whitfin / jumper

Jump consistent hash implementation in Elixir (without NIFs)

Jumper

Installation

Jumper is available on Hex. You can install the package by adding it to your dependencies in mix.exs:

def deps do
 [{:jumper, "~> 1.0"}]
end

Usage

Using Jumper is pretty trivial; there is a single API used to slot keys into a range of buckets:

iex> Jumper.slot(256, 1024)
520

The first argument is the key, and the second is the number of buckets the key can be slotted into. The result is the bucket the key should be routed to. Both the key and the bucket count should be valid integers. If you want to check a non-integer key, you could always use :erlang.phash2/1 to generate a hash code for the value:

iex> %{} |> :erlang.phash2 |> Jumper.slot(1024)
29

Benchmarks

There are some very trivial benchmarks available using Benchee in the benchmarks/ directory. You can run the benchmarks using the following command:

$ mix bench

Typical results are a microsecond or two, based on the number of buckets you're trying to slot into (scales to the number of buckets).

Contributions

If you feel something can be improved, or have any questions about certain behaviours or pieces of implementation, please feel free to file an issue. Proposed changes should be taken to issues before any PRs to avoid wasting time on code which might not be merged upstream.

If you do make changes to the codebase, please make sure you test your changes thoroughly, and include any unit tests alongside new or changed behaviours. jumper currently uses the excellent excoveralls to track code coverage.

$ mix test
$ mix credo
$ mix coveralls
$ mix coveralls.html && open cover/excoveralls.html