consistenthash

Documentation

Index

• Constants
• func StableHash(data []byte) uint64
• type ConsistentHash
  • func New(opts ...Option) *ConsistentHash
  • func (ch *ConsistentHash) AddBuckets(newBuckets ...string) (ok bool)
  • func (ch *ConsistentHash) Assignment(item string) (bucket string)
  • func (ch *ConsistentHash) Assignments(items ...string) map[string][]string
  • func (ch *ConsistentHash) Buckets() (buckets []string)
  • func (ch *ConsistentHash) HashFunction() HashFunction
  • func (ch *ConsistentHash) IsAssigned(bucket, item string) (ok bool)
  • func (ch *ConsistentHash) MarshalJSON() ([]byte, error)
  • func (ch *ConsistentHash) RemoveBucket(toRemove string) (ok bool)
  • func (ch *ConsistentHash) Replicas() int
  • func (ch *ConsistentHash) String() string
• type HashFunction
• type HashedBucket
• type Option
  • func OptHashFunction(hashFunction HashFunction) Option
  • func OptReplicas(replicas int) Option
• type Options

Constants

const (
	// DefaultReplicas is the default number of bucket virtual replicas.
	DefaultReplicas = 16
)

Functions

func StableHash

func StableHash(data []byte) uint64

StableHash implements the default hash function with a stable crc64 table checksum.

Types

type ConsistentHash

type ConsistentHash struct {
	// contains filtered or unexported fields
}

ConsistentHash creates hashed assignments for each bucket.

You _must_ use `New` to parameterize ConsistentHash beyond the defaults for `replicas` and `hashFunction`.

This is done because these parameters if changed after data has been added will lead to inconsistent behavior.

func New

func New(opts ...Option) *ConsistentHash

New creates a new consistent hash instance.

func (*ConsistentHash) AddBuckets

func (ch *ConsistentHash) AddBuckets(newBuckets ...string) (ok bool)

AddBuckets adds a list of buckets to the consistent hash, and returns a boolean indiciating if _any_ buckets were added.

If any of the new buckets do not exist on the hash ring the new bucket will be inserted `ReplicasOrDefault` number of times into the internal hashring.

If any of the new buckets already exist on the hash ring no action is taken for that bucket (it's effectively skipped).

Calling `AddBuckets` is safe to do concurrently and acquires a write lock on the consistent hash reference.

func (*ConsistentHash) Assignment

func (ch *ConsistentHash) Assignment(item string) (bucket string)

Assignment returns the bucket assignment for a given item.

Calling `Assignment` is safe to do concurrently and acquires a read lock on the consistent hash reference.

func (*ConsistentHash) Assignments

func (ch *ConsistentHash) Assignments(items ...string) map[string][]string

Assignments returns the assignments for a given list of items organized by the name of the bucket, and an array of the assigned items.

Calling `Assignments` is safe to do concurrently and acquires a read lock on the consistent hash reference.

func (*ConsistentHash) Buckets

func (ch *ConsistentHash) Buckets() (buckets []string)

Buckets returns the buckets.

Calling `Buckets` is safe to do concurrently and acquires a read lock on the consistent hash reference.

func (*ConsistentHash) HashFunction

func (ch *ConsistentHash) HashFunction() HashFunction

HashFunction returns the provided hash function or a default.

func (*ConsistentHash) IsAssigned

func (ch *ConsistentHash) IsAssigned(bucket, item string) (ok bool)

IsAssigned returns if a given bucket is assigned a given item.

Calling `IsAssigned` is safe to do concurrently and acquires a read lock on the consistent hash reference.

func (*ConsistentHash) MarshalJSON

func (ch *ConsistentHash) MarshalJSON() ([]byte, error)

MarshalJSON marshals the consistent hash as json.

The form of the returned json is the underlying []HashedBucket and there is no corresponding `UnmarshalJSON` because it is uncertain on the other end what the hashfunction is because functions can't be json serialized.

You should use MarshalJSON for communicating information for debugging purposes only.

Calling `MarshalJSON` is safe to do concurrently and acquires a read lock on the consistent hash reference.

func (*ConsistentHash) RemoveBucket

func (ch *ConsistentHash) RemoveBucket(toRemove string) (ok bool)

RemoveBucket removes a bucket from the consistent hash, and returns a boolean indicating if the provided bucket was found.

If the bucket exists on the hash ring, the bucket and its replicas are removed.

If the bucket does not exist on the ring, no action is taken.

Calling `RemoveBucket` is safe to do concurrently and acquires a write lock on the consistent hash reference.

func (*ConsistentHash) Replicas

func (ch *ConsistentHash) Replicas() int

Replicas is the default number of bucket virtual replicas.

func (*ConsistentHash) String

func (ch *ConsistentHash) String() string

String returns a string form of the hash for debugging purposes.

Calling `String` is safe to do concurrently and acquires a read lock on the consistent hash reference.

type HashFunction

type HashFunction func([]byte) uint64

HashFunction is a function that can be used to hash items.

type HashedBucket

type HashedBucket struct {
	Hashcode uint64 `json:"hashcode"`
	Bucket   string `json:"bucket"`
	Replica  int    `json:"replica"`
}

HashedBucket is a bucket in the hashring that holds the hashcode, the bucket name (as Bucket) and the virtual replica index.

type Option

type Option func(*Options)

Option mutates options.

func OptHashFunction

func OptHashFunction(hashFunction HashFunction) Option

OptReplicas sets the replicas on options.

func OptReplicas

func OptReplicas(replicas int) Option

OptReplicas sets the replicas on options.

type Options

type Options struct {
	Replicas     int
	HashFunction HashFunction
}

Options are the options for the consistent hash type.