portunus_machine (portunus v0.8.0)

View Source

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.

Determinism rules (see AGENTS.md): apply/3 never reads node-local time (only the leader-stamped system_time in the command metadata), never calls make_ref/0/self/0, and mints tokens/ids from the Raft index. Timers and monitors are effects that only trigger commands; the decision is always re-derived from replicated state.

Summary

Types

command()
lease_id()
lock_key()
owner()
owner_info()
state()
token()
watch_ref()

Functions

apply(Meta, Cmd, State0)
handle_aux/5
init(Config)
init_aux(Name)
overview(State)
query_contenders(LockKey, State)
query_owner(LockKey, State)
query_status(State)
state_enter/2
version()
which_module/1

Types

command()

-type command() ::
          {grant_lease, portunus:option(lease_id()), pos_integer(), owner(), portunus:option(pid())} |
          {renew, [lease_id()]} |
          {revoke_lease, lease_id()} |
          {acquire, lease_id(), lock_key(), owner(), term(), wait | nowait} |
          {acquire, lease_id(), lock_key(), owner(), term(), wait | nowait, integer()} |
          {release, lock_key(), token()} |
          {transfer, lock_key(), token(), owner()} |
          {leave_queue, lock_key(), lease_id()} |
          {watch, lock_key(), pid()} |
          {unwatch, watch_ref()} |
          {timeout, expire} |
          {down, pid(), term()} |
          {nodeup | nodedown, node()}.

lease_id()

-type lease_id() :: term().

lock_key()

-type lock_key() :: term().

owner()

-type owner() :: term().

owner_info()

-type owner_info() ::
          #{owner := owner(),
            lease := lease_id(),
            token := token(),
            context := term(),
            remaining_ms := non_neg_integer()}.

state()

-opaque state()

token()

-type token() :: non_neg_integer().

watch_ref()

-type watch_ref() :: non_neg_integer().

Functions

apply(Meta, Cmd, State0)

-spec apply(ra_machine:command_meta_data(), command(), state()) ->
               {state(), term(), ra_machine:effects()}.

handle_aux/5

-spec handle_aux(ra_server:ra_state(), term(), term(), undefined, ra_aux:internal_state()) ->
                    {no_reply, undefined, ra_aux:internal_state()}.

init(Config)

-spec init(map()) -> state().

init_aux(Name)

-spec init_aux(atom()) -> undefined.

overview(State)

-spec overview(state()) -> map().

query_contenders(LockKey, State)

-spec query_contenders(lock_key(), state()) -> [owner()].

query_owner(LockKey, State)

-spec query_owner(lock_key(), state()) -> {ok, owner_info()} | {error, not_held}.

query_status(State)

-spec query_status(state()) -> map().

state_enter/2

-spec state_enter(ra_server:ra_state() | eol, state()) -> ra_machine:effects().

version()

-spec version() -> ra_machine:version().

which_module/1

-spec which_module(ra_machine:version()) -> module().