Skip to main content

Module graceful

Module graceful 

Available on crate feature 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.
JoinAborted
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.
ScopeClosed
The scope an input runs in is closing and admits no new work, see enter_scope.
WeakScope
A Scope handle that observes without holding the drain open.

Enums§

Cause
Why a Scope entered its graceful or hard phase.
RunCutoff
Which bound ended a future run by Scope::run_until_aborted_within before it completed.

Functions§

attach_scope
Make the input of extensions also run in scope.
default_signal
Completes on Ctrl+C, and on SIGTERM (unix) or Ctrl+Break, close and shutdown events (windows).
enter_scope
Run the input of extensions in a new scope below the scope it runs in, and attach it.
enter_scope_with
Like enter_scope, with the new scope also below own (see Scope::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; None if none is attached.