Spectre.Instance.Owner behaviour (Spectre v0.3.0)

Host contract for canonical Instance ownership and monotonic fencing.

A local Registry is routing, not distributed ownership. Hosts that may run the same logical Instance on multiple nodes must supply an adapter backed by a linearizable lease or route all work to one canonical owner. Losing or superseding the lease blocks admission, activation commit, state commit, Effect dispatch, and retry before dispatch.

Summary

Types

config()

Callbacks

claim(t, keyword)

release(t, t, keyword)

validate(t, t, keyword)

Functions

assert_current(config, ref, lease, operation, opts \\ [])

Validates a lease and classifies failure as an owner-fence loss for one concrete operation.

claim(config, ref, opts \\ [])

Claims ownership and validates the returned portable lease.

normalize(module)

Normalizes an ownership adapter; nil selects the local-only adapter.

release(config, ref, lease, opts \\ [])

Releases an owned lease when the adapter implements the callback.

validate(config, ref, lease, opts \\ [])

Validates that a lease remains current at a guarded boundary.

Types

config()

@type config() :: module() | {module(), keyword()} | nil

Callbacks

claim(t, keyword)

@callback claim(
  Spectre.Instance.Ref.t(),
  keyword()
) :: {:ok, Spectre.Instance.Owner.Lease.t()} | {:error, term()}

release(t, t, keyword)

(optional)

@callback release(Spectre.Instance.Ref.t(), Spectre.Instance.Owner.Lease.t(), keyword()) ::
  :ok | {:error, term()}

validate(t, t, keyword)

@callback validate(Spectre.Instance.Ref.t(), Spectre.Instance.Owner.Lease.t(), keyword()) ::
  :ok | {:error, term()}

Functions

assert_current(config, ref, lease, operation, opts \\ [])

@spec assert_current(
  config(),
  Spectre.Instance.Ref.t(),
  Spectre.Instance.Owner.Lease.t(),
  atom(),
  keyword()
) :: :ok | {:error, term()}

Validates a lease and classifies failure as an owner-fence loss for one concrete operation.

claim(config, ref, opts \\ [])

@spec claim(config(), Spectre.Instance.Ref.t(), keyword()) ::
  {:ok, {module(), keyword()}, Spectre.Instance.Owner.Lease.t()}
  | {:error, term()}

Claims ownership and validates the returned portable lease.

normalize(module)

@spec normalize(config()) :: {:ok, {module(), keyword()}} | {:error, term()}

Normalizes an ownership adapter; nil selects the local-only adapter.

release(config, ref, lease, opts \\ [])

@spec release(
  config(),
  Spectre.Instance.Ref.t(),
  Spectre.Instance.Owner.Lease.t(),
  keyword()
) ::
  :ok | {:error, term()}

Releases an owned lease when the adapter implements the callback.

validate(config, ref, lease, opts \\ [])

@spec validate(
  config(),
  Spectre.Instance.Ref.t(),
  Spectre.Instance.Owner.Lease.t(),
  keyword()
) ::
  :ok | {:error, term()}

Validates that a lease remains current at a guarded boundary.