consistent-hashing

A lightweight and concurrency-safe consistent hashing implementation in Go, with support for replication and virtual nodes.

Check out this video to learn about Consistent Hashing.

Installation

go get https://github.com/zuzuleinen/consistent-hashing

Then use it in your project:

import "github.com/zuzuleinen/consistent-hashing"

Usage

Basic usage:

	ch := consistenthashing.NewConsistentHashing()

	ch.Add("host-1")
	ch.Add("host-2")
	ch.Add("host-3")

	matchedHosts, err := ch.Get("customer-id-1")

If ch is constructed without any options, it will always match exactly one host.

Enable virtual nodes:

    ch := consistenthashing.NewConsistentHashing(
        consistenthashing.WithVirtualNodes(100),
    )

In this case, each primary host receives 100 virtual nodes each.

Enable replication:

    ch := consistenthashing.NewConsistentHashing(
        consistenthashing.WithReplicationFactor(2),
    )

    ch.Add("host-1")
    ch.Add("host-2")
    ch.Add("host-3")

    matchedHosts, err := ch.Get("customer-id-1")

WithReplicationFactor allows you to pass a replication factor R.

When R > 1 a key will be saved in R matchedHosts nodes instead of just one. In our example len(matchedHosts) == 2.

If R is bigger than the number of primary hosts, it will be capped to no. of primary hosts.

Customize hash function

By default, the library uses a 32 bit FNV-1a by default, but you can use your own custom function using:

	ch := consistenthashing.NewConsistentHashing(
		consistenthashing.WithHashFunc(YourCustomHashFunction),
	)

Contributing

Feel free to open an issue or e-mail me at andrey.boar[at]gmail.com.

If you want to keep in touch, connect with me on LinkedIn.