package module
Version: v1.0.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Jul 26, 2017 License: MIT Imports: 5 Imported by: 75



Consistent hash package for Go.


go get


Look at the godoc.


This package was extracted from production code powering StatHat, so clearly we feel that it is production-ready, but it should still be considered experimental as other uses of it could reveal issues we aren't experiencing.

Contact us

We'd love to hear from you if you are using consistent. Get in touch: @stathat or contact us here.


Written by Patrick Crosby at StatHat. Twitter: @stathat



Package consistent provides a consistent hashing function.

Consistent hashing is often used to distribute requests to a changing set of servers. For example, say you have some cache servers cacheA, cacheB, and cacheC. You want to decide which cache server to use to look up information on a user.

You could use a typical hash table and hash the user id to one of cacheA, cacheB, or cacheC. But with a typical hash table, if you add or remove a server, almost all keys will get remapped to different results, which basically could bring your service to a grinding halt while the caches get rebuilt.

With a consistent hash, adding or removing a server drastically reduces the number of keys that get remapped.

Read more about consistent hashing on wikipedia:




This section is empty.


View Source
var ErrEmptyCircle = errors.New("empty circle")

ErrEmptyCircle is the error returned when trying to get an element when nothing has been added to hash.


This section is empty.


type Consistent

type Consistent struct {
	NumberOfReplicas int

	// contains filtered or unexported fields

Consistent holds the information about the members of the consistent hash circle.

func New

func New() *Consistent

New creates a new Consistent object with a default setting of 20 replicas for each entry.

To change the number of replicas, set NumberOfReplicas before adding entries.

package main

import (


func main() {
	c := consistent.New()
	users := []string{"user_mcnulty", "user_bunk", "user_omar", "user_bunny", "user_stringer"}
	for _, u := range users {
		server, err := c.Get(u)
		if err != nil {
		fmt.Printf("%s => %s\n", u, server)

user_mcnulty => cacheA
user_bunk => cacheA
user_omar => cacheA
user_bunny => cacheC
user_stringer => cacheC

func (*Consistent) Add

func (c *Consistent) Add(elt string)

Add inserts a string element in the consistent hash.

func (*Consistent) Get

func (c *Consistent) Get(name string) (string, error)

Get returns an element close to where name hashes to in the circle.

func (*Consistent) GetN

func (c *Consistent) GetN(name string, n int) ([]string, error)

GetN returns the N closest distinct elements to the name input in the circle.

func (*Consistent) GetTwo

func (c *Consistent) GetTwo(name string) (string, string, error)

GetTwo returns the two closest distinct elements to the name input in the circle.

func (*Consistent) Members

func (c *Consistent) Members() []string

func (*Consistent) Remove

func (c *Consistent) Remove(elt string)

Remove removes an element from the hash.

func (*Consistent) Set

func (c *Consistent) Set(elts []string)

Set sets all the elements in the hash. If there are existing elements not present in elts, they will be removed.

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL