Owns subscriber roles, monitor identity, and detached-session reclamation.
Session performs every process and timer effect. This value validates the operation, returns the next lifecycle or a named preparation, and accepts the resulting OTP reference through a completion transition.
Transition table
| Command | Valid source | Result |
|---|---|---|
| subscribe | valid role, PID absent | monitor preparation |
| complete subscribe | unchanged preparation source | attachment installed, prior timer returned for cancellation |
| claim driver | attached PID, driver vacant or same PID | role transition |
| detach | attached PID | attachment removed with monitor cleanup identity |
| DOWN | matching PID and monitor reference | attachment removed |
| reconcile reclaim | detached and turn reclaimable | timer preparation or unchanged |
| complete reclaim schedule | unchanged preparation source | exact OTP timer reference installed |
| reclaim timeout | matching timer, detached, turn reclaimable | reclaim accepted |
| stop | any | empty lifecycle plus ordered timer and monitor cleanup identity |
Summary
Types
A validated reclaim schedule awaiting timer creation.
Remote attachment role.
Role outcome produced by installing a new subscriber.
A validated subscription awaiting monitor creation.
Subscriber lifecycle state.
Functions
Claims a vacant driver role for an attached subscriber.
Installs an OTP reclaim timer when the validated source is still current.
Installs a subscription monitor when the validated source is still current.
Returns the default role for a new subscriber.
Detaches a subscriber and returns its monitor identity for cleanup.
Returns the active driver derived from canonical attachment roles.
Returns true when the PID owns the driver role.
Builds an empty detached lifecycle.
Validates a subscription before Session creates its process monitor.
Accepts only the installed timer identity and rechecks reclaim eligibility.
Returns the installed reclaim timer reference.
Reconciles the installed reclaim timer with attachment and turn eligibility.
Returns the role for an attached subscriber.
Clears lifecycle ownership and returns timer then monitor cleanup identities.
Consumes a subscriber DOWN only when both PID and monitor identity match.
Returns all attached subscriber PIDs.
Types
@type reclaim_preparation() :: t()
A validated reclaim schedule awaiting timer creation.
@type role() :: MingaAgent.Session.SubscriberAttachment.role()
Remote attachment role.
@type subscription_change() ::
:driver_initialized | :driver_changed | :viewer_attached
Role outcome produced by installing a new subscriber.
A validated subscription awaiting monitor creation.
@type t() :: %MingaAgent.Session.SubscriberLifecycle{ attachments: %{required(pid()) => MingaAgent.Session.SubscriberAttachment.t()}, reclaim_timer: reference() | nil }
Subscriber lifecycle state.
Functions
@spec claim_driver(t(), pid()) :: {:changed, t()} | :unchanged | {:error, :driver_taken | :not_subscribed}
Claims a vacant driver role for an attached subscriber.
@spec complete_reclaim_schedule(t(), reclaim_preparation(), reference()) :: {:ok, t()} | {:error, :stale_preparation | :timer_already_installed | :subscriber_attached}
Installs an OTP reclaim timer when the validated source is still current.
@spec complete_subscribe(t(), subscription_preparation(), reference()) :: {:ok, t(), subscription_change(), timer_to_cancel :: reference() | nil} | {:error, :stale_preparation | :already_attached | :driver_taken}
Installs a subscription monitor when the validated source is still current.
Returns the default role for a new subscriber.
@spec detach(t(), pid()) :: {:removed, t(), MingaAgent.Session.SubscriberAttachment.t()} | :unchanged
Detaches a subscriber and returns its monitor identity for cleanup.
Returns the active driver derived from canonical attachment roles.
Returns true when the PID owns the driver role.
@spec new() :: t()
Builds an empty detached lifecycle.
@spec prepare_subscribe(t(), pid(), term()) :: {:monitor, subscription_preparation()} | {:already_attached, t()} | {:error, :invalid_role}
Validates a subscription before Session creates its process monitor.
@spec reclaim_timeout(t(), reference(), boolean()) :: {:reclaim, t()} | {:keep, t()} | {:error, :stale_timer}
Accepts only the installed timer identity and rechecks reclaim eligibility.
Returns the installed reclaim timer reference.
@spec reconcile_reclaim(t(), boolean(), boolean()) :: {:start_timer, reclaim_preparation()} | {:cancel_timer, reference(), t()} | :unchanged
Reconciles the installed reclaim timer with attachment and turn eligibility.
Returns the role for an attached subscriber.
Clears lifecycle ownership and returns timer then monitor cleanup identities.
@spec subscriber_down(t(), pid(), reference()) :: {:removed, t(), MingaAgent.Session.SubscriberAttachment.t()} | {:error, :stale_monitor}
Consumes a subscriber DOWN only when both PID and monitor identity match.
Returns all attached subscriber PIDs.