portunus_session (portunus v0.8.0)
View SourceA 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).
On lease loss the session exits with reason lease_lost. A linked opener
that does not trap exits crashes with it (the fail-stop default, since
its claims are gone). Trap exits to handle the loss instead.
Summary
Functions
Claim an exclusive key under the session; returns its fencing token.
Open a session. Opts: ttl_ms, proposed_id (a stable proposed lease id).
After a partition, reopening with a proposed_id can return
{error, id_in_use} until the previous incarnation's lease expires;
supervisor restart handles it.
Types
-type session() :: pid().
-type session_opts() :: #{ttl_ms => pos_integer(), proposed_id => portunus:lease_id()}.
Functions
-spec claim(session(), portunus:lock_key()) -> {ok, portunus:token()} | {error, portunus:acquire_error()}.
Claim an exclusive key under the session; returns its fencing token.
-spec close(session()) -> ok.
-spec keys(session()) -> [portunus:lock_key()].
-spec open(portunus:name()) -> {ok, session()} | {error, term()}.
-spec open(portunus:name(), session_opts()) -> {ok, session()} | {error, term()}.
Open a session. Opts: ttl_ms, proposed_id (a stable proposed lease id).
After a partition, reopening with a proposed_id can return
{error, id_in_use} until the previous incarnation's lease expires;
supervisor restart handles it.
-spec release(session(), portunus:lock_key()) -> ok | {error, portunus:release_error()}.