tokio-rs · ADD-SP · Oct 10, 2025 · Sep 30, 2025 · Oct 1, 2025 · Oct 1, 2025
diff --git a/.cirrus.yml b/.cirrus.yml
@@ -29,9 +29,12 @@ task:
     # Free the disk space before the next build,
     # otherwise cirrus-ci complains about "No space left on device".
     - cargo clean
-    # Enable all unstable features, including io_uring, because it supports
-    # x86_64 FreeBSD.
-    - RUSTFLAGS="$RUSTFLAGS --cfg tokio_unstable" RUSTDOCFLAGS="$RUSTDOCFLAGS --cfg tokio_unstable" cargo test --all --all-features
+    # Enable all unstable features except `taskdump`, which is Linux-only.
+    - |
+      RUSTFLAGS="$RUSTFLAGS --cfg tokio_unstable" \
+      RUSTDOCFLAGS="$RUSTDOCFLAGS --cfg tokio_unstable" \
+        cargo test \
+          --features $TOKIO_STABLE_FEATURES,io-uring,tracing
 
 task:
   name: FreeBSD docs
@@ -48,7 +51,9 @@ task:
       rustc --version
   test_script:
     - . $HOME/.cargo/env
-    - cargo doc --lib --no-deps --all-features --document-private-items
+    # We use `--features $TOKIO_STABLE_FEATURES,io-uring,tracing` instead of
+    # `--all-features` to exclude `taskdump`, which is Linux-only.
+    - cargo doc --lib --no-deps --features $TOKIO_STABLE_FEATURES,io-uring,tracing --document-private-items
 
 task:
   name: FreeBSD 32-bit

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
diff --git a/Cargo.toml b/Cargo.toml
@@ -27,7 +27,6 @@ unexpected_cfgs = { level = "warn", check-cfg = [
   'cfg(tokio_internal_mt_counters)',
   'cfg(tokio_no_parking_lot)',
   'cfg(tokio_no_tuning_tests)',
-  'cfg(tokio_taskdump)',
   'cfg(tokio_unstable)',
   'cfg(target_os, values("cygwin"))',
 ] }
diff --git a/examples/Cargo.toml b/examples/Cargo.toml
@@ -24,6 +24,9 @@ httparse = "1.0"
 httpdate = "1.0"
 once_cell = "1.5.2"
 
+[target.'cfg(all(tokio_unstable, target_os = "linux"))'.dev-dependencies]
+tokio = { version = "1.0.0", path = "../tokio", features = ["full", "tracing", "taskdump"] }
+
 [target.'cfg(windows)'.dev-dependencies.windows-sys]
 version = "0.59"
 

diff --git a/examples/dump.rs b/examples/dump.rs
@@ -4,7 +4,6 @@
 
 #[cfg(all(
     tokio_unstable,
-    tokio_taskdump,
     target_os = "linux",
     any(target_arch = "aarch64", target_arch = "x86", target_arch = "x86_64")
 ))]
@@ -82,7 +81,6 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
 #[cfg(not(all(
     tokio_unstable,
-    tokio_taskdump,
     target_os = "linux",
     any(target_arch = "aarch64", target_arch = "x86", target_arch = "x86_64")
 )))]

diff --git a/netlify.toml b/netlify.toml
@@ -17,9 +17,11 @@
   RUSTDOCFLAGS="""
     --cfg docsrs \
     --cfg tokio_unstable \
-    --cfg tokio_taskdump \
     """
-  RUSTFLAGS="--cfg tokio_unstable --cfg tokio_taskdump --cfg docsrs"
+  RUSTFLAGS="""
+    --cfg docsrs \
+    --cfg tokio_unstable
+    """
 
 [[redirects]]
   from = "/"

diff --git a/tokio/Cargo.toml b/tokio/Cargo.toml
@@ -86,6 +86,8 @@ test-util = ["rt", "sync", "time"]
 time = []
 # Unstable feature. Requires `--cfg tokio_unstable` to enable.
 io-uring = ["dep:io-uring", "libc", "mio/os-poll", "mio/os-ext", "dep:slab"]
+# Unstable feature. Requires `--cfg tokio_unstable` to enable.
+taskdump = ["dep:backtrace"]
 
 [dependencies]
 tokio-macros = { version = "~2.5.0", path = "../tokio-macros", optional = true }
