Struct Supervisor 

pub struct Supervisor { /* private fields */ }

Supervises the Runledger runtime loops spawned for a worker process.

A supervisor owns the worker, scheduler, and reaper task handles selected by SupervisorBuilder. Use Self::run_until_shutdown for a typical worker process that should exit on either an external shutdown signal or an internal runtime task failure.

Dropping a supervisor requests shutdown and detaches the task handles. Call Self::shutdown or Self::join when the owning process needs to observe panics or unexpected task exits.

Implementations

impl Supervisor

pub fn builder( pool: &DbPool, config: JobsConfig, ) -> Result<SupervisorBuilder<'_>, RuntimeError>

Returns a builder for a supervisor over a shared pool and runtime configuration.

This validates that the caller is inside the Tokio runtime that will own spawned supervisor tasks.

pub fn shutdown_handle(&self) -> SupervisorShutdown

Returns a cloneable shutdown handle that can request shutdown without owning the supervisor task joins.

pub fn request_shutdown(&self)

Requests graceful shutdown of all supervised loops.

pub fn is_shutdown_requested(&self) -> bool

Returns whether shutdown has been requested through this supervisor or a clone of its shutdown handle.

pub async fn join(self) -> Result<()>

Waits for all supervised loops to exit.

With the default long-running loops, this method waits until shutdown is requested through a SupervisorShutdown handle or until a task exits. If a loop exits before shutdown was requested, the remaining loops are asked to shut down and the first observed error is returned. Additional task failures observed while draining are logged. This method does not impose a deadline; use Self::shutdown_with_timeout when the caller owns shutdown and needs a bounded wait.

pub async fn shutdown(self) -> Result<()>

Requests graceful shutdown and waits for all supervised loops to exit.

If a loop exits before shutdown was requested, the remaining loops are asked to shut down and the pre-existing task exit is reported, even when that exit is only observed after shutdown begins. This method does not impose a deadline. Use Self::shutdown_with_timeout when the owning process needs a shutdown budget; externally timing out this consuming future can detach still-running task handles.

pub async fn run_until_shutdown<F>( self, shutdown: F, timeout: Duration, ) -> Result<()>

where F: Future<Output = ()>,

Waits until shutdown resolves or a supervised task fails, then exits.

If shutdown resolves first, graceful shutdown is requested and the supervisor waits up to timeout for all loops to exit. If a loop panics or exits unexpectedly before shutdown resolves, shutdown is requested for the remaining loops and the original task error is returned after those loops drain or a timeout is reported. If shutdown is requested through a SupervisorShutdown handle and every loop exits cleanly before shutdown resolves, this returns successfully.

This is the preferred method for worker binaries because it observes internal task failures during normal operation while still applying a bounded shutdown budget to cooperative process termination.

If timeout is too large to represent as a runtime deadline, this returns RuntimeError::ShutdownTimeoutTooLarge immediately. A zero timeout requests shutdown, aborts tasks without waiting for cooperative exits, and reports RuntimeError::ShutdownTimeout.

If the initial timeout validation fails before shutdown resolves, the supervisor is still dropped, so shutdown is requested, but task handles are not aborted or drained. If a deadline overflow is detected after shutdown begins, remaining tasks are aborted and drained before returning.

pub async fn shutdown_with_timeout(self, timeout: Duration) -> Result<()>

Requests graceful shutdown and waits up to timeout for all supervised loops to exit.

If a loop had already exited before this method begins shutdown, that failure is returned after the remaining loops have had the same shutdown budget to exit cooperatively. If the timeout expires, remaining tasks are aborted and drained with a bounded cleanup attempt before a timeout error is returned. Abort cleanup can make total wall-clock time exceed timeout by up to one second, or timeout, whichever is smaller. A zero timeout requests shutdown, immediately aborts tasks that did not already finish, and reports RuntimeError::ShutdownTimeout.

If timeout is too large to represent as a runtime deadline, this returns RuntimeError::ShutdownTimeoutTooLarge immediately. The supervisor is still dropped, so shutdown is requested, but task handles are not aborted or drained.

Trait Implementations

impl Drop for Supervisor

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.