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

Copy Markdown View Source

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)
claim_maintenance(t, atom, 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.

claim_maintenance(config, ref, purpose, opts \\ [])

Claims an unowned Instance for one offline maintenance operation.

maintenance_capability(config)

Checks whether an Owner can fence an offline maintenance operation.

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()}

claim_maintenance(t, atom, keyword)

(optional) 
@callback claim_maintenance(Spectre.Instance.Ref.t(), atom(), 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.

claim_maintenance(config, ref, purpose, opts \\ [])

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

Claims an unowned Instance for one offline maintenance operation.

Unlike an ordinary claim, an adapter must not supersede a live owner. The callback is optional so existing adapters remain source compatible, but maintenance operations fail with an explicit capability error when it is absent. The local adapter is safe only after core has reserved the unique local Registry key.

maintenance_capability(config)

@spec maintenance_capability(config()) :: :ok | {:error, term()}

Checks whether an Owner can fence an offline maintenance operation.

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.