View Source Cachex.Router.Ring (Cachex v4.0.1)

Routing implementation using a consistent hash ring.

This router provides the most resilient routing for a distributed cache, due to being much more resilient to addition and removal of nodes in the cluster. Most distributed caches will end up using this router if they have the requirement to handle such cases.

The core implementation of this router is provided by the Discord library, so please see their repository for further details.

Summary

Functions

Create a child specification to back a ring routing state.

Returns whether a node is included given the provided patterns.

Initialize a ring routing state for a cache.

Retrieve the list of nodes from a ring routing state.

Route a key to a node in a ring routing state.

Functions

Link to this function

children(cache, options)

View Source
@spec children(cache :: Cachex.t(), options :: Keyword.t()) :: Supervisor.child_spec()

Create a child specification to back a ring routing state.

Link to this function

included?(node, includes, excludes)

View Source
@spec included?(
  node :: binary() | node(),
  includes :: [binary() | Regex.t()],
  excludes :: [binary() | Regex.t()]
) :: boolean()

Returns whether a node is included given the provided patterns.

Link to this function

init(cache, options \\ [])

View Source
@spec init(cache :: Cachex.t(), options :: Keyword.t()) :: ExHashRing.Ring.ring()

Initialize a ring routing state for a cache.

Options

  • :nodes

    The :nodes option allows a user to provide a list of nodes to treat as a cluster. If this is not provided, the cluster will be inferred by using Node.self/0 and Node.list/1.

  • :monitor

    This option specifies whether to monitor Erlang :nodeup and :nodedown events and scale this ring to add/remove nodes dynamically. This defaults to false, but if you're using this router it's likely you want this enabled.

  • :monitor_excludes

    This option allows the developer to provide a list of patterns to exclude nodes from joining automatically when monitoring is enabled. Patterns can be provided as either binaries or Regex.

  • :monitor_includes

    This option allows the developer to provide a list of patterns to validate nodes before allowing them to join the ring. Patterns can be provided as either binaries or Regex.

  • :monitor_type

    The type of nodes to listen for and dynamically add to the internal ring. This defaults to :all, but can be any value accepted by the OTP function :net_kernel.monitor_nodes/2.

@spec nodes(ring :: ExHashRing.Ring.t()) :: {:ok, [atom()]}

Retrieve the list of nodes from a ring routing state.

@spec route(ring :: ExHashRing.Ring.t(), key :: any()) :: {:ok, atom()}

Route a key to a node in a ring routing state.