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][saluki_common::resource_tracking::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, and statistics about task polls (poll count, poll duration) are collected.

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 with_shutdown_budget(self, budget: Duration) -> Self

Bounds how long this supervisor waits for its worker children during shutdown.

Without a budget, a supervisor waits as long as each child’s own ShutdownStrategy allows, and waits indefinitely for any child that has no finite deadline of its own. A budget makes the supervisor responsible for the deadline instead: children need no individual timeouts, and whatever is still running when the budget elapses is forcefully aborted – each one named in the logs, and counted in the resulting SupervisorError::ShutdownTimedOut.

The budget is a ceiling, not a replacement: a child that also carries its own finite deadline is still held to whichever elapses first.

Two kinds of child are outside it. A nested supervisor is never cut off by its parent’s budget – it bounds its own subtree, and aborting it would both truncate that drain and, for a supervisor running on a dedicated runtime, fail to stop it at all. A ShutdownStrategy::Brutal child is aborted up front and never waited on. Neither can a budget bound work that ignores cancellation, since an abort only takes effect at an await point.

Use this where one deadline for a whole subtree is more meaningful than a guess per worker – a topology component and its background tasks, for instance, where what matters is that the component as a whole stops in time.

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.