portunus_service behaviour (portunus v0.8.0)
View SourceA 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:
-callback keys(Args :: term()) -> [Key :: term()].
-callback start(Key :: term(), Token :: portunus:token(), Args :: term()) ->
{ok, State :: term()}.
-callback stop(Key :: term(), State :: term()) -> ok.start/3 must link whatever it starts to the calling process: a crashed
election loses the callback state, and an unlinked resource then keeps
running with no way to stop it.
Every node contends eagerly, and the election keeps a single winner per
key until that winner's lease is lost. Pass #{affinity => Spec} (see
portunus_affinity) to steer which
node wins, for example a preferred-owner or consistent-hash hint; the
default is FIFO in arrival (registration) order.
Summary
Functions
If this node currently owns Key, hand ownership to TargetNode; if not,
return {error, not_owner}. Only the owner can transfer. If
TargetNode is not a ready contender the owner keeps running and the reply is
{error, {no_contender, TargetNode}}.
Types
-type service_opts() :: #{ttl_ms => pos_integer(), affinity => portunus_affinity:spec(), group => term()}.
Callbacks
Functions
-spec start_link(portunus:name(), module(), term()) -> {ok, pid()} | {error, term()}.
-spec start_link(portunus:name(), module(), term(), service_opts()) -> {ok, pid()} | {error, term()}.
-spec stop(pid()) -> ok.
-spec transfer(pid(), term(), node()) -> portunus:ok_or_error({no_contender, node()} | not_owner | no_quorum).
If this node currently owns Key, hand ownership to TargetNode; if not,
return {error, not_owner}. Only the owner can transfer. If
TargetNode is not a ready contender the owner keeps running and the reply is
{error, {no_contender, TargetNode}}.