@@ -112,11 +114,7 @@ io-uring = { version = "0.7.6", default-features = false, optional = true }
 libc = { version = "0.2.168", optional = true }
 mio = { version = "1.0.1", default-features = false, features = ["os-poll", "os-ext"], optional = true }
 slab = { version = "0.4.9", optional = true }
-
-# Currently unstable. The API exposed by these features may be broken at any time.
-# Requires `--cfg tokio_unstable` to enable.
-[target.'cfg(tokio_taskdump)'.dependencies]
-backtrace = { version = "0.3.58" }
+backtrace = { version = "0.3.58", optional = true }
 
 [target.'cfg(unix)'.dependencies]
 libc = { version = "0.2.168", optional = true }
@@ -169,10 +167,10 @@ tracing-mock = "= 0.1.0-beta.1"
 [package.metadata.docs.rs]
 all-features = true
 # enable unstable features in the documentation
-rustdoc-args = ["--cfg", "docsrs", "--cfg", "tokio_unstable", "--cfg", "tokio_taskdump"]
-# it's necessary to _also_ pass `--cfg tokio_unstable` and `--cfg tokio_taskdump`
+rustdoc-args = ["--cfg", "docsrs", "--cfg", "tokio_unstable"]
+# it's necessary to _also_ pass `--cfg tokio_unstable`
 # to rustc, or else dependencies will not be enabled, and the docs build will fail.
-rustc-args = ["--cfg", "tokio_unstable", "--cfg", "tokio_taskdump"]
+rustc-args = ["--cfg", "tokio_unstable"]
 
 [package.metadata.playground]
 features = ["full", "test-util"]

diff --git a/tokio/src/lib.rs b/tokio/src/lib.rs
@@ -483,19 +483,19 @@ compile_error!("Only features sync,macros,io-util,rt,time are supported on wasm.
 #[cfg(all(not(tokio_unstable), feature = "io-uring"))]
 compile_error!("The `io-uring` feature requires `--cfg tokio_unstable`.");
 
-#[cfg(all(not(tokio_unstable), tokio_taskdump))]
-compile_error!("The `tokio_taskdump` feature requires `--cfg tokio_unstable`.");
+#[cfg(all(not(tokio_unstable), feature = "taskdump"))]
+compile_error!("The `taskdump` feature requires `--cfg tokio_unstable`.");
 
 #[cfg(all(
-    tokio_taskdump,
+    feature = "taskdump",
     not(doc),
     not(all(
         target_os = "linux",
         any(target_arch = "aarch64", target_arch = "x86", target_arch = "x86_64")
     ))
 ))]
 compile_error!(
-    "The `tokio_taskdump` feature is only currently supported on \
+    "The `taskdump` feature is only currently supported on \
 linux, on `aarch64`, `x86` and `x86_64`."
 );
 

