Struct Supervisor 

pub struct Supervisor { /* private fields */ }

Supervises a set of workers.

Workers

All workers are defined through implementation of the Supervisable trait, which provides the logic for both creating the underlying worker future that’s spawned, as well as other metadata, such as the worker’s name, how the worker should be shutdown, and so on.

Supervisors also (indirectly) implement the Supervisable trait, allowing them to be supervised by other supervisors in order to construct supervision trees.

Instrumentation

Supervisors automatically create their own allocation group ([TrackingAllocator][resource_accounting::TrackingAllocator]), which is used to track both the memory usage of the supervisor itself and its children. Additionally, individual worker processes are wrapped in a dedicated tracing::Span to allow tracing the causal relationship between arbitrary code and the worker executing it.

Restart Strategies

As the main purpose of a supervisor, restart behavior is fully configurable. A number of restart strategies are available, which generally relate to the purpose of the supervisor: whether the workers being managed are independent or interdependent.

All restart strategies are configured through RestartStrategy, which has more information on the available strategies and configuration settings.

Implementations

impl Supervisor

pub fn new<S: AsRef<str>>(supervisor_id: S) -> Result<Self, SupervisorError>

Creates an empty Supervisor with the default restart strategy.

pub fn id(&self) -> &str

Returns the supervisor’s ID.

pub fn with_restart_strategy(self, strategy: RestartStrategy) -> Self

Sets the restart strategy for the supervisor.

pub fn with_auto_shutdown(self, auto_shutdown: AutoShutdown) -> Self

Sets the supervisor’s automatic-shutdown policy.

Controls whether the termination of significant children (see ChildSpecification::with_significant) drives the supervisor to shut down. Defaults to AutoShutdown::Never.

pub fn with_shutdown_mode(self, mode: ShutdownMode) -> Self

Sets the supervisor’s shutdown mode. See ShutdownMode. Defaults to ShutdownMode::Ordered.

pub fn handle(&self) -> SupervisorHandle

Returns a handle for spawning dynamic children on this supervisor while it runs.

The handle can be created before the supervisor starts and cloned freely. Spawns only succeed while the supervisor is actually running; if it hasn’t started yet, is between restarts, or has shut down, they return SpawnError::SupervisorGone.

pub fn with_dedicated_runtime(self, config: RuntimeConfiguration) -> Self

Configures this supervisor to run in a dedicated runtime.

When this supervisor is added as a child to another supervisor, it will spawn its own OS threads and Tokio runtime instead of running on the parent’s ambient runtime.

This provides runtime isolation, which can be useful for:

• CPU-bound work that shouldn’t block the parent’s runtime
• Isolating failures in one part of the system
• Using different runtime configurations (for example, single-threaded vs multi-threaded)

pub fn add_worker<S, T>(&mut self, child: T)

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

Adds a worker (or nested supervisor) to the supervisor.

A worker can be anything that implements the Supervisable trait. A Supervisor can also be added as a worker and managed in a nested fashion, known as a supervision tree.

See ChildSpecification for more details on how workers are represented internally and what options are available to configure.

pub async fn run(&mut self) -> Result<(), SupervisorError>

Runs the supervisor forever.

Errors

If the supervisor exceeds its restart limits, or fails to initialize a child process, an error is returned.

pub async fn run_with_shutdown<F: Future + Send + 'static>( &mut self, shutdown: F, ) -> Result<(), SupervisorError>

Runs the supervisor until shutdown is triggered.

When shutdown resolves, the supervisor will shutdown all child processes according to their shutdown strategy, and then return.

Errors

If the supervisor exceeds its restart limits, or fails to initialize a child process, an error is returned.

Trait Implementations

impl From<Supervisor> for ChildSpecification<SupervisorSpec>

fn from(supervisor: Supervisor) -> Self

Converts to this type from the input type.