Struct Service

pub struct Service { /* private fields */ }

A collection of related tasks that succeed or fail together, consisting of:

• A set of primary tasks, which control the lifetime of the service in the happy path. When all primary tasks complete successfully or have been cancelled, the service will start a graceful shutdown.

• A set of secondary tasks, which run alongside the primary tasks, but do not extend the service’s lifetime (The service will not wait for all secondary tasks to complete or be cancelled before triggering a shutdown).

• A set of exit signals, which are executed when the service wants to trigger graceful shutdown.

Any task (primary or secondary) failing by returning an error, or panicking, will also trigger a graceful shutdown.

If graceful shutdown takes longer than the grace period, or another task fails during shutdown, all remaining tasks are aborted and dropped immediately. Tasks are expected to clean-up after themselves when dropped (e.g. if a task has spawned its own sub-tasks, these should also be aborted when the parent task is dropped).

Implementations

impl Service

pub fn new() -> Self

Create a new, empty service.

pub fn spawn( self, task: impl Future<Output = Result<()>> + Send + 'static, ) -> Self

Add a primary task.

The task will start running in the background immediately, once added. It is expected to clean up after itself when it is dropped, which will happen when it is aborted (non-graceful shutdown).

pub fn spawn_aborting( self, task: impl Future<Output = Result<()>> + Send + 'static, ) -> Self

Add a primary task that aborts immediately on graceful shutdown.

This is useful for tasks that don’t need a graceful shutdown.

pub fn with_shutdown_signal( self, exit: impl Future<Output = ()> + Send + 'static, ) -> Self

Add a shutdown signal.

This future will be executed when the service is instructed to shutdown gracefully, before a grace period timer starts (in which the task receiving the shutdown signal is expected to wind down and exit cleanly).

Evaluation order of shutdown signals is non-determinate.

pub fn merge(self, other: Service) -> Self

Add the tasks and signals from other into self.

pub fn attach(self, other: Service) -> Self

Attach other to self as a secondary service.

All its tasks (primary and secondary) will be treated as secondary tasks of self.

pub async fn main(self) -> Result<(), Error>

Runs the service, waiting for interrupt signals from the operating system to trigger graceful shutdown, within the defualt grace period.

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

Wait until all primary tasks in the service either complete successfully or are cancelled, or one task fails.

This operation does not consume the service, so that it can be interacted with further in case of an error.

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

Trigger a graceful shutdown of the service.

Returns with an error if any of the constituent tasks produced an error during shutdown, otherwise waits for all tasks (primary and secondy) to complete successfully.

Trait Implementations

impl Debug for Service

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Service

fn default() -> Service

Returns the “default value” for a type.

impl Sync for Service