RpcLoadBalancer.LoadBalancer.SelectionAlgorithm.HashRing (rpc_load_balancer v0.3.4)

Copy Markdown View Source

Consistent hash ring node selection algorithm powered by libring.

Routes requests to nodes based on a caller-provided :key option. Each physical node is placed on the ring as virtual nodes (shards) so that topology changes only redistribute a minimal number of keys.

Supports replica selection via choose_nodes/4 — returns multiple distinct nodes for a given key, useful for replication strategies.

When no key is provided, falls back to random selection.

Storage:

  • :weight (compile-time-ish — set once at init/2) lives in :persistent_term keyed by {__MODULE__, lb_name, :weight}. Write-once is the access pattern :persistent_term is designed for.
  • The ring itself lives in HashRingCache (ETS). It's rewritten on every on_node_change event, so PT would mean continuous global GC sweeps in clusters with steady flapping.

Usage

RpcLoadBalancer.LoadBalancer.start_link(
  name: :my_balancer,
  selection_algorithm: RpcLoadBalancer.LoadBalancer.SelectionAlgorithm.HashRing,
  algorithm_opts: [weight: 200]
)

RpcLoadBalancer.LoadBalancer.select_node(:my_balancer, key: "user:123")

{:ok, [primary, replica]} =
  RpcLoadBalancer.LoadBalancer.select_nodes(:my_balancer, 2, key: "user:123")

Options

  • :weight — number of virtual nodes (shards) per physical node (default: 128)