Statifier.Session.HaltNotice (Statifier v2.11.0)

Copy Markdown View Source

The halt notice a session sends to the processes a send processor starts from Statifier.Send.Processor.perform/2, such as the timer that holds a delayed send (ADR-0069 decision 4: the processor owns the delay).

Spec 6.2 asks that a delayed send be discarded when its session terminates before the delay elapses. A session's status can be :done, :cancelled or :budget_exhausted while its process is still alive, so a timer cannot tell from the process alone, and asking the session with a call can time out while the session is busy. Instead, a processor hands the process it starts to watch/2 from inside perform/2, which a Statifier.Session runs in its own process, and the session sends that process

{:statifier_halted, session, reason}

when it halts, session being the session's pid and reason one of :done, :cancelled or :budget_exhausted. A process watched after the session has halted is sent the notice at once. The session never calls a watched process and never waits on it.

The session also keeps the watched process under the key the processor gave it, so the processor can take/1 the processes held under a key (to cancel them, say), and forgets each one when it ends.

Outside a Statifier.Session (a host that performs instructions in its own process), there is no session to send the notice: watch/2 keeps nothing and answers :not_a_session, and take/1 answers [].

Summary

Types

The message a watched process is sent when its session halts.

Why the session halted, as its status names it.

Functions

Removes and answers every process watched under key in the calling session; a taken process is sent no notice. Answers [] outside a session or when none is held under key.

Watches pid under key for the session performing the current instruction: the session sends pid a notice/0 when it halts, or at once when it has already halted, and keeps pid under key until pid ends or is taken with take/1.

Types

notice()

@type notice() :: {:statifier_halted, session :: pid(), reason()}

The message a watched process is sent when its session halts.

reason()

@type reason() :: :done | :cancelled | :budget_exhausted

Why the session halted, as its status names it.

Functions

take(key)

@spec take(key :: term()) :: [pid()]

Removes and answers every process watched under key in the calling session; a taken process is sent no notice. Answers [] outside a session or when none is held under key.

watch(key, pid)

@spec watch(key :: term(), pid :: pid()) :: :ok | :not_a_session

Watches pid under key for the session performing the current instruction: the session sends pid a notice/0 when it halts, or at once when it has already halted, and keeps pid under key until pid ends or is taken with take/1.

Call it from Statifier.Send.Processor.perform/2, which a session runs in its own process. Answers :not_a_session, keeping nothing, when the calling process is not a Statifier.Session.