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, a dynamic child is hosted. A hosted child that can be started again, such as most Supervisables and every Supervisor, is restarted only if it fails. A child that cannot be started again, such as an FnWorker, is never restarted. See the runtime documentation.

A dynamic child is not restored when the supervisor itself restarts. The supervisor stops the child when the supervisor restarts or terminates.

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_sibling becomes a child of this supervisor. So does anything that fut spawns through spawn, but only if fut runs outside supervision. Code in a supervised process has a current scope, and spawn uses that scope instead of the ambient supervisor. Thus, this function 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 worker_with_shutdown<N, F, Fut>(&self, name: N, f: F) -> ChildBuilder<'_>

where N: Into<String>, F: FnOnce(ShutdownHandle) -> Fut + Send + 'static, Fut: Future + Send + 'static, Fut::Output: IntoWorkerResult,

Creates a builder for a child task with a body that receives the shutdown signal.

f receives the [ShutdownHandle] of the task when the task starts. Use this method for work that must observe shutdown to stop in time. Such work stops when it observes shutdown, not when it reaches its own terminal condition. An example is a long-lived connection that must close gracefully. See FnWorker::with_shutdown.

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.

A supervisable task can usually be started again, so its owner restarts it when it fails. A task that reports through can_restart that it cannot be started again is never restarted. See the runtime documentation for how its restart policy is decided.

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.

You can give a Supervisor directly to spawn or Supervisor::add_worker. Most callers need only that. This builder is for the settings that are not available in that way: whether the subtree is needed or hosted, and whether it stops with its owner in a scope.

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 its drain is bounded by its children’s timeouts and by its owner.

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.