ExHashRing.Ring (ex_hash_ring v6.0.4) View Source

A pure Elixir consistent hash ring.

Ring data is stored in an ETS table owned by the ExHashRing.Ring GenServer. This module provides functions for managing and querying a consistent hash ring quickly and efficiently.

Link to this section Summary

Types

depth()

Rings maintain a history, the history is limited to depth number of generations to retain.

generation()

Generations act as a grouping mechanism to associate many records together as one logical and atomic group.

key()

Any hashable key can be looked up in the ring to find the nodes that own that key.

name()

Rings are named with a unique atom.

option()

Union type that represents all valid options

option_depth()

Option that controls the number of generations to retain for lookup.

option_name()

Option that controls the name to register this process under, Rings that are registered can use their name in place of their pid.

option_nodes()

Option that controls the initial nodes for the Ring.

option_overrides()

Option that controls the initial overrides for the Ring.

option_replicas()

Option that controls the number of replicas to use for nodes that do not define replicas.

options()

List of options that can be provided when starting a Ring, see the option/0 type and its associated types for more information.

overrides()

Overrides allow the Ring to always resolve a given key to a set list of nodes.

ring()

Several functions accept either a name for a named Ring or a pid for an anonymous Ring

size()

Ring size is a memoized count of the number of logical nodes in a ring

t()

Functions

add_node(ring, node_name, num_replicas \\ nil)

Adds a node to the existing set of nodes in the ring.

add_nodes(ring, nodes)

Adds multiple nodes to the existing set of nodes in the ring.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

do_find_stable_nodes(key, hash, num, back, info)

find_historical_node(ring, key, back)

find_historical_nodes(ring, key, num, back)

Finds the specified number of nodes responsible for the given key in the specified ring's history, going back back number of generations.

find_node(ring, key)

Finds the node responsible for the given key in the specified ring.

find_nodes(ring, key, num)

Finds the specified number of nodes responsible for the given key in the specified ring's current generation.

find_stable_nodes(ring, key, num)

Finds the specificed number of nodes responsible for the given key by looking at each generation in the ring's configured depth. See find_stable_nodes/4 for more information.

find_stable_nodes(ring, key, num, back)

Finds the specified number of nodes responsible for the given key in the specified ring's current generation and in the history of the ring. This means that this function returns up to back * num; where num = number of nodes requested, and back = the number of generations to consider.

force_gc(ring)

Forces a garbage collection of any generations that are pending garbage collection. Returns the generations that were collected.

force_gc(ring, generation)

Forces a garbage collection of a specific generation, the generation must be pending or else {:error, :not_pending} is returned.

get_generation(ring)

Get the current ring generation

get_nodes(ring)

Retrieves the current set of node names from the ring.

get_nodes_with_replicas(ring)

Retrieves the current set of nodes as tuples of {name, replicas} from the ring.

get_overrides(ring)

Retrieves the current set of overrides from the ring.

get_pending_gcs(ring)

Retrieves a list of pending gc generations.

init(options)

Callback implementation for GenServer.init/1.

remove_node(ring, name)

Removes a node from the ring by its name.

remove_nodes(ring, names)

Atomically remove multiple nodes from the ring by name

set_nodes(ring, nodes)

Replaces the nodes in the ring with a new set of nodes.

set_overrides(ring, overrides)

Replaces the overrides in the ring with new overrides.

start_link(options \\ [])

Start and link a Ring with the given name.

stop(name)

Stops the GenServer holding the Ring.

Link to this section Types

depth()

Specs

depth() :: pos_integer()

Rings maintain a history, the history is limited to depth number of generations to retain.

generation()

Specs

generation() :: integer()

Generations act as a grouping mechanism to associate many records together as one logical and atomic group.

key()

Specs

key() :: ExHashRing.Hash.hashable()

Any hashable key can be looked up in the ring to find the nodes that own that key.

name()

Specs

name() :: atom()

Rings are named with a unique atom.

option()

Specs

option() ::
  option_depth()
  | option_name()
  | option_nodes()
  | option_overrides()
  | option_replicas()

Union type that represents all valid options

option_depth()

Specs

option_depth() :: {:depth, depth()}

Option that controls the number of generations to retain for lookup.

Defaults to 1

option_name()

Specs

option_name() :: {:name, name()}

Option that controls the name to register this process under, Rings that are registered can use their name in place of their pid.

Defaults behavior is to not register the Ring process.

option_nodes()

Specs

option_nodes() :: {:nodes, [ExHashRing.Node.definition()]}

Option that controls the initial nodes for the Ring.

Defaults to []

option_overrides()

Specs

option_overrides() :: {:overrides, overrides()}

Option that controls the initial overrides for the Ring.

Defaults to %{}

option_replicas()

Specs

option_replicas() :: {:replicas, ExHashRing.Node.replicas()}

Option that controls the number of replicas to use for nodes that do not define replicas.

Defaults to 512

options()

Specs

options() :: [option()]

List of options that can be provided when starting a Ring, see the option/0 type and its associated types for more information.

overrides()

Specs

overrides() :: %{required(key()) => [ExHashRing.Node.name()]}

Overrides allow the Ring to always resolve a given key to a set list of nodes.

ring()

Specs

ring() :: name() | pid()

Several functions accept either a name for a named Ring or a pid for an anonymous Ring

size()

Specs

size() :: non_neg_integer()

Ring size is a memoized count of the number of logical nodes in a ring

