How to Use Connection-Tracking Algorithms

Copy Markdown View Source

The Least Connections and Power of Two algorithms track active connection counts per node. This guide covers how to use them and handle the connection lifecycle correctly.

Start with Least Connections

alias RpcLoadBalancer.LoadBalancer.SelectionAlgorithm

{:ok, _pid} =
  RpcLoadBalancer.start_link(
    name: :lc_balancer,
    selection_algorithm: SelectionAlgorithm.LeastConnections
  )

How tracking works

When choose_from_nodes/3 runs, it:

  1. Reads each node's connection count from an ETS counter
  2. Picks the node with the lowest count
  3. Atomically increments that node's counter

When the call finishes, the counter must be decremented.

Automatic release with call/5

When you use call/5 with the :load_balancer option, the library handles counter management for you. After the RPC completes (success or failure), it calls the algorithm's release_node/2 to decrement the counter:

{:ok, result} =
  RpcLoadBalancer.call(node(), MyModule, :work, [arg], load_balancer: :lc_balancer)

Manual release with select_node

If you use select_node/2 directly, you are responsible for releasing the node through the algorithm:

alias RpcLoadBalancer.LoadBalancer.SelectionAlgorithm

{:ok, selected} = RpcLoadBalancer.select_node(:lc_balancer)
{:ok, algorithm} = SelectionAlgorithm.get_algorithm(:lc_balancer)

try do
  {:ok, :erpc.call(selected, MyModule, :work, [arg])}
after
  SelectionAlgorithm.release_node(algorithm, :lc_balancer, selected)
end

Always release in an after block to prevent counter leaks on errors.

Power of Two

Power of Two works identically but samples only two random nodes instead of scanning all of them. It provides a good balance between accuracy and performance at scale:

{:ok, _pid} =
  RpcLoadBalancer.start_link(
    name: :p2c_balancer,
    selection_algorithm: SelectionAlgorithm.PowerOfTwo
  )

The same release semantics apply — call/5 with :load_balancer handles it automatically, select_node/2 requires manual release.

Node lifecycle

Both algorithms implement on_node_change/2:

  • Join — no-op (counters start at zero implicitly)
  • Leave — erases the counter entry for the departed node

This happens automatically when the :pg group membership changes.