Crate tokio_graceful_shutdown

This crate provides utility functions to perform a graceful shutdown on tokio-rs based services.

Specifically, it provides:

• Listening for shutdown requests from within subsystems
• Manual shutdown initiation from within subsystems
• Automatic shutdown on
  • SIGINT/SIGTERM/Ctrl+C
  • Subsystem failure
  • Subsystem panic
• Clean shutdown procedure with timeout and error propagation
• Subsystem nesting
• Partial shutdown of a selected subsystem tree

Example

This example shows a minimal example of how to launch an asynchronous subsystem with the help of this crate.

It contains a countdown subsystem that will end the program after 10 seconds. During the countdown, the program will react to Ctrl-C/SIGINT/SIGTERM and will cancel the countdown task accordingly.

use tokio_graceful_shutdown::{Error, SubsystemHandle, Toplevel};
use env_logger::{Builder, Env};
use tokio::time::{sleep, Duration};

async fn countdown() {
    for i in (1..=5).rev() {
        log::info!("Shutting down in: {}", i);
        sleep(Duration::from_millis(1000)).await;
    }
}

async fn countdown_subsystem(subsys: SubsystemHandle) -> Result<(), Error> {
    tokio::select! {
        _ = subsys.on_shutdown_requested() => {
            log::info!("Countdown cancelled.");
        },
        _ = countdown() => {
            subsys.request_shutdown();
        }
    };

    Ok(())
}

#[tokio::main]
async fn main() -> Result<(), Error> {
    // Init logging
    Builder::from_env(Env::default().default_filter_or("debug")).init();

    // Create toplevel
    Toplevel::new()
        .start("Countdown", countdown_subsystem)
        .catch_signals()
        .handle_shutdown_requests(Duration::from_millis(1000))
        .await
}

There are a couple of things to note here.

For one, the Toplevel object represents the root object of the subsystem tree and is the main entry point of how to interact with this crate. Subsystems can then be started using the start() functionality of the toplevel object.

The catch_signals() method signals the Toplevel object to listen for SIGINT/SIGTERM/Ctrl+C and initiate a shutdown thereafter.

handle_shutdown_requests() is the final and most important method of Toplevel. It idles until the program enters the shutdown mode. Then, it collects all the return values of the subsystems and determines the global error state, and makes sure shutdown happens within the given timeout. Lastly, it returns an error value that can be directly used as a return code for main().

Further, the way to register and start a new submodule ist to provide a submodule function/lambda to Toplevel::start or SubsystemHandle::start. If additional arguments shall to be provided to the submodule, it is necessary to create a submodule struct. Further details can be seen in the examples folder of the repository.

Finally, you can see the SubsystemHandle object that gets provided to the subsystem. It is the main way of the subsystem to communicate with this crate. It enables the subsystem to start nested subsystems, to react to shutdown requests or to initiate a shutdown.

Structs

NestedSubsystem

A nested subsystem. Can be used to perform a partial shutdown.

SubsystemHandle

The handle given to each subsystem through which the subsystem can interact with this crate.

Toplevel

Acts as the base for the subsystem tree and forms the entry point for any interaction with this crate.

Enums

PartialShutdownError

This enum contains all the possible errors that a partial shutdown could cause.

Type Definitions

Error