Module graceful
std only.Expand description
Cancellation trees with a graceful and a hard phase.
A Scope is one node of such a tree. It is first cancelled (the graceful phase: stop
taking new work, finish what runs) and then aborted (the hard phase: stop now). Both phases
flow from a parent to its children, never upwards, and the earliest cause wins.
A root comes from Scope::new. A process-wide root is usually
Scope::new().with_default_signal(), optionally with Scope::with_grace to bound the
drain. Every unit of work (a connection, a request, a relay) gets its own Scope::child,
tightened with timeouts, deadlines or signals as it needs. Work that belongs to several
scopes at once gets Scope::child_of them all.
Holding a Scope keeps its drain open, while a WeakScope only observes. Only running
work holds: a component is handed a WeakScope to run in and takes a hold for each piece
of work it starts (WeakScope::try_hold, then Scope::spawn_task), so a component kept
around never delays a shutdown. A cancelled scope without holders is closed and refuses new
holds; spawning on a held Scope is never refused.
Scope::join gives up its own hold and returns once every holder of the scope and its
subtree is gone, or with JoinAborted when the hard phase came first;
Scope::join_once_cancelled first waits for the cancel, as the shutdown of a root does.
An input carries the scope it runs in, weakly, in its extensions: attach_scope adds one,
enter_scope starts a new scope below it for the work on that input (enter_scope_with
also below a scope of the caller’s own), and scope_context observes it. Scopes travel in no other way, so retained extensions never
keep a drain open.
Structs§
- Aborted
- Future returned by
Scope::aborted; cancel safe. - Cancelled
- Future returned by
Scope::cancelled; cancel safe. - Drained
- Future returned by
Scope::drained; cancel safe. - Join
Aborted - Returned by [
Scope::join] when the scope reached its hard phase before it drained. - Joined
- Returned by [
Scope::join] once the scope drained. - Scope
- A node in a cancellation tree, held strongly.
- Scope
Closed - The scope an input runs in is closing and admits no new work, see
enter_scope. - Weak
Scope - A
Scopehandle that observes without holding the drain open.
Enums§
- Cause
- Why a
Scopeentered its graceful or hard phase. - RunCutoff
- Which bound ended a future run by
Scope::run_until_aborted_withinbefore it completed.
Functions§
- attach_
scope - Make the input of
extensionsalso run inscope. - default_
signal - Completes on Ctrl+C, and on SIGTERM (unix) or Ctrl+Break, close and shutdown events (windows).
- enter_
scope - Run the input of
extensionsin a new scope below the scope it runs in, and attach it. - enter_
scope_ with - Like
enter_scope, with the new scope also belowown(seeScope::child_of), such as the scope of the server that serves the input. - scope_
context - The scope an input runs in: every scope attached to its extensions, merged;
Noneif none is attached.