Add tokio taskname registration for use in tokio-console

.github/workflows/ci.yml

@@ -30,14 +30,14 @@ jobs:
         uses: taiki-e/install-action@cross
 
       - name: Build
-        run: cross build --all-features --release --target=${{ matrix.target }}
+        run: cross build --release --target=${{ matrix.target }}
 
   build-examples:
     name: Build Examples
     runs-on: ubuntu-latest
     needs: [lints, docs]
     env:
-      RUSTFLAGS: "-D warnings"
+      RUSTFLAGS: "-D warnings --cfg tokio_unstable"
     steps:
       - name: Checkout sources
         uses: actions/checkout@v4
@@ -165,7 +165,7 @@ jobs:
         run: cargo fmt --all -- --check
 
       - name: Run cargo clippy
-        run: cargo clippy --all-features --all-targets -- -D warnings
+        run: cargo clippy --all-targets -- -D warnings
 
   docs:
     name: Documentation

.github/workflows/coverage.yml

@@ -23,10 +23,9 @@ jobs:
         uses: actions/checkout@v4
       - name: Install llvm-cov
         uses: taiki-e/install-action@cargo-llvm-cov
-      #- uses: Swatinem/rust-cache@v1
       - name: Compute Coverage
         run:
-          cargo llvm-cov --all-features --workspace --ignore-filename-regex tests.rs --codecov --output-path codecov.json
+          cargo llvm-cov --workspace --ignore-filename-regex tests.rs --codecov --output-path codecov.json
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v4
         env:

.github/workflows/rust-clippy.yml

@@ -43,7 +43,6 @@ jobs:
       - name: Run rust-clippy
         run:
           cargo clippy
-          --all-features
           --all-targets
           --message-format=json | clippy-sarif | tee rust-clippy-results.sarif | sarif-fmt
         continue-on-error: true

Cargo.toml

@@ -20,6 +20,9 @@ exclude = [
     "/UPCOMING_VERSION_CHANGES.txt",
 ]
 
+[features]
+tokio-unstable = ["tokio/tracing"]
+
 [dependencies]
 tracing = { version = "0.1.37", default-features = false }
 
@@ -67,10 +70,17 @@ headers = ">= 0.3.5"           # Required to fix minimal-versions
 serde_urlencoded = ">= 0.7.1"  # Required to fix minimal-versions
 unicode-linebreak = ">= 0.1.5" # Required to fix minimal-versions
 
+# tokio-console
+console-subscriber = "0.2.0"
+
 # For testing unix signals
 [target.'cfg(unix)'.dev-dependencies]
 nix = { version = "0.29.0", default-features = false, features = ["signal"] }
 
 # Make leak sanitizer more reliable
 [profile.dev]
 opt-level = 1
+
+# Define `tokio_unstable` config for linter
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(tokio_unstable)'] }

examples/tokio_console.rs

@@ -0,0 +1,61 @@
+//! This example demonstrates how to use the tokio-console application for tracing tokio tasks's
+//! runtime behaviour. Subsystems will appear under their registration names.
+//!
+//! Run this example with:
+//!
+//! ```
+//! RUSTFLAGS="--cfg tokio_unstable" cargo run --features "tokio-unstable" --example tokio_console
+//! ```
+//!
+//! Then, open the `tokio-console` application (see https://crates.io/crates/tokio-console) to
+//! follow the subsystem tasks live.
+xxx
+use miette::Result;
+use tokio::time::{sleep, Duration};
+use tokio_graceful_shutdown::{FutureExt, SubsystemBuilder, SubsystemHandle, Toplevel};
+use tracing_subscriber::prelude::*;
+
+async fn subsys(subsys: SubsystemHandle) -> Result<()> {
+    tracing::info!("Parent started.");
+
+    let mut iteration = 0;
+    while !subsys.is_shutdown_requested() {
+        subsys.start(SubsystemBuilder::new(format!("child{iteration}"), child));
+        iteration += 1;
+
+        sleep(Duration::from_millis(1000))
+            .cancel_on_shutdown(&subsys)
+            .await
+            .ok();
+    }
+
+    tracing::info!("Parent stopped.");
+    Ok(())
+}
+
+async fn child(subsys: SubsystemHandle) -> Result<()> {
+    sleep(Duration::from_millis(3000))
+        .cancel_on_shutdown(&subsys)
+        .await
+        .ok();
+    Ok(())
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let console_layer = console_subscriber::spawn();
+    // Init logging
+    tracing_subscriber::registry()
+        .with(console_layer)
+        .with(tracing_subscriber::fmt::layer().compact())
+        .init();
+
+    // Setup and execute subsystem tree
+    Toplevel::new(|s| async move {
+        s.start(SubsystemBuilder::new("parent", subsys));
+    })
+    .catch_signals()
+    .handle_shutdown_requests(Duration::from_millis(1000))
+    .await
+    .map_err(Into::into)
+}

src/lib.rs

@@ -124,3 +124,6 @@ pub use subsystem::SubsystemBuilder;
 pub use subsystem::SubsystemFinishedFuture;
 pub use subsystem::SubsystemHandle;
 pub use toplevel::Toplevel;
+
+mod tokio_unstable;
+use tokio_unstable::spawn;

src/runner.rs

@@ -33,7 +33,7 @@ impl SubsystemRunner {
         Err: Into<ErrType>,
     {
         let future = async { run_subsystem(name, subsystem, subsystem_handle, guard).await };
-        let aborthandle = tokio::spawn(future).abort_handle();
+        let aborthandle = crate::spawn(future, "subsystem_runner").abort_handle();
         SubsystemRunner { aborthandle }
     }
 }
@@ -57,7 +57,7 @@ async fn run_subsystem<Fut, Subsys, ErrType: ErrTypeTraits, Err>(
     let mut redirected_subsystem_handle = subsystem_handle.delayed_clone();
 
     let future = async { subsystem(subsystem_handle).await.map_err(|e| e.into()) };
-    let join_handle = tokio::spawn(future);
+    let join_handle = crate::spawn(future, &name);
 
     // Abort on drop
     guard.on_cancel({

src/tokio_unstable.rs

@@ -0,0 +1,21 @@
+use std::future::Future;
+use tokio::task::JoinHandle;
+
+#[cfg(not(all(tokio_unstable, feature = "tokio-unstable")))]
+pub(crate) fn spawn<F: Future + Send + 'static>(f: F, _name: &str) -> JoinHandle<F::Output>
+where
+    <F as Future>::Output: Send + 'static,
+{
+    tokio::spawn(f)
+}
+
+#[cfg(all(tokio_unstable, feature = "tokio-unstable"))]
+pub(crate) fn spawn<F: Future + Send + 'static>(f: F, name: &str) -> JoinHandle<F::Output>
+where
+    <F as Future>::Output: Send + 'static,
+{
+    tokio::task::Builder::new()
+        .name(name)
+        .spawn(f)
+        .expect("a task should be spawned")
+}

src/toplevel.rs

@@ -121,10 +121,13 @@ impl<ErrType: ErrTypeTraits> Toplevel<ErrType> {
     pub fn catch_signals(self) -> Self {
         let shutdown_token = self.root_handle.get_cancellation_token().clone();
 
-        tokio::spawn(async move {
-            wait_for_signal().await;
-            shutdown_token.cancel();
-        });
+        crate::spawn(
+            async move {
+                wait_for_signal().await;
+                shutdown_token.cancel();
+            },
+            "catch_signals",
+        );
 
         self
     }