Struct SupervisorHandle 

pub struct SupervisorHandle { /* private fields */ }

A handle for spawning dynamic children on a running Supervisor.

Obtained from Supervisor::handle. Handles are cheap to clone and can be shared across tasks.

Spawning is synchronous and infallible, in the spirit of tokio::spawn: the child is queued for the running supervisor and the call returns immediately with the child’s ChildId. Also as with tokio::spawn, being accepted is not a promise of being run – if the supervisor isn’t running, or shuts down before it gets to the queued child, the child is never started at all.

Ambient spawning

Code running under supervision usually doesn’t need a handle at all: spawn targets the supervisor of whatever process is currently running. Use a handle when spawning from outside supervision, or when targeting a supervisor other than the ambient one. scope bridges the two by making a handle the ambient supervisor for a future.

Implementations

impl SupervisorHandle

pub fn name(&self) -> &str

Returns the name of the supervisor this handle refers to.

pub fn spawn<S, T>(&self, child: T) -> ChildId

where S: ChildState, T: Into<ChildSpecification<S>>,

Spawns a new dynamic child.

Accepts anything Supervisor::add_worker accepts: a bare Supervisable, a Supervisor to run as a nested supervision subtree, or a ChildSpecification configured in detail.

Unless ChildBuilder says otherwise, dynamic children are temporary: they aren’t restarted when they die, and they aren’t restored when the supervisor itself restarts. That suits short-lived, non-critical work that still wants structured concurrency – the child is stopped when the supervisor is restarted or terminated.

The returned ChildId identifies the child for the lifetime of the supervisor run. The child is queued rather than started synchronously, so it may not have begun running by the time this returns; if the supervisor isn’t running, or shuts down before reaching the child, it never runs at all.

pub fn is_running(&self) -> bool

Returns whether the supervisor is currently running.

pub fn active_children(&self) -> usize

Returns the number of dynamic children currently running under the supervisor.

Counts children the supervisor has actually started, so a child that has been spawned but not yet picked up isn’t included yet.

impl SupervisorHandle

pub fn scope<F>(&self, fut: F) -> TaskLocalFuture<SupervisorHandle, F>

where F: Future,

Runs fut with this supervisor installed as the ambient supervisor.

Anything fut spawns through spawn becomes a child of this supervisor. Supervised processes already have their own supervisor installed, so this is for code that runs outside supervision – a test driving a component directly, or a task started with tokio::spawn that needs to attach children to a known supervisor.

The ambient supervisor applies only for the duration of fut, and shadows any supervisor already installed.

impl SupervisorHandle

pub fn worker<N, Fut>(&self, name: N, fut: Fut) -> ChildBuilder<'_>

where N: Into<String>, Fut: Future + Send + 'static, Fut::Output: IntoWorkerResult,

Creates a builder for a child task built from a plain future.

The task runs until it reaches its own terminal condition; it is never handed the shutdown signal. See FnWorker for what that means at shutdown, and for the two cases that need something else.

Use this method when advanced configuration of the underlying task is required. Otherwise, prefer spawn_worker.

Examples

supervisor.worker("encoder", encode()).on_runtime(pool).spawn();

pub fn supervisable<T>(&self, worker: T) -> ChildBuilder<'_, Restartable>

where T: Supervisable + 'static,

Creates a builder for a supervisable child task.

Supervisable tasks are those where the worker already implements Supervisable, which lets the builder serve as a consistent control surface for spawning both arbitrary asynchronous functions and more full-fledged workers.

Supervisable tasks are set to permanently restart by default.

Use this method when advanced configuration of the underlying task is required. Otherwise, prefer spawn_supervisable.

pub fn spawn_worker<N, Fut>(&self, name: N, fut: Fut) -> ChildId

where N: Into<String>, Fut: Future + Send + 'static, Fut::Output: IntoWorkerResult,

Spawns a child task built from a plain future.

The task runs until it reaches its own terminal condition; it is never handed the shutdown signal. See FnWorker for what that means at shutdown, and for the two cases that need something else.

Use worker when advanced configuration of the underlying task is required.

pub fn spawn_supervisable<T>(&self, worker: T) -> ChildId

where T: Supervisable + 'static,

Spawns a supervisable child task.

Supervisable tasks are those where the worker already implements Supervisable, which lets the builder serve as a consistent control surface for spawning both arbitrary asynchronous functions and more full-fledged workers.

Use supervisable when advanced configuration of the underlying task is required.

pub fn nested_supervisor( &self, supervisor: Supervisor, ) -> NestedSupervisorBuilder<'_>

Creates a builder for a nested supervisor.

A Supervisor can be handed to spawn or Supervisor::add_worker directly, which is all most callers need. This builder exists for the settings that aren’t reachable that way: the restart policy and significance. It matters most for a dynamically spawned subtree, which would otherwise be temporary and so quietly stay dead once it terminated.

Unlike supervisable, there is no placement or shutdown setting. A nested supervisor runs wherever its parent does and its children carry their own placement, and it bounds its own drain through those children rather than through a deadline imposed from above.

Nested supervisors are set to permanently restart by default.

Trait Implementations

impl Clone for SupervisorHandle

fn clone(&self) -> SupervisorHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.