Trait RunnableCapability 

pub trait RunnableCapability: Send + Sync {
    // Required methods
    fn start<'life0, 'async_trait>(
        &'life0 self,
        cancel: CancellationToken,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn stop<'life0, 'async_trait>(
        &'life0 self,
        deadline_token: CancellationToken,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
}

Capability for modules that have a long-running background task.

Shutdown Contract

The stop method receives a deadline token that implements two-phase shutdown:

1. Graceful stop request: When stop(deadline_token) is called, the deadline_token is not cancelled. This is the signal to begin graceful shutdown.

2. Hard-stop deadline: After the runtime’s shutdown_deadline expires (default 30s), the deadline_token is cancelled. This signals that graceful shutdown time is over and the module should abort immediately.

Recommended Implementation Pattern

async fn stop(&self, deadline_token: CancellationToken) -> anyhow::Result<()> {
    // 1. Request cooperative shutdown of child tasks
    self.request_graceful_shutdown();

    // 2. Wait for graceful completion OR hard-stop deadline
    tokio::select! {
        _ = self.wait_for_graceful_completion() => {
            // Graceful shutdown succeeded
        }
        _ = deadline_token.cancelled() => {
            // Deadline reached, force abort
            self.force_abort();
        }
    }
    Ok(())
}

Important Notes

• The deadline_token passed to stop() is a fresh token, not the root cancellation token that triggered the shutdown. This allows modules to implement real graceful shutdown.
• Modules should NOT assume the token is already cancelled when stop() is called.
• The WithLifecycle wrapper handles this contract automatically via its stop_timeout.

Required Methods

fn start<'life0, 'async_trait>( &'life0 self, cancel: CancellationToken, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

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

Start the module’s background task.

The cancel token is a child of the runtime’s root cancellation token. When cancelled, the module should stop its background work.

fn stop<'life0, 'async_trait>( &'life0 self, deadline_token: CancellationToken, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

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

Stop the module’s background task.

The deadline_token implements two-phase shutdown:

• Initially not cancelled: begin graceful shutdown
• When cancelled: graceful period expired, abort immediately

See trait-level documentation for the full shutdown contract.

Implementors

impl<T: Runnable> RunnableCapability for WithLifecycle<T>