t()

Specs

t() :: %ExHashRing.Ring{
  depth: depth(),
  generation: generation(),
  nodes: [ExHashRing.Node.t()],
  overrides: overrides(),
  pending_gcs: %{required(generation()) => reference()},
  replicas: ExHashRing.Node.replicas(),
  sizes: [size()],
  table: :ets.tid()
}

Link to this section Functions

add_node(ring, node_name, num_replicas \\ nil)

Specs

add_node(ring(), ExHashRing.Node.name(), ExHashRing.Node.replicas() | nil) ::
  {:ok, [ExHashRing.Node.t()]} | {:error, :node_exists}

Adds a node to the existing set of nodes in the ring.

add_nodes(ring, nodes)

Specs

add_nodes(ring(), nodes :: [ExHashRing.Node.definition()]) ::
  {:ok, [ExHashRing.Node.t()]} | {:error, :node_exists}

Adds multiple nodes to the existing set of nodes in the ring.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

do_find_stable_nodes(key, hash, num, back, info)

Specs

do_find_stable_nodes(
  key(),
  hash :: ExHashRing.Hash.t(),
  num :: non_neg_integer(),
  back :: non_neg_integer(),
  info :: ExHashRing.Info.entry()
) :: {:ok, [ExHashRing.Node.name()]} | {:error, atom()}

find_historical_node(ring, key, back)

Specs

find_historical_node(ring(), key(), back :: non_neg_integer()) ::
  {:ok, ExHashRing.Node.name()} | {:error, atom()}

find_historical_nodes(ring, key, num, back)

Specs

find_historical_nodes(
  ring(),
  key(),
  num :: non_neg_integer(),
  back :: non_neg_integer()
) :: {:ok, [ExHashRing.Node.name()]} | {:error, atom()}

Finds the specified number of nodes responsible for the given key in the specified ring's history, going back back number of generations.

find_node(ring, key)

Specs

find_node(ring(), key()) :: {:ok, ExHashRing.Node.name()} | {:error, atom()}

Finds the node responsible for the given key in the specified ring.

find_nodes(ring, key, num)

Specs

find_nodes(ring(), key(), num :: non_neg_integer()) ::
  {:ok, [ExHashRing.Node.name()]} | {:error, reason :: atom()}

Finds the specified number of nodes responsible for the given key in the specified ring's current generation.

find_stable_nodes(ring, key, num)

Specs

find_stable_nodes(ring(), key(), num :: non_neg_integer()) ::
  {:ok, [ExHashRing.Node.name()]} | {:error, atom()}

Finds the specificed number of nodes responsible for the given key by looking at each generation in the ring's configured depth. See find_stable_nodes/4 for more information.

find_stable_nodes(ring, key, num, back)

Specs

find_stable_nodes(
  ring(),
  key(),
  num :: non_neg_integer(),
  back :: pos_integer()
) :: {:ok, [ExHashRing.Node.name()]} | {:error, atom()}

force_gc(ring)

Specs

force_gc(ring()) :: {:ok, [generation()]}

Forces a garbage collection of any generations that are pending garbage collection. Returns the generations that were collected.

force_gc(ring, generation)

Specs

force_gc(ring(), generation()) :: :ok | {:error, :not_pending}

Forces a garbage collection of a specific generation, the generation must be pending or else {:error, :not_pending} is returned.

get_generation(ring)

Specs

get_generation(ring()) :: {:ok, generation()} | :error

Get the current ring generation

get_nodes(ring)

Specs

get_nodes(ring()) :: {:ok, [ExHashRing.Node.name()]}

Retrieves the current set of node names from the ring.

get_nodes_with_replicas(ring)

Specs

get_nodes_with_replicas(ring()) :: {:ok, [ExHashRing.Node.t()]}

Retrieves the current set of nodes as tuples of {name, replicas} from the ring.

get_overrides(ring)

Specs

get_overrides(ring()) :: {:ok, overrides()}

Retrieves the current set of overrides from the ring.

get_pending_gcs(ring)

Specs

get_pending_gcs(ring()) :: {:ok, [generation()]}

Retrieves a list of pending gc generations.

init(options)

Specs

init(options()) :: {:ok, t()}

Callback implementation for GenServer.init/1.

remove_node(ring, name)

Specs

remove_node(ring(), name :: ExHashRing.Node.name()) ::
  {:ok, [ExHashRing.Node.t()]} | {:error, :node_not_exists}

Removes a node from the ring by its name.

remove_nodes(ring, names)

Specs

remove_nodes(ring(), names :: [ExHashRing.Node.name()]) ::
  {:ok, [ExHashRing.Node.t()]} | {:error, :node_not_exists}

Atomically remove multiple nodes from the ring by name

set_nodes(ring, nodes)

Specs

set_nodes(ring(), nodes :: [ExHashRing.Node.definition()]) ::
  {:ok, [ExHashRing.Node.t()]}

Replaces the nodes in the ring with a new set of nodes.

set_overrides(ring, overrides)

Specs

set_overrides(ring(), overrides()) :: {:ok, overrides()}

Replaces the overrides in the ring with new overrides.

start_link(options \\ [])

Specs

start_link(options()) :: GenServer.on_start()

Start and link a Ring with the given name.

Ring supports various options see options/0 for more information.

stop(name)

Specs

stop(ring()) :: :ok

Stops the GenServer holding the Ring.