Module machi_chash

Consistent hashing library.

Description

Consistent hashing library. Also known as "random slicing".

This code was originally from the Hibari DB source code at https://github.com/hibari

Data Types

float_map()

float_map() = [{owner_name(), float()}]

A float map subdivides the unit interval, starting at 0.0, to partitions that are assigned to various owners. The sum of all floats must be exactly 1.0 (or close enough for floating point purposes).

float_tree()

abstract datatype: float_tree()

We can't use gb_trees:tree() because 'nil' (the empty tree) is never valid in our case. But teaching Dialyzer that is difficult.

nextfloat_list()

nextfloat_list() = [{float(), brick()}]

A nextfloat_list differs from a float_map in two respects: 1) nextfloat_list contains tuples with the brick name in 2nd position, 2) the float() at each position I_n > I_m, for all n, m such that n > m. For example, a nextfloat_list of the float_map example above, [{0.25, {br1, nd1}}, {0.75, {br2, nd1}}, {1.0, {br3, nd1}].

owner_int_range()

owner_int_range() = {owner_name(), non_neg_integer(), non_neg_integer()}

Used when "prettying" a float map.

owner_name()

owner_name() = term()

Owner for a range on the unit interval. We are agnostic about its type.

owner_weight()

owner_weight() = {owner_name(), weight()}

owner_weight_list()

owner_weight_list() = [owner_weight()]

A owner_weight_list is a definition of brick assignments over the unit interval [0.0, 1.0]. The sum of all floats must be 1.0. For example, [{{br1,nd1}, 0.25}, {{br2,nd1}, 0.5}, {{br3,nd1}, 0.25}].

weight()

weight() = non_neg_integer()

For this library, a weight is an integer which specifies the capacity of a "owner" relative to other owners. For example, if owner A with a weight of 10, and if owner B has a weight of 20, then B will be assigned twice as much of the unit interval as A.

Function Index

hash_binary_via_float_map/2Query a float map with a binary (inefficient).
hash_binary_via_float_tree/2Query a float tree with a binary.
make_demo_map1/0Create a sample float map.
make_demo_map2/0Create a sample float map.
make_float_map/1Create a float map, based on a basic owner weight list.
make_float_map/2Create a float map, based on an older float map and a new weight list.
make_tree/1Create a float tree, which is the rapid lookup data structure for consistent hash queries.
pretty_with_integers/2Make a pretty/human-friendly version of a float map that describes integer ranges between 1 and Scale.
pretty_with_integers/3Make a pretty/human-friendly version of a float map (based upon a float map created from OldWeights and NewWeights) that describes integer ranges between 1 and Scale.
query_tree/2Low-level function for querying a float tree: the (floating point) point within the unit interval.
sum_map_weights/1Create a human-friendly summary of a float map.
zzz_usage_details/0Various usage examples, see source code below this function for full details.

Function Details

hash_binary_via_float_map/2

hash_binary_via_float_map(Key::binary(), Map::float_map()) -> {float(), owner_name()}

Query a float map with a binary (inefficient).

hash_binary_via_float_tree/2

hash_binary_via_float_tree(Key::binary(), Tree::float_tree()) -> {float(), owner_name()}

Query a float tree with a binary.

make_demo_map1/0

make_demo_map1() -> float_map()

Create a sample float map.

make_demo_map2/0

make_demo_map2() -> float_map()

Create a sample float map.

make_float_map/1

make_float_map(NewOwnerWeights::owner_weight_list()) -> float_map()

Create a float map, based on a basic owner weight list.

make_float_map/2

make_float_map(OldFloatMap::float_map(), NewOwnerWeights::owner_weight_list()) -> float_map()

Create a float map, based on an older float map and a new weight list.

The weights in the new weight list may be different than (or the same as) whatever weights were used to make the older float map.

make_tree/1

make_tree(Map::float_map()) -> float_tree()

Create a float tree, which is the rapid lookup data structure for consistent hash queries.

pretty_with_integers/2

pretty_with_integers(Map::float_map(), Scale::integer()) -> [owner_int_range()]

Make a pretty/human-friendly version of a float map that describes integer ranges between 1 and Scale.

pretty_with_integers/3

pretty_with_integers(OldWeights::owner_weight_list(), NewWeights::owner_weight_list(), Scale::integer()) -> [owner_int_range()]

Make a pretty/human-friendly version of a float map (based upon a float map created from OldWeights and NewWeights) that describes integer ranges between 1 and Scale.

query_tree/2

query_tree(Val::float(), Tree::float_tree()) -> {float(), owner_name()}

Low-level function for querying a float tree: the (floating point) point within the unit interval.

sum_map_weights/1

sum_map_weights(Map::float_map()) -> {{per_owner, float_map()}, {weight_sum, float()}}

Create a human-friendly summary of a float map.

The two parts of the summary are: a per-owner total of the unit interval range(s) owned by each owner, and a total sum of all per-owner ranges (which should be 1.0 but is not enforced).

zzz_usage_details/0

zzz_usage_details() -> any()

Various usage examples, see source code below this function for full details.


Generated by EDoc, May 20 2015, 12:58:33.