diff --git a/tokio/src/macros/cfg.rs b/tokio/src/macros/cfg.rs
@@ -499,7 +499,7 @@ macro_rules! cfg_taskdump {
         $(
             #[cfg(all(
                 tokio_unstable,
-                tokio_taskdump,
+                feature = "taskdump",
                 feature = "rt",
                 target_os = "linux",
                 any(
@@ -518,7 +518,7 @@ macro_rules! cfg_not_taskdump {
         $(
             #[cfg(not(all(
                 tokio_unstable,
-                tokio_taskdump,
+                feature = "taskdump",
                 feature = "rt",
                 target_os = "linux",
                 any(

diff --git a/tokio/src/runtime/context.rs b/tokio/src/runtime/context.rs
@@ -66,7 +66,7 @@ struct Context {
 
     #[cfg(all(
         tokio_unstable,
-        tokio_taskdump,
+        feature = "taskdump",
         feature = "rt",
         target_os = "linux",
         any(target_arch = "aarch64", target_arch = "x86", target_arch = "x86_64")
@@ -107,7 +107,7 @@ tokio_thread_local! {
 
             #[cfg(all(
                 tokio_unstable,
-                tokio_taskdump,
+                feature = "taskdump",
                 feature = "rt",
                 target_os = "linux",
                 any(

diff --git a/tokio/src/runtime/handle.rs b/tokio/src/runtime/handle.rs
@@ -329,7 +329,7 @@ impl Handle {
     fn block_on_inner<F: Future>(&self, future: F, _meta: SpawnMeta<'_>) -> F::Output {
         #[cfg(all(
             tokio_unstable,
-            tokio_taskdump,
+            feature = "taskdump",
             feature = "rt",
             target_os = "linux",
             any(target_arch = "aarch64", target_arch = "x86", target_arch = "x86_64")
@@ -356,7 +356,7 @@ impl Handle {
         let id = crate::runtime::task::Id::next();
         #[cfg(all(
             tokio_unstable,
-            tokio_taskdump,
+            feature = "taskdump",
             feature = "rt",
             target_os = "linux",
             any(target_arch = "aarch64", target_arch = "x86", target_arch = "x86_64")
@@ -381,7 +381,7 @@ impl Handle {
         let id = crate::runtime::task::Id::next();
         #[cfg(all(
             tokio_unstable,
-            tokio_taskdump,
+            feature = "taskdump",
             feature = "rt",
             target_os = "linux",
             any(target_arch = "aarch64", target_arch = "x86", target_arch = "x86_64")
@@ -536,19 +536,19 @@ cfg_taskdump! {
         /// ## Unstable Features
         ///
         /// This functionality is **unstable**, and requires both the
-        /// `tokio_unstable` and `tokio_taskdump` `cfg` flags to be set.
+        /// `--cfg tokio_unstable` and cargo feature `taskdump` to be set.
         ///
         /// You can do this by setting the `RUSTFLAGS` environment variable
         /// before invoking `cargo`; e.g.:
         /// ```bash
-        /// RUSTFLAGS="--cfg tokio_unstable --cfg tokio_taskdump" cargo run --example dump
+        /// RUSTFLAGS="--cfg tokio_unstable cargo run --example dump
         /// ```
         ///
         /// Or by [configuring][cargo-config] `rustflags` in
         /// `.cargo/config.toml`:
         /// ```text
         /// [build]
-        /// rustflags = ["--cfg", "tokio_unstable", "--cfg", "tokio_taskdump"]
+        /// rustflags = ["--cfg", "tokio_unstable"]
         /// ```
         ///
         /// [cargo-config]:
@@ -568,7 +568,7 @@ cfg_taskdump! {
         ///
         /// ## Performance
         ///
-        /// Although enabling the `tokio_taskdump` feature imposes virtually no
+        /// Although enabling the `taskdump` feature imposes virtually no
         /// additional runtime overhead, actually calling `Handle::dump` is
         /// expensive. The runtime must synchronize and pause its workers, then
         /// re-poll every task in a special tracing mode. Avoid requesting dumps

diff --git a/tokio/src/runtime/local_runtime/runtime.rs b/tokio/src/runtime/local_runtime/runtime.rs
@@ -232,7 +232,7 @@ impl LocalRuntime {
     fn block_on_inner<F: Future>(&self, future: F, _meta: SpawnMeta<'_>) -> F::Output {
         #[cfg(all(
             tokio_unstable,
-            tokio_taskdump,
+            feature = "taskdump",
             feature = "rt",
             target_os = "linux",
             any(target_arch = "aarch64", target_arch = "x86", target_arch = "x86_64")

diff --git a/tokio/src/runtime/runtime.rs b/tokio/src/runtime/runtime.rs
@@ -347,7 +347,7 @@ impl Runtime {
     fn block_on_inner<F: Future>(&self, future: F, _meta: SpawnMeta<'_>) -> F::Output {
         #[cfg(all(
             tokio_unstable,
-            tokio_taskdump,
+            feature = "taskdump",
             feature = "rt",
             target_os = "linux",
             any(target_arch = "aarch64", target_arch = "x86", target_arch = "x86_64")

diff --git a/tokio/src/runtime/scheduler/current_thread/mod.rs b/tokio/src/runtime/scheduler/current_thread/mod.rs
@@ -350,7 +350,7 @@ impl Core {
     }
 }
 
-#[cfg(tokio_taskdump)]
+#[cfg(feature = "taskdump")]
 fn wake_deferred_tasks_and_free(context: &Context) {
     let wakers = context.defer.take_deferred();
     for waker in wakers {
@@ -509,7 +509,7 @@ impl Handle {
     /// Capture a snapshot of this runtime's state.
     #[cfg(all(
         tokio_unstable,
-        tokio_taskdump,
+        feature = "taskdump",
         target_os = "linux",
         any(target_arch = "aarch64", target_arch = "x86", target_arch = "x86_64")
     ))]

diff --git a/tokio/src/runtime/scheduler/defer.rs b/tokio/src/runtime/scheduler/defer.rs
@@ -35,7 +35,7 @@ impl Defer {
         }
     }
 
-    #[cfg(tokio_taskdump)]
+    #[cfg(feature = "taskdump")]
     pub(crate) fn take_deferred(&self) -> Vec<Waker> {
         let mut deferred = self.deferred.borrow_mut();
         std::mem::take(&mut *deferred)

diff --git a/tokio/src/runtime/scheduler/inject.rs b/tokio/src/runtime/scheduler/inject.rs
@@ -36,7 +36,7 @@ impl<T: 'static> Inject<T> {
     }
 
     // Kind of annoying to have to include the cfg here
-    #[cfg(tokio_taskdump)]
+    #[cfg(feature = "taskdump")]
     pub(crate) fn is_closed(&self) -> bool {
         let synced = self.synced.lock();
         self.shared.is_closed(&synced)

diff --git a/tokio/src/runtime/scheduler/inject/shared.rs b/tokio/src/runtime/scheduler/inject/shared.rs
@@ -38,7 +38,7 @@ impl<T: 'static> Shared<T> {
     }
 
     // Kind of annoying to have to include the cfg here
-    #[cfg(any(tokio_taskdump, feature = "rt-multi-thread"))]
+    #[cfg(any(feature = "taskdump", feature = "rt-multi-thread"))]
     pub(crate) fn is_closed(&self, synced: &Synced) -> bool {
         synced.is_closed
     }

diff --git a/tokio/src/runtime/task/mod.rs b/tokio/src/runtime/task/mod.rs
@@ -404,7 +404,7 @@ impl<S: 'static> Task<S> {
 
     #[cfg(all(
         tokio_unstable,
-        tokio_taskdump,
+        feature = "taskdump",
         feature = "rt",
         target_os = "linux",
         any(target_arch = "aarch64", target_arch = "x86", target_arch = "x86_64")

diff --git a/tokio/src/runtime/task/state.rs b/tokio/src/runtime/task/state.rs
@@ -284,7 +284,7 @@ impl State {
     /// otherwise `false.`
     #[cfg(all(
         tokio_unstable,
-        tokio_taskdump,
+        feature = "taskdump",
         feature = "rt",
         target_os = "linux",
         any(target_arch = "aarch64", target_arch = "x86", target_arch = "x86_64")

diff --git a/tokio/src/sync/notify.rs b/tokio/src/sync/notify.rs
@@ -1218,7 +1218,7 @@ impl NotifiedProject<'_> {
                     return Poll::Pending;
                 }
                 State::Waiting => {
-                    #[cfg(tokio_taskdump)]
+                    #[cfg(feature = "taskdump")]
                     if let Some(waker) = waker {
                         let mut ctx = Context::from_waker(waker);
                         std::task::ready!(crate::trace::trace_leaf(&mut ctx));
@@ -1312,7 +1312,7 @@ impl NotifiedProject<'_> {
                     drop(old_waker);
                 }
                 State::Done => {
-                    #[cfg(tokio_taskdump)]
+                    #[cfg(feature = "taskdump")]
                     if let Some(waker) = waker {
                         let mut ctx = Context::from_waker(waker);
                         std::task::ready!(crate::trace::trace_leaf(&mut ctx));

diff --git a/tokio/src/task/local.rs b/tokio/src/task/local.rs
@@ -411,7 +411,7 @@ cfg_rt! {
 
                 #[cfg(all(
                     tokio_unstable,
-                    tokio_taskdump,
+                    feature = "taskdump",
                     feature = "rt",
                     target_os = "linux",
                     any(

diff --git a/tokio/src/task/spawn.rs b/tokio/src/task/spawn.rs
@@ -189,7 +189,7 @@ cfg_rt! {
 
         #[cfg(all(
             tokio_unstable,
-            tokio_taskdump,
+            feature = "taskdump",
             feature = "rt",
             target_os = "linux",
             any(

diff --git a/tokio/tests/dump.rs b/tokio/tests/dump.rs
@@ -1,6 +1,6 @@
 #![cfg(all(
     tokio_unstable,
-    tokio_taskdump,
+    feature = "taskdump",
     target_os = "linux",
     any(target_arch = "aarch64", target_arch = "x86", target_arch = "x86_64")
 ))]

diff --git a/tokio/tests/task_trace_self.rs b/tokio/tests/task_trace_self.rs
@@ -1,7 +1,7 @@
 #![allow(unknown_lints, unexpected_cfgs)]
 #![cfg(all(
     tokio_unstable,
-    tokio_taskdump,
+    feature = "taskdump",
     target_os = "linux",
     any(target_arch = "aarch64", target_arch = "x86", target_arch = "x86_64")
 ))]