Documentation ¶
Overview ¶
Package consistent provides a consistent hashing function with bounded loads. This implementation also adds partitioning logic on top of the original algorithm. 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{}, }
Now you can create a new Consistent instance. This function can take a list of the members.
c := consistent.New(members, cfg)
In the following sample, you add a new Member to the consistent hash ring. myMember is just a Go struct that implements the Member interface. You should know that modifying the consistent hash ring distributes partitions among members using the algorithm defined on Google Research Blog.
c.Add(myMember)
Remove a member from the consistent hash ring:
c.Remove(member-name)
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 that is responsible for the key.
key := []byte("my-key") member := c.LocateKey(key)
Index ¶
- Constants
- 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 ¶
const ( DefaultPartitionCount int = 271 DefaultReplicationFactor int = 20 DefaultLoad float64 = 1.25 )
Variables ¶
var ErrInsufficientMemberCount = errors.New("insufficient member count")
ErrInsufficientMemberCount represents an error which means there are not enough members to complete the task.
Functions ¶
This section is empty.
Types ¶
type Config ¶
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 ¶
type Consistent struct {
// contains filtered or unexported fields
}
Consistent holds the information about the members of the consistent hash circle.
func New ¶
func New(members []Member, config Config) *Consistent
New creates and returns a new Consistent object.
func (*Consistent) Add ¶
func (c *Consistent) Add(member Member)
Add adds a new member to the consistent hash circle.
func (*Consistent) AverageLoad ¶
func (c *Consistent) AverageLoad() float64
AverageLoad exposes the current average load.
func (*Consistent) FindPartitionID ¶
func (c *Consistent) FindPartitionID(key []byte) int
FindPartitionID returns partition id for given key.
func (*Consistent) GetClosestN ¶
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 ¶
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 ¶
func (c *Consistent) GetMembers() []Member
GetMembers returns a thread-safe copy of members. If there are no members, it returns an empty slice of Member.
func (*Consistent) GetPartitionOwner ¶
func (c *Consistent) GetPartitionOwner(partID int) Member
GetPartitionOwner returns the owner of the given partition.
func (*Consistent) LoadDistribution ¶
func (c *Consistent) LoadDistribution() map[string]float64
LoadDistribution exposes load distribution of members.
func (*Consistent) LocateKey ¶
func (c *Consistent) LocateKey(key []byte) Member
LocateKey finds a home for given key
func (*Consistent) Remove ¶
func (c *Consistent) Remove(name string)
Remove removes a member from the consistent hash circle.