github.com/blend/go-sdk@v1.20220411.3/consistenthash/doc.go (about)

     1  /*
     2  
     3  Copyright (c) 2022 - Present. Blend Labs, Inc. All rights reserved
     4  Use of this source code is governed by a MIT license that can be found in the LICENSE file.
     5  
     6  */
     7  
     8  /*
     9  Package consistenthash contains helpers for mapping items to buckets using consistent hashing.
    10  
    11  Methods (AddBucket, Assignment etc.) typically run in `log2(N*M)` time where N is the number
    12  of buckets and M is the number of virtual replicas in use (which defaults to 16).
    13  This is strictly worse than a typical map, but avoids space issues with tracking item
    14  assignments individually.
    15  
    16  The default hash function is `crc64.ChecksumIEEE` but that can be customized. The default hash
    17  function is seeded with a constant polynomial so that assignments are stable between process starts.
    18  
    19  A `*consistenthash.ConsistentHash` reference (the result of `New(...)`) is safe to use
    20  from multiple goroutines and will use a read/write mutex to synchronize changes to internal state.
    21  
    22  Example usage:
    23  
    24      ch := consistenthash.New(
    25  		consistenthash.OptBuckets("worker-0", "worker-1", "worker-2"),
    26  	)
    27  	// figure out which bucket an item maps to
    28  	worker := ch.Assignment("item-0") // will yield `worker-0` or `worker-1` etc.
    29  
    30  You can tune the number of virtual replicas to reduce the constant time hit of most operations
    31  at the expense of bucket to item mapping uniformity.
    32  
    33  Example setting the replicas:
    34  
    35      ch := consistenthash.New(
    36  		consistenthash.OptBuckets("worker-0", "worker-1", "worker-2"),
    37  		consistenthash.OptReplicas(5),
    38  	)
    39  	// figure out which bucket an item maps to
    40  	worker := ch.Assignment("item-0") // will yield `worker-0` or `worker-1` etc.
    41  
    42  */
    43  package consistenthash // import "github.com/blend/go-sdk/consistenthash"