Specs

add_node(ring(), key()) :: :ok | {:error, :no_such_ring}

Adds a node to the given hash ring.

An error is returned if the ring does not exist, or the node already exists in the ring.

Examples

iex> {:ok, _pid} = HashRing.Managed.new(:test4)
...> HashRing.Managed.add_node(:test4, "a")
...> HashRing.Managed.key_to_node(:test4, :foo)
"a"

iex> HashRing.Managed.add_node(:no_exist, "a")
{:error, :no_such_ring}

Specs

add_node(ring(), key(), weight()) ::
  :ok | {:error, :no_such_ring} | {:error, {:invalid_weight, key(), term()}}

Same as add_node/2, but takes a weight value.

The weight controls the relative presence this node will have on the ring, the default is 128, but it's best to give each node a weight value which maps to a concrete resource such as memory or priority. It's not ideal to have a number which is too high, as it will make the ring data structure larger, but a good value is probably in the range of 64-256.

Examples

iex> {:ok, _pid} = HashRing.Managed.new(:test5)
...> HashRing.Managed.add_node(:test5, "a", 64)
...> HashRing.Managed.key_to_node(:test5, :foo)
"a"

iex> HashRing.Managed.add_node(:no_exist, "a")
{:error, :no_such_ring}

Specs

add_nodes(ring(), node_list()) ::
  :ok | {:error, :no_such_ring} | {:error, [{:invalid_weight, key(), term()}]}

Adds a list of nodes to the ring.

The list of nodes can contain either node names or {node_name, weight} tuples. If there is an error with any of the node weights, an error will be returned, and the ring will remain unchanged.

Examples

iex> {:ok, _pid} = HashRing.Managed.new(:test6)
...> :ok = HashRing.Managed.add_nodes(:test6, ["a", {"b", 64}])
...> HashRing.Managed.key_to_node(:test6, :foo)
"b"

iex> {:ok, _pid} = HashRing.Managed.new(:test7)
...> HashRing.Managed.add_nodes(:test7, ["a", {"b", :wrong}])
{:error, [{:invalid_weight, "b", :wrong}]}

Specs

key_to_node(ring(), any()) ::
  key() | {:error, :no_such_ring} | {:error, {:invalid_ring, :no_nodes}}

Maps a key to a node on the hash ring.

An error is returned if the ring does not exist.

Specs

new(ring(), ring_options()) ::
  {:ok, pid()}
  | {:error, {:already_started, pid()}}
  | {:error, {:invalid_option, term()}}

Creates a new stateful hash ring with the given name.

This name is how you will refer to the hash ring via other API calls.

It takes an optional set of options which control how the ring behaves. Valid options are as follows:

• monitor_nodes: boolean - will automatically monitor Erlang node membership, if new nodes are connected or nodes are disconnected, the ring will be updated automatically. In this configuration, nodes cannot be added or removed via the API. Those requests will be ignored.
• node_blacklist: [String.t | Regex.t] - Used in conjunction with monitor_nodes: true, this is a list of patterns, either as literal strings, or as regex patterns (in either string or literal form), and will be used to ignore nodeup/down events for nodes which are blacklisted. If a node whitelist is provided, the blacklist has no effect.
• node_whitelist: [String.t | Regex.t] - The same as node_blacklist, except the opposite; only nodes which match a pattern in the whitelist will result in the ring being updated.

• node_type: :all | :hidden | :visible: refers what kind of nodes will be monitored when monitor_nodes is true. For more information, see :net_kernel.monitor_nodes/2.

An error is returned if the ring already exists or if bad ring options are provided.

Examples

iex> {:ok, _pid} = HashRing.Managed.new(:test1, [nodes: ["a", {"b", 64}]])
...> HashRing.Managed.key_to_node(:test1, :foo)
"b"

iex> {:ok, pid} = HashRing.Managed.new(:test2)
...> {:error, {:already_started, existing_pid}} = HashRing.Managed.new(:test2)
...> pid == existing_pid
true
iex> HashRing.Managed.new(:test3, [nodes: "a"])
** (ArgumentError) {:nodes, "a"} is an invalid option for `HashRing.Managed.new/2`

Specs

nodes(ring()) :: [term()]

Same as HashRing.nodes/1, returns a list of nodes on the ring.

Examples

iex> {:ok, _pid} = HashRing.Managed.new(:nodes_test)
...> HashRing.Managed.add_nodes(:nodes_test, [:a, :b])
...> HashRing.Managed.nodes(:nodes_test)
[:b, :a]

Specs

remove_node(ring(), key()) :: :ok | {:error, :no_such_ring}

Removes a node from the given hash ring.

An error is returned if the ring does not exist.

Examples

iex> {:ok, _pid} = HashRing.Managed.new(:test8)
...> :ok = HashRing.Managed.add_nodes(:test8, ["a", {"b", 64}])
...> :ok = HashRing.Managed.remove_node(:test8, "b")
...> HashRing.Managed.key_to_node(:test8, :foo)
"a"