Full rewrite (#64)

## Full rewrite of this crate

The main problem was that the API followed the implementation and not the other way round. Some API improvements weren't possible because they weren't implementable.

With the new implementation, several API decisions that bothered me were finally improved.

### Breaking Changes
- Remove `Toplevel::nested` (which was a rather ugly hack), replace with configurable `ErrorAction`s.
- Remove partial shutdown mechanism; replace with `NestedSubsystem::initiate_shutdown()` and `NestedSubsystem::join()`.
- Add `SubsystemHandle::wait_for_children()`.
- Remove `Toplevel::start`. Instead, add a single subsystem to `Toplevel::new`, which can then spawn all further subsystems.
- Rework `SubsystemHandle::start`; it now takes a `SubsystemBuilder` object that provides further subsystem configuration options.
- Minimum Supported Rust Version (MSRV) is now `1.63.0`.


The rest of the API is almost identical and migration should be mostly straight forward.

.github/workflows/audit.yml

@@ -12,6 +12,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - uses: actions-rs/audit-check@v1
+      - uses: rustsec/audit-check@v1.4.1
         with:
           token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/ci.yml

@@ -48,6 +48,23 @@ jobs:
       - name: Run cargo test
         run: cargo test -- --test-threads 1
 
+  msrv:
+    name: Minimum Supported Rust Version
+    runs-on: ubuntu-latest
+    env:
+      RUSTFLAGS: "-D warnings"
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v3
+
+      - name: Install MSRV toolchain
+        uses: dtolnay/[email protected]
+
+      #- uses: Swatinem/rust-cache@v1
+
+      - name: Run cargo build
+        run: cargo build
+
   lints:
     name: Lints
     runs-on: ubuntu-latest
@@ -115,7 +132,7 @@ jobs:
     runs-on: ubuntu-latest
     environment: production
     if: github.event_name == 'release'
-    needs: [build, test, lints, docs, leaks]
+    needs: [build, test, msrv, lints, docs, leaks]
     steps:
       - name: Checkout sources
         uses: actions/checkout@v3

Cargo.toml

@@ -1,8 +1,9 @@
 [package]
 name = "tokio-graceful-shutdown"
 authors = ["Finomnis <[email protected]>"]
-version = "0.13.0"
-edition = "2018"
+version = "0.14.0"
+edition = "2021"
+rust-version = "1.63"
 license = "MIT OR Apache-2.0"
 readme = "README.md"
 repository = "https://github.com/Finomnis/tokio-graceful-shutdown"
@@ -20,39 +21,35 @@ exclude = [
 ]
 
 [dependencies]
-# Error definitions
-thiserror = "1.0.32"
-miette = "5.3.0"
+tracing = { version = "0.1.37", default-features = false }
 
-# For async utilities
-tokio = { version = "1.20.1", default-features = false, features = [
+tokio = { version = "1.32.0", default-features = false, features = [
     "signal",
     "rt",
     "macros",
     "time",
 ] }
-tokio-util = { version = "0.7.2", default-features = false }
-futures = "0.3.23"
-async-recursion = "1.0.0"
-pin-project-lite = "0.2.9"
+tokio-util = { version = "0.7.8", default-features = false }
 
-# For 'IntoSubsystem' trait
-async-trait = "0.1.57"
-
-# For logging
-log = "0.4.17"
+pin-project-lite = "0.2.13"
+thiserror = "1.0.49"
+miette = "5.10.0"
+async-trait = "0.1.73"
+atomic = "0.6.0"
+bytemuck = { version = "1.14.0", features = ["derive"] }
 
 [dev-dependencies]
 # Error propagation
-anyhow = "1.0.61"
+anyhow = "1.0.75"
 eyre = "0.6.8"
-miette = { version = "5.3.0", features = ["fancy"] }
+miette = { version = "5.10.0", features = ["fancy"] }
 
 # Logging
-env_logger = "0.10.0"
+tracing-subscriber = "0.3.17"
+tracing-test = "0.2.4"
 
 # Tokio
-tokio = { version = "1.20.1", features = ["full"] }
+tokio = { version = "1.32.0", features = ["full"] }
 
 # Hyper example
 hyper = { version = "0.14.20", features = ["full"] }

README.md

@@ -40,17 +40,19 @@ This subsystem can now be executed like this:
 ```rust
 #[tokio::main]
 async fn main() -> Result<()> {
-    Toplevel::new()
-        .start("Subsys1", subsys1)
-        .catch_signals()
-        .handle_shutdown_requests(Duration::from_millis(1000))
-        .await
-        .map_err(Into::into)
+    Toplevel::new(|s| async move {
+        s.start(SubsystemBuilder::new("Subsys1", subsys1))
+    })
+    .catch_signals()
+    .handle_shutdown_requests(Duration::from_millis(1000))
+    .await
+    .map_err(Into::into)
 }
 ```
 
 The `Toplevel` object is the root object of the subsystem tree.
-Subsystems can then be started using the `start()` functionality of the toplevel object.
+Subsystems can then be started in it using the `start()` method
+of its `SubsystemHandle` object.
 
 The `catch_signals()` method signals the `Toplevel` object to listen for SIGINT/SIGTERM/Ctrl+C and initiate a shutdown thereafter.
 

examples/01_normal_shutdown.rs

@@ -7,40 +7,42 @@
 //! If custom arguments for the subsystem coroutines are required,
 //! a struct has to be used instead, as seen in other examples.
 
-use env_logger::{Builder, Env};
 use miette::Result;
 use tokio::time::{sleep, Duration};
-use tokio_graceful_shutdown::{SubsystemHandle, Toplevel};
+use tokio_graceful_shutdown::{SubsystemBuilder, SubsystemHandle, Toplevel};
 
 async fn subsys1(subsys: SubsystemHandle) -> Result<()> {
-    log::info!("Subsystem1 started.");
+    tracing::info!("Subsystem1 started.");
     subsys.on_shutdown_requested().await;
-    log::info!("Shutting down Subsystem1 ...");
+    tracing::info!("Shutting down Subsystem1 ...");
     sleep(Duration::from_millis(400)).await;
-    log::info!("Subsystem1 stopped.");
+    tracing::info!("Subsystem1 stopped.");
     Ok(())
 }
 
 async fn subsys2(subsys: SubsystemHandle) -> Result<()> {
-    log::info!("Subsystem2 started.");
+    tracing::info!("Subsystem2 started.");
     subsys.on_shutdown_requested().await;
-    log::info!("Shutting down Subsystem2 ...");
+    tracing::info!("Shutting down Subsystem2 ...");
     sleep(Duration::from_millis(500)).await;
-    log::info!("Subsystem2 stopped.");
+    tracing::info!("Subsystem2 stopped.");
     Ok(())
 }
 
 #[tokio::main]
 async fn main() -> Result<()> {
     // Init logging
-    Builder::from_env(Env::default().default_filter_or("debug")).init();
+    tracing_subscriber::fmt()
+        .with_max_level(tracing::Level::TRACE)
+        .init();
 
-    // Create toplevel
-    Toplevel::new()
-        .start("Subsys1", subsys1)
-        .start("Subsys2", subsys2)
-        .catch_signals()
-        .handle_shutdown_requests(Duration::from_millis(1000))
-        .await
-        .map_err(Into::into)
+    // Setup and execute subsystem tree
+    Toplevel::new(|s| async move {
+        s.start(SubsystemBuilder::new("Subsys1", subsys1));
+        s.start(SubsystemBuilder::new("Subsys2", subsys2));
+    })
+    .catch_signals()
+    .handle_shutdown_requests(Duration::from_millis(1000))
+    .await
+    .map_err(Into::into)
 }

examples/02_structs.rs

@@ -2,27 +2,26 @@
 //! custom parameters to be passed to the subsystem.
 //!
 //! There are two ways of using structs as subsystems, by either
-//! wrapping them in an async closure, or by implementing the
+//! wrapping them in a closure, or by implementing the
 //! IntoSubsystem trait. Note, though, that the IntoSubsystem
 //! trait requires an additional dependency, `async-trait`.
 
 use async_trait::async_trait;
-use env_logger::{Builder, Env};
 use miette::Result;
 use tokio::time::{sleep, Duration};
-use tokio_graceful_shutdown::{IntoSubsystem, SubsystemHandle, Toplevel};
+use tokio_graceful_shutdown::{IntoSubsystem, SubsystemBuilder, SubsystemHandle, Toplevel};
 
 struct Subsystem1 {
     arg: u32,
 }
 
 impl Subsystem1 {
     async fn run(self, subsys: SubsystemHandle) -> Result<()> {
-        log::info!("Subsystem1 started. Extra argument: {}", self.arg);
+        tracing::info!("Subsystem1 started. Extra argument: {}", self.arg);
         subsys.on_shutdown_requested().await;
-        log::info!("Shutting down Subsystem1 ...");
+        tracing::info!("Shutting down Subsystem1 ...");
         sleep(Duration::from_millis(500)).await;
-        log::info!("Subsystem1 stopped.");
+        tracing::info!("Subsystem1 stopped.");
         Ok(())
     }
 }
@@ -34,29 +33,32 @@ struct Subsystem2 {
 #[async_trait]
 impl IntoSubsystem<miette::Report> for Subsystem2 {
     async fn run(self, subsys: SubsystemHandle) -> Result<()> {
-        log::info!("Subsystem2 started. Extra argument: {}", self.arg);
+        tracing::info!("Subsystem2 started. Extra argument: {}", self.arg);
         subsys.on_shutdown_requested().await;
-        log::info!("Shutting down Subsystem2 ...");
+        tracing::info!("Shutting down Subsystem2 ...");
         sleep(Duration::from_millis(500)).await;
-        log::info!("Subsystem2 stopped.");
+        tracing::info!("Subsystem2 stopped.");
         Ok(())
     }
 }
 
 #[tokio::main]
 async fn main() -> Result<()> {
     // Init logging
-    Builder::from_env(Env::default().default_filter_or("debug")).init();
+    tracing_subscriber::fmt()
+        .with_max_level(tracing::Level::TRACE)
+        .init();
 
     let subsys1 = Subsystem1 { arg: 42 };
     let subsys2 = Subsystem2 { arg: 69 };
 
-    // Create toplevel
-    Toplevel::new()
-        .start("Subsys1", |a| subsys1.run(a))
-        .start("Subsys2", subsys2.into_subsystem())
-        .catch_signals()
-        .handle_shutdown_requests(Duration::from_millis(1000))
-        .await
-        .map_err(Into::into)
+    // Setup and execute subsystem tree
+    Toplevel::new(|s| async move {
+        s.start(SubsystemBuilder::new("Subsys1", |a| subsys1.run(a)));
+        s.start(SubsystemBuilder::new("Subsys2", subsys2.into_subsystem()));
+    })
+    .catch_signals()
+    .handle_shutdown_requests(Duration::from_millis(1000))
+    .await
+    .map_err(Into::into)
 }

examples/03_shutdown_timeout.rs

@@ -4,30 +4,32 @@
 //! so the subsystem gets cancelled and the program returns an appropriate
 //! error code.
 
-use env_logger::{Builder, Env};
 use miette::Result;
 use tokio::time::{sleep, Duration};
-use tokio_graceful_shutdown::{SubsystemHandle, Toplevel};
+use tokio_graceful_shutdown::{SubsystemBuilder, SubsystemHandle, Toplevel};
 
 async fn subsys1(subsys: SubsystemHandle) -> Result<()> {
-    log::info!("Subsystem1 started.");
+    tracing::info!("Subsystem1 started.");
     subsys.on_shutdown_requested().await;
-    log::info!("Shutting down Subsystem1 ...");
+    tracing::info!("Shutting down Subsystem1 ...");
     sleep(Duration::from_millis(2000)).await;
-    log::info!("Subsystem1 stopped.");
+    tracing::info!("Subsystem1 stopped.");
     Ok(())
 }
 
 #[tokio::main]
 async fn main() -> Result<()> {
     // Init logging
-    Builder::from_env(Env::default().default_filter_or("debug")).init();
+    tracing_subscriber::fmt()
+        .with_max_level(tracing::Level::TRACE)
+        .init();
 
-    // Create toplevel
-    Toplevel::new()
-        .start("Subsys1", subsys1)
-        .catch_signals()
-        .handle_shutdown_requests(Duration::from_millis(500))
-        .await
-        .map_err(Into::into)
+    // Setup and execute subsystem tree
+    Toplevel::new(|s| async move {
+        s.start(SubsystemBuilder::new("Subsys1", subsys1));
+    })
+    .catch_signals()
+    .handle_shutdown_requests(Duration::from_millis(500))
+    .await
+    .map_err(Into::into)
 }

examples/04_subsystem_finished.rs

@@ -1,19 +1,18 @@
-//! This subsystem demonstrates that subsystems can also stop
+//! This example demonstrates that subsystems can also stop
 //! prematurely.
 //!
 //! Returning Ok(()) from a subsystem indicates that the subsystem
 //! stopped intentionally, and no further measures by the runtime are performed.
 //! (unless there are no more subsystems left, in that case TopLevel would shut down anyway)
 
-use env_logger::{Builder, Env};
 use miette::Result;
 use tokio::time::{sleep, Duration};
-use tokio_graceful_shutdown::{SubsystemHandle, Toplevel};
+use tokio_graceful_shutdown::{SubsystemBuilder, SubsystemHandle, Toplevel};
 
 async fn subsys1(_subsys: SubsystemHandle) -> Result<()> {
-    log::info!("Subsystem1 started.");
+    tracing::info!("Subsystem1 started.");
     sleep(Duration::from_millis(500)).await;
-    log::info!("Subsystem1 stopped.");
+    tracing::info!("Subsystem1 stopped.");
 
     // Task ends without an error. This should not cause the main program to shutdown,
     // because Subsys2 is still running.
@@ -28,14 +27,17 @@ async fn subsys2(subsys: SubsystemHandle) -> Result<()> {
 #[tokio::main]
 async fn main() -> Result<()> {
     // Init logging
-    Builder::from_env(Env::default().default_filter_or("debug")).init();
+    tracing_subscriber::fmt()
+        .with_max_level(tracing::Level::TRACE)
+        .init();
 
-    // Create toplevel
-    Toplevel::new()
-        .start("Subsys1", subsys1)
-        .start("Subsys2", subsys2)
-        .catch_signals()
-        .handle_shutdown_requests(Duration::from_millis(1000))
-        .await
-        .map_err(Into::into)
+    // Setup and execute subsystem tree
+    Toplevel::new(|s| async move {
+        s.start(SubsystemBuilder::new("Subsys1", subsys1));
+        s.start(SubsystemBuilder::new("Subsys2", subsys2));
+    })
+    .catch_signals()
+    .handle_shutdown_requests(Duration::from_millis(1000))
+    .await
+    .map_err(Into::into)
 }