Trait SupervisedTask 

pub trait SupervisedTask: Send + Sync {
    // Required methods
    fn id(&self) -> &'static str;
    fn run<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = SupervisorResult<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;

    // Provided methods
    fn name(&self) -> String { ... }
    fn dependencies(&self) -> &'static [&'static str] { ... }
    fn restart_policy(&self) -> RestartPolicy { ... }
    fn backoff_strategy(&self) -> BackoffStrategy { ... }
    fn priority(&self) -> i32 { ... }
    fn concurrency_limit(&self) -> Option<usize> { ... }
    fn circuit_breaker(&self) -> Option<CircuitBreakerConfig> { ... }
    fn shutdown_timeout(&self) -> Duration { ... }
    fn initial_delay(&self) -> Option<Duration> { ... }
    fn jitter(&self) -> Option<(Duration, Duration)> { ... }
    fn min_restart_interval(&self) -> Option<Duration> { ... }
    fn execution_time_window(&self) -> Option<(Option<u8>, Option<u8>)> { ... }
    fn group_id(&self) -> Option<&'static str> { ... }
    fn conditional_dependencies(
        &self,
    ) -> Vec<(&'static str, Box<dyn Fn() -> bool + Send + Sync>)> { ... }
    fn active_dependencies(&self) -> Vec<&'static str> { ... }
    fn setup<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = SupervisorResult<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn cleanup<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn should_restart<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _attempt: usize,
        _last_error: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn health_check<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = HealthStatus> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn metrics<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Option<TaskMetrics>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn on_restart<'life0, 'async_trait>(
        &'life0 self,
        _attempt: usize,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn on_error<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _error: &'life1 str,
        _attempt: usize,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn on_panic<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _panic_info: &'life1 str,
        _attempt: usize,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn on_shutdown<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
}

Core trait for any long-running task that needs supervision

Required Methods

fn id(&self) -> &'static str

Unique identifier for this task (used in logs, monitoring, and dependency resolution)

fn run<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = SupervisorResult<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Main task execution - this should run until completion or error

Provided Methods

fn name(&self) -> String

Human-readable name for this task (used in logs and monitoring)

fn dependencies(&self) -> &'static [&'static str]

Declare task IDs that must complete setup before this task starts

fn restart_policy(&self) -> RestartPolicy

Restart policy when task fails or panics

fn backoff_strategy(&self) -> BackoffStrategy

Backoff strategy between restart attempts

fn priority(&self) -> i32

Priority of the task (higher values = higher priority) Used when concurrency limits are reached to decide which tasks start first

fn concurrency_limit(&self) -> Option<usize>

Optional concurrency limit for this specific task This is useful if the task is part of a pool or if multiple instances exist

fn circuit_breaker(&self) -> Option<CircuitBreakerConfig>

Configuration for the task’s circuit breaker If None, the circuit breaker is disabled for this task

fn shutdown_timeout(&self) -> Duration

Maximum time to wait for the task to finish its run() and on_shutdown() before forced termination during supervisor shutdown.

fn initial_delay(&self) -> Option<Duration>

Optional initial delay before the first execution

This is useful for staggering task startup to prevent thundering herd problems or for giving dependencies time to initialize.

fn jitter(&self) -> Option<(Duration, Duration)>

Optional jitter to add randomness to the initial delay

Returns a tuple of (min_jitter, max_jitter) that will be randomly added to the initial delay. This helps prevent thundering herd problems in distributed deployments where multiple instances start simultaneously.

Example: If initial_delay is 5s and jitter is (0, 2s), the actual delay will be between 5s and 7s.

fn min_restart_interval(&self) -> Option<Duration>

Minimum time between restart attempts (rate limiting)

This prevents tasks from restarting too frequently, which can overwhelm external services or resources. If a task fails and wants to restart, it will wait at least this duration before attempting again.

This is applied in addition to the backoff strategy - the actual delay will be the maximum of the backoff delay and this minimum restart interval.

fn execution_time_window(&self) -> Option<(Option<u8>, Option<u8>)>

Time window restrictions for task execution

Returns optional start and end times (as hours in 24-hour format) during which the task is allowed to run. Outside this window, the task will wait until the next allowed time.

Example: Some((9, 17)) means the task can only run between 9 AM and 5 PM. Use None for either value to indicate no restriction on that boundary.

Note: Times are evaluated in UTC by default.

fn group_id(&self) -> Option<&'static str>

Task group identifier for atomic operations

Tasks with the same group ID can be started, stopped, or managed together. This is useful for related tasks that should be treated as a unit.

Example: A database connection pool and its query processor might be in the same group so they start and stop together.

fn conditional_dependencies( &self, ) -> Vec<(&'static str, Box<dyn Fn() -> bool + Send + Sync>)>

Conditional dependencies based on environment or runtime conditions

Returns a list of dependencies that are only active when certain conditions are met. Each tuple contains (dependency_id, condition_function). The condition function receives the current environment context and returns true if the dependency should be enforced.

Example: Only depend on “cache-service” if USE_CACHE env var is set

vec![("cache-service", Box::new(|| std::env::var("USE_CACHE").is_ok()))]

fn active_dependencies(&self) -> Vec<&'static str>

Get all active dependencies (regular + conditional that evaluate to true)

This combines regular dependencies with conditional dependencies whose conditions currently evaluate to true.

fn setup<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = SupervisorResult<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Called once before the first run() attempt

fn cleanup<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Called after task stops (success, failure, or panic)

Purpose: Internal resource cleanup and teardown.

This hook is called automatically by the supervision loop whenever a task’s run() method completes (successfully or with error) or panics. It’s meant for:

• Closing database connections
• Releasing file handles
• Dropping temporary resources
• Any internal cleanup needed before restart or shutdown

When it’s called:

• After every run() completion (success or failure)
• After a panic is caught
• When task receives Stop command
• During supervisor shutdown

Important: This is NOT for graceful shutdown logic. Use on_shutdown() instead if you need to perform actions specifically during supervisor-initiated shutdown.

fn should_restart<'life0, 'life1, 'async_trait>( &'life0 self, _attempt: usize, _last_error: &'life1 str, ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Dynamic restart control - called before each restart

fn health_check<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = HealthStatus> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Health check for monitoring endpoints

fn metrics<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Option<TaskMetrics>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Return task-specific metrics (optional)

fn on_restart<'life0, 'async_trait>( &'life0 self, _attempt: usize, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Called before each restart (not called on first attempt)

fn on_error<'life0, 'life1, 'async_trait>( &'life0 self, _error: &'life1 str, _attempt: usize, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Called when run() returns an error

fn on_panic<'life0, 'life1, 'async_trait>( &'life0 self, _panic_info: &'life1 str, _attempt: usize, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Called when run() panics

fn on_shutdown<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Called when the service is shutting down

Purpose: Graceful shutdown hook for external/user-defined cleanup.

This hook is called ONLY during supervisor-initiated graceful shutdown, AFTER the supervision loop has terminated. It’s meant for:

• Flushing buffers to disk/network
• Sending final notifications
• Performing graceful disconnections
• Any user-defined shutdown logic that should run once at the end

When it’s called:

• ONLY during TaskRuntime::shutdown()
• AFTER the supervision loop ends
• AFTER cleanup() has been called
• Once per task, in dependency-aware order

Key difference from cleanup():

• cleanup() = Internal teardown, called after EVERY run() completion
• on_shutdown() = Graceful shutdown, called ONCE during supervisor shutdown

Example:

async fn on_shutdown(&self) {
    // Flush pending messages
    self.message_queue.flush().await.ok();
    // Notify monitoring service
    self.notify_shutdown().await.ok();
}

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors