Documentation
¶
Overview ¶
Package hash provides a consistent hashing function with bounded loads. For more information about the underlying algorithm, please take a look at https://research.googleblog.com/2017/04/consistent-hashing-with-bounded-loads.html
Example Use:
cfg := consistent.Config{
PartitionCount: 71,
ReplicationFactor: 20,
Load: 1.25,
Hasher: hasher{},
}
// Create a new consistent object
// You may call this with a list of members
// instead of adding them one by one.
c := consistent.New(members, cfg)
// myMember struct just needs to implement a String method.
// New/Add/Remove distributes partitions among members using the algorithm
// defined on Google Research Blog.
c.Add(myMember)
key := []byte("my-key")
// LocateKey hashes the key and calculates partition ID with
// this modulo operation: MOD(hash result, partition count)
// The owner of the partition is already calculated by New/Add/Remove.
// LocateKey just returns the member which's responsible for the key.
member := c.LocateKey(key)
We optimized this hash algorithm and improved the problem of panic in borderline cases mentioned in this issue: https://github.com/buraksezer/consistent/issues/13
Index ¶
- Variables
- type Config
- type Consistent
- func (c *Consistent) Add(member Member)
- func (c *Consistent) AverageLoad() float64
- func (c *Consistent) FindPartitionID(key []byte) int
- func (c *Consistent) GetClosestN(key []byte, count int) ([]Member, error)
- func (c *Consistent) GetClosestNForPartition(partID, count int) ([]Member, error)
- func (c *Consistent) GetMembers() []Member
- func (c *Consistent) GetPartitionOwner(partID int) Member
- func (c *Consistent) LoadDistribution() map[string]float64
- func (c *Consistent) LocateKey(key []byte) Member
- func (c *Consistent) Remove(name string)
- type Hasher
- type Member
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInsufficientMemberCount represents an error which means there are not enough members to complete the task. ErrInsufficientMemberCount = errors.New("insufficient member count") // ErrMemberNotFound represents an error which means requested member could not be found in consistent hash ring. ErrMemberNotFound = errors.New("member could not be found in ring") )
Functions ¶
This section is empty.
Types ¶
type Config ¶ added in v1.2.5
type Config struct {
// Hasher is responsible for generating unsigned, 64 bit hash of provided byte slice.
Hasher Hasher
// Keys are distributed among partitions. Prime numbers are good to
// distribute keys uniformly. Select a big PartitionCount if you have
// too many keys.
PartitionCount int
// Members are replicated on consistent hash ring. This number means that a member
// how many times replicated on the ring.
ReplicationFactor int
// Load is used to calculate average load. See the code, the paper and Google's blog post to learn about it.
Load float64
}
Config represents a structure to control consistent package.
type Consistent ¶ added in v1.2.5
type Consistent struct {
// contains filtered or unexported fields
}
Consistent holds the information about the members of the consistent hash circle.
func NewUniformityHash ¶ added in v1.2.5
func NewUniformityHash(members []Member, config Config) *Consistent
NewUniformityHash creates and returns a new Consistent object.
func (*Consistent) Add ¶ added in v1.2.5
func (c *Consistent) Add(member Member)
Add adds a new member to the consistent hash circle.
func (*Consistent) AverageLoad ¶ added in v1.2.5
func (c *Consistent) AverageLoad() float64
AverageLoad exposes the current average load.
func (*Consistent) FindPartitionID ¶ added in v1.2.5
func (c *Consistent) FindPartitionID(key []byte) int
FindPartitionID returns partition id for given key.
func (*Consistent) GetClosestN ¶ added in v1.2.5
func (c *Consistent) GetClosestN(key []byte, count int) ([]Member, error)
GetClosestN returns the closest N member to a key in the hash ring. This may be useful to find members for replication.
func (*Consistent) GetClosestNForPartition ¶ added in v1.2.5
func (c *Consistent) GetClosestNForPartition(partID, count int) ([]Member, error)
GetClosestNForPartition returns the closest N member for given partition. This may be useful to find members for replication.
func (*Consistent) GetMembers ¶ added in v1.2.5
func (c *Consistent) GetMembers() []Member
GetMembers returns a thread-safe copy of members.
func (*Consistent) GetPartitionOwner ¶ added in v1.2.5
func (c *Consistent) GetPartitionOwner(partID int) Member
GetPartitionOwner returns the owner of the given partition.
func (*Consistent) LoadDistribution ¶ added in v1.2.5
func (c *Consistent) LoadDistribution() map[string]float64
LoadDistribution exposes load distribution of members.
func (*Consistent) LocateKey ¶ added in v1.2.5
func (c *Consistent) LocateKey(key []byte) Member
LocateKey finds a home for given key
func (*Consistent) Remove ¶ added in v1.2.5
func (c *Consistent) Remove(name string)
Remove removes a member from the consistent hash circle.
type Hasher ¶ added in v1.2.5
Hasher is responsible for generating unsigned, 64 bit hash of provided byte slice. Hasher should minimize collisions (generating same hash for different byte slice) and while performance is also important fast functions are preferable (i.e. you can use FarmHash family).
Source Files