only depend on tokio if spawn capability is desired (#25)

Author: BugenZhao

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "await-tree"
-version = "0.3.0-alpha.2"
+version = "0.3.0-alpha.3"
 edition = "2021"
 description = "Generate accurate and informative tree dumps of asynchronous tasks."
 repository = "https://github.com/risingwavelabs/await-tree"
@@ -11,6 +11,7 @@ license = "Apache-2.0"
 
 [features]
 serde = ["dep:serde", "flexstr/serde"]
+tokio = ["dep:tokio"]
 
 [dependencies]
 coarsetime = "0.1"
@@ -22,15 +23,16 @@ itertools = "0.12"
 parking_lot = "0.12"
 pin-project = "1"
 serde = { version = "1", features = ["derive"], optional = true }
-tokio = { version = "1", features = ["rt"] }
+task-local = "0.1"
+tokio = { version = "1", features = ["rt"], optional = true }
 tracing = "0.1"
 weak-table = "0.3.2"
 
 [dev-dependencies]
 criterion = { version = "0.5", features = ["async", "async_tokio"] }
 futures = { version = "0.3", default-features = false, features = ["alloc"] }
 serde_json = "1"
-tokio = { version = "1", features = ["rt", "rt-multi-thread", "time", "macros"] }
+tokio = { version = "1", features = ["full"] }
 
 [[bench]]
 name = "basic"
@@ -49,3 +51,11 @@ rpath = false
 [[example]]
 name = "serde"
 required-features = ["serde"]
+
+[[example]]
+name = "spawn"
+required-features = ["tokio"]
+
+[[example]]
+name = "global"
+required-features = ["tokio"]

README.md

@@ -33,6 +33,7 @@ async fn foo() {
 // Init the global registry to start tracing the tasks.
 await_tree::init_global_registry(Default::default());
 // Spawn a task with root span "foo" and key "foo".
+// Note: The `spawn` function requires the `tokio` feature to be enabled.
 await_tree::spawn("foo", "foo", foo());
 // Let the tasks run for a while.
 sleep(Duration::from_secs(1)).await;
@@ -64,7 +65,20 @@ println!("{tree}");
   println!("{json}");
   ```
 
-### Compared to `async-backtrace`
+- `tokio`: Enables integration with the Tokio runtime, providing task spawning capabilities through `spawn` and `spawn_anonymous` functions. This feature is required for the examples that demonstrate spawning tasks.
+
+  ```rust
+  // Enable the tokio feature in Cargo.toml
+  // await-tree = { version = "<version>", features = ["tokio"] }
+
+  // Then you can spawn tasks with await-tree instrumentation
+  await_tree::spawn("task-key", "root_span", async {
+      // Your async code here
+      work().instrument_await("work_span").await;
+  });
+  ```
+
+## Compared to `async-backtrace`
 
 [`tokio-rs/async-backtrace`](https://github.com/tokio-rs/async-backtrace) is a similar crate that also provides the ability to dump the execution tree of async tasks. Here are some differences between `await-tree` and `async-backtrace`:
 

examples/global.rs

@@ -13,6 +13,11 @@
 // limitations under the License.
 
 //! This example shows the usage of the global registry.
+//!
+//! Note: This example requires the `tokio` feature to be enabled.
+//! Run with: `cargo run --example global --features tokio`
+
+#![cfg(feature = "tokio")]
 
 use std::time::Duration;
 

examples/spawn.rs

@@ -14,6 +14,11 @@
 
 //! This example shows how to spawn tasks with `await_tree::spawn` that are automatically registered
 //! to the current registry of the scope.
+//!
+//! Note: This example requires the `tokio` feature to be enabled.
+//! Run with: `cargo run --example spawn --features tokio`
+
+#![cfg(feature = "tokio")]
 
 use std::time::Duration;
 

src/lib.rs

@@ -78,6 +78,7 @@ mod obj_utils;
 mod registry;
 mod root;
 mod span;
+#[cfg(feature = "tokio")]
 mod spawn;
 
 pub use context::{current_tree, Tree};
@@ -86,6 +87,7 @@ pub use global::init_global_registry;
 pub use registry::{AnyKey, Config, ConfigBuilder, ConfigBuilderError, Key, Registry};
 pub use root::TreeRoot;
 pub use span::{Span, SpanExt};
+#[cfg(feature = "tokio")]
 pub use spawn::{spawn, spawn_anonymous};
 
 #[doc(hidden)]

src/root.rs

@@ -26,7 +26,7 @@ pub struct TreeRoot {
     pub(crate) registry: WeakRegistry,
 }
 
-tokio::task_local! {
+task_local::task_local! {
     static ROOT: TreeRoot
 }
 

src/spawn.rs

@@ -15,8 +15,6 @@
 // TODO: should we consider exposing `current_registry`
 // so that users can not only spawn tasks but also get and collect trees?
 
-// TODO: should we support "global registry" for users to quick start?
-
 use std::future::Future;
 
 use tokio::task::JoinHandle;

src/tests/spawn.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+#![cfg(feature = "tokio")]
+
 use std::time::Duration;
 
 use futures::future::pending;