portunus_service behaviour (portunus v0.8.0)

View Source

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:

-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

service_opts()

-type service_opts() ::
          #{ttl_ms => pos_integer(), affinity => portunus_affinity:spec(), group => term()}.

Callbacks

keys/1

-callback keys(term()) -> [term()].

start/3

-callback start(term(), portunus:token(), term()) -> {ok, term()}.

stop/2

-callback stop(term(), term()) -> ok.

Functions

handle_call/3

handle_cast(Msg, State)

handle_info/2

init/1

start_link(Name, Mod, Args)

-spec start_link(portunus:name(), module(), term()) -> {ok, pid()} | {error, term()}.

start_link(Name, Mod, Args, Opts)

-spec start_link(portunus:name(), module(), term(), service_opts()) -> {ok, pid()} | {error, term()}.

stop(Pid)

-spec stop(pid()) -> ok.

terminate(Reason, State)

transfer(Server, Key, TargetNode)

-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}}.