API Reference portunus v#0.8.0

The primary API of the portunus lock server. Its shape is inspired by ra's own API.

An affinity strategy gives each portunus node (cluster member) a score for a key, and portunus_machine succession promotes the highest-scoring contender. Ties are broken in favor of the node that joined the succession queue first.

Every node scores 0, so succession is plain FIFO in arrival (registration) order. For an even spread across nodes use hash.

Rendezvous (highest-random-weight) hashing: each node scores its weight for the key, the highest wins. Keys spread evenly across members, and a membership change only moves the keys that hashed to the gained or lost node. Args is ignored. phash2/1 is portable, so every node agrees.

A dynamic strategy: this node bids the value of a local metric. Args is a fun(() -> integer()) read on each node, for example spare capacity, so the least-loaded node wins. The bid is a snapshot taken at contention time, not a continuous signal.

Run the child on Args, the pinned node. Every other node scores 0, so if the pinned node is absent any of them can take over (a soft pin).

Prefer the nodes in Args, a node list, earliest first. A node in the list always outscores one that is not, so the list is the order in which ownership moves between nodes.

A dynamic strategy: each node bids a random weight, so a uniformly random contender wins. The roll runs on the client, never in the machine, so it does not affect determinism. For a stable even spread prefer portunus_affinity_hash, whose owner does not move on every contention.

Operational metrics for portunus, backed by seshat (one counter set per node, per cluster).

Rate-limited restarts for plain Erlang/OTP supervisors, accepting the extended supervisor2 restart type without a dependency on supervisor2.

Helps implement a leader election with application-specific semantics.

This module implements automatic background lease renewal for a holder that is an Erlang process.

The portunus Ra state machine. It manages leases, locks, fencing tokens, a score-ordered succession queue (FIFO among equal scores), and tick-based lease expiry.

A dynamic cluster-wide supervisor. "Dynamic" isn't an Erlang/OTP supervisor type here: it means children are added and removed at runtime with add/3 and remove/2, unlike portunus_supervisor, whose children are the fixed set returned once by init/1.

A managed set of keys, each with exactly one owner in the cluster at any given time. When an owner's lease is lost, ownership moves to another node. Runs one portunus_election per key. The callback module supplies the key set and the per-key work

A per-node session: one lease, one renewer, many exclusive keys claimed under it. The session process is the lease holder, so its death releases all of its keys at once. Renewal cost is O(sessions), not O(keys).

A declarative, static supervisor. "Static" isn't an Erlang/OTP supervisor type here: it means the child set is fixed, returned once by init/1, unlike portunus_registry, whose children are added and removed at runtime.