hashring

README

hashring

Implements consistent hashing that can be used when the number of server nodes can increase or decrease (like in memcached). The hashing ring is built using the same algorithm as libketama.

This is a port of Python hash_ring library https://pypi.python.org/pypi/hash_ring/ in Go with the extra methods to add and remove nodes.

Using

Importing ::

import "github.com/serialx/hashring"

Basic example usage ::

memcacheServers := []string{"192.168.0.246:11212",
                            "192.168.0.247:11212",
                            "192.168.0.249:11212"}

ring := hashring.New(memcacheServers)
server, _ := ring.GetNode("my_key")

To fulfill replication requirements, you can also get a list of servers that should store your key.

serversInRing := []string{"192.168.0.246:11212",
                          "192.168.0.247:11212",
                          "192.168.0.248:11212",
                          "192.168.0.249:11212",
                          "192.168.0.250:11212",
                          "192.168.0.251:11212",
                          "192.168.0.252:11212"}

replicaCount := 3
ring := hashring.New(serversInRing)
server, _ := ring.GetNodes("my_key", replicaCount)

Using weights example ::

weights := make(map[string]int)
weights["192.168.0.246:11212"] = 1
weights["192.168.0.247:11212"] = 2
weights["192.168.0.249:11212"] = 1

ring := hashring.NewWithWeights(weights)
server, _ := ring.GetNode("my_key")

Adding and removing nodes example ::

memcacheServers := []string{"192.168.0.246:11212",
                            "192.168.0.247:11212",
                            "192.168.0.249:11212"}

ring := hashring.New(memcacheServers)
ring = ring.RemoveNode("192.168.0.246:11212")
ring = ring.AddNode("192.168.0.250:11212")
server, _ := ring.GetNode("my_key")

Documentation

Index

• type HashFunc
• type HashKey
  • func NewInt64PairHashKey(bytes []byte) (HashKey, error)
• type HashKeyOrder
  • func (h HashKeyOrder) Len() int
  • func (h HashKeyOrder) Less(i, j int) bool
  • func (h HashKeyOrder) Swap(i, j int)
• type HashRing
  • func New(nodes []string) *HashRing
  • func NewWithHash(nodes []string, hashKey HashFunc) *HashRing
  • func NewWithHashAndWeights(weights map[string]int, hashFunc HashFunc) *HashRing
  • func NewWithWeights(weights map[string]int) *HashRing
  • func (h *HashRing) AddNode(node string) *HashRing
  • func (h *HashRing) AddWeightedNode(node string, weight int) *HashRing
  • func (h *HashRing) GenKey(key string) HashKey
  • func (h *HashRing) GetNode(stringKey string) (node string, ok bool)
  • func (h *HashRing) GetNodePos(stringKey string) (pos int, ok bool)
  • func (h *HashRing) GetNodes(stringKey string, size int) (nodes []string, ok bool)
  • func (h *HashRing) RemoveNode(node string) *HashRing
  • func (h *HashRing) Size() int
  • func (h *HashRing) UpdateWeightedNode(node string, weight int) *HashRing
  • func (h *HashRing) UpdateWithWeights(weights map[string]int)
• type HashSum
  • func NewHash(hasher func() hash.Hash) *HashSum
  • func (r *HashSum) FirstBytes(n int) *HashSum
  • func (r *HashSum) LastBytes(n int) *HashSum
  • func (r *HashSum) Use(hashKeyFunc func(bytes []byte) (HashKey, error)) (HashFunc, error)
• type Int64PairHashKey
  • func (k *Int64PairHashKey) Less(other HashKey) bool
• type Uint32HashKey
  • func (k Uint32HashKey) Less(other HashKey) bool

Types

type HashFunc

type HashFunc func([]byte) HashKey

type HashKey

type HashKey interface {
	Less(other HashKey) bool
}

func NewInt64PairHashKey

func NewInt64PairHashKey(bytes []byte) (HashKey, error)

type HashKeyOrder

type HashKeyOrder []HashKey

func (HashKeyOrder) Len

func (h HashKeyOrder) Len() int

func (HashKeyOrder) Less

func (h HashKeyOrder) Less(i, j int) bool

func (HashKeyOrder) Swap

func (h HashKeyOrder) Swap(i, j int)

type HashRing

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

func New

func New(nodes []string) *HashRing

func NewWithHash

func NewWithHash(
	nodes []string,
	hashKey HashFunc,
) *HashRing

func NewWithHashAndWeights

func NewWithHashAndWeights(
	weights map[string]int,
	hashFunc HashFunc,
) *HashRing

func NewWithWeights

func NewWithWeights(weights map[string]int) *HashRing

func (*HashRing) AddNode

func (h *HashRing) AddNode(node string) *HashRing

func (*HashRing) AddWeightedNode

func (h *HashRing) AddWeightedNode(node string, weight int) *HashRing

func (*HashRing) GenKey

func (h *HashRing) GenKey(key string) HashKey

func (*HashRing) GetNode

func (h *HashRing) GetNode(stringKey string) (node string, ok bool)

func (*HashRing) GetNodePos

func (h *HashRing) GetNodePos(stringKey string) (pos int, ok bool)

func (*HashRing) GetNodes

func (h *HashRing) GetNodes(stringKey string, size int) (nodes []string, ok bool)

GetNodes iterates over the hash ring and returns the nodes in the order which is determined by the key. GetNodes is thread safe if the hash which was used to configure the hash ring is thread safe.

func (*HashRing) RemoveNode

func (h *HashRing) RemoveNode(node string) *HashRing

func (*HashRing) Size

func (h *HashRing) Size() int

func (*HashRing) UpdateWeightedNode

func (h *HashRing) UpdateWeightedNode(node string, weight int) *HashRing

func (*HashRing) UpdateWithWeights

func (h *HashRing) UpdateWithWeights(weights map[string]int)

type HashSum

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

HashSum allows to use a builder pattern to create different HashFunc objects. See examples for details.

func NewHash

func NewHash(hasher func() hash.Hash) *HashSum

NewHash creates a new *HashSum object which can be used to create HashFunc. HashFunc object is thread safe if the hasher argument produces a new hash.Hash each time. The produced hash.Hash is allowed to be non thread-safe.

func (*HashSum) FirstBytes

func (r *HashSum) FirstBytes(n int) *HashSum

func (*HashSum) LastBytes

func (r *HashSum) LastBytes(n int) *HashSum

func (*HashSum) Use

func (r *HashSum) Use(
	hashKeyFunc func(bytes []byte) (HashKey, error),
) (HashFunc, error)

type Int64PairHashKey

type Int64PairHashKey struct {
	High int64
	Low  int64
}

func (*Int64PairHashKey) Less

func (k *Int64PairHashKey) Less(other HashKey) bool

type Uint32HashKey

type Uint32HashKey uint32

func (Uint32HashKey) Less

func (k Uint32HashKey) Less(other HashKey) bool