Struct Supervisor 

pub struct Supervisor { /* private fields */ }

Builder for constructing and starting a supervisor.

Supervisor provides a fluent API for registering tasks, setting up prerequisites, and configuring global runtime options like concurrency limits and persistence.

Example

use foxtive_supervisor::{Supervisor, SupervisedTask};

struct MyTask;
#[async_trait::async_trait]
impl SupervisedTask for MyTask {
    fn id(&self) -> &'static str { "my-task" }
    async fn run(&self) -> foxtive_supervisor::SupervisorResult<()> { Ok(()) }
}

#[tokio::main]
async fn main() {
    Supervisor::new()
        .add(MyTask)
        .start_and_wait_any()
        .await
        .unwrap();
}

Implementations

impl Supervisor

pub fn new() -> Self

Create a new, empty supervisor.

pub fn add<T: SupervisedTask + 'static>(self, task: T) -> Self

Add a task to be supervised.

The task must implement the SupervisedTask trait.

pub fn add_many<T: SupervisedTask + 'static>(self, tasks: Vec<T>) -> Self

Add multiple tasks of the same type.

pub fn add_boxed(self, task: Box<dyn SupervisedTask>) -> Self

Add a task already wrapped in a Box.

Useful when managing a heterogeneous collection of tasks.

pub fn add_arc(self, task: Arc<dyn SupervisedTask>) -> Self

Add a task already wrapped in an Arc.

This is the most efficient way to add a task if you already have an Arc handle.

pub fn with_global_concurrency_limit(self, limit: usize) -> Self

Set a global concurrency limit for the supervisor.

This limits how many tasks can be in their run() loop simultaneously. It’s useful for preventing resource exhaustion during massive task restarts.

pub fn with_event_channel_capacity(self, capacity: usize) -> Self

Set the event broadcast channel capacity.

The default is 1024. Increase this if you have many tasks emitting events rapidly and observe lagged event warnings.

pub fn add_listener(self, listener: Arc<dyn SupervisorEventListener>) -> Self

Register an event listener to observe lifecycle events.

Event listeners receive notifications for task starts, failures, restarts, etc.

pub fn with_state_store(self, store: Arc<dyn TaskStateStore>) -> Self

Set a custom state store for persisting task states across restarts.

The supervisor will use this store to load previous attempt counts and failure metadata before starting tasks, and will update it as tasks run.

pub fn require<F>(self, name: &'static str, fut: F) -> Self

where F: Future<Output = SupervisorResult<()>> + Send + 'static,

Require a named async gate to resolve before any supervised task starts.

Prerequisites run sequentially in the order they were registered. If any prerequisite fails, the supervisor aborts startup.

pub fn require_fn<F, Fut>(self, name: &'static str, f: F) -> Self

where F: FnOnce() -> Fut + Send + 'static, Fut: Future<Output = SupervisorResult<()>> + Send + 'static,

Require a named async gate using a closure.

pub fn runtime(self) -> TaskRuntime

Consume the builder and return the underlying TaskRuntime.

Note: This does not start the tasks. You must call start_all() on the returned runtime.

pub async fn start(self) -> Result<TaskRuntime, SupervisorError>

Start all registered tasks and return the TaskRuntime handle.

This validates the dependency graph and executes prerequisites before spawning tasks.

Errors

Returns SupervisorError if prerequisites fail or if the dependency graph is invalid.

pub async fn start_and_wait_any( self, ) -> Result<SupervisionResult, SupervisorError>

Start all tasks and block until the first one terminates.

Errors

Returns SupervisorError if startup validation or prerequisites fail.

pub async fn start_and_wait_all( self, ) -> Result<Vec<SupervisionResult>, SupervisorError>

Start all tasks and block until all have terminated.

Errors

Returns SupervisorError if startup validation or prerequisites fail.

Trait Implementations

impl Default for Supervisor

fn default() -> Self

Create a new supervisor with default settings.