more documentation

tokio-rs · carllerche · Jan 27, 2025 · Nov 13, 2024 · Jan 9, 2025 · Jan 10, 2025
commit 03b481af5ddc55fa9e7228bcf197422a49b018ab
diff --git a/tokio/src/runtime/dump.rs b/tokio/src/runtime/dump.rs
@@ -219,11 +219,19 @@ impl Trace {
 
     //github.com/ Runs the function `f` in tracing mode, and returns its result along with the resulting [`Trace`].
     //github.com/
-    //github.com/ The passed-in function is normally a poll function. Due to the way tracing is implemented,
-    //github.com/ Tokio leaf futures might, instead of doing their actual work, do the equivalent of a
-    //github.com/ `yield_now` (returning a `Poll::Pending` and scheduling the current context for execution),
-    //github.com/ which means forward progress is only guaranteed if you eventually call your future outside of
-    //github.com/ `capture`.
+    //github.com/ This is normally called with `f` being the poll function of a future, and will give you a backtrace
+    //github.com/ that tells you what that one future is doing.
+    //github.com/
+    //github.com/ Use [`Handle::dump`] instead if you want to know what *all the tasks* in your program are doing.
+    //github.com/ Also see [`Handle::dump`] for more documentation about dumps, but unlike [`Handle::dump`], this function
+    //github.com/ should not be much slower than calling `f` directly.
+    //github.com/
+    //github.com/ Due to the way tracing is implemented, Tokio leaf futures will usually, instead of doing their
+    //github.com/ actual work, do the equivalent of a `yield_now` (returning a `Poll::Pending` and scheduling the
+    //github.com/ current context for execution), which means forward progress will probably not happen unless
+    //github.com/ you eventually call your future outside of `capture`.
+    //github.com/
+    //github.com/ [`Handle::dump`]: crate::runtime::Handle::dump
     //github.com/
     //github.com/ Example usage:
     //github.com/ ```
@@ -235,12 +243,13 @@ impl Trace {
     //github.com/ // some future
     //github.com/ let mut test_future = std::pin::pin!(async move { tokio::task::yield_now().await; 0 });
     //github.com/
-    //github.com/ // trace it once
+    //github.com/ // trace it once, see what it's doing
     //github.com/ let (trace, res) = Trace::root(std::future::poll_fn(|cx| {
     //github.com/     let (res, trace) = Trace::capture(|| test_future.as_mut().poll(cx));
     //github.com/     Poll::Ready((trace, res))
     //github.com/ })).await;
     //github.com/
+    //github.com/ // await it to let it finish, outside of a `capture`
     //github.com/ let output = match res {
     //github.com/    Poll::Ready(output) => output,
     //github.com/    Poll::Pending => test_future.await,
@@ -254,11 +263,6 @@ impl Trace {
     //github.com/
     //github.com/ Nested calls to `capture` might return partial traces, but will not do any other undesirable behavior (for
     //github.com/ example, they will not panic).
-    //github.com/
-    //github.com/ ### Unstable Implementation Details
-    //github.com/
-    //github.com/ When run in tracing mode, Tokio leaf futures will return `Poll::Pending` and emit a stack trace
-    //github.com/ that will be captured in the returning [`Trace`].
     pub fn capture<F, R>(f: F) -> (R, Trace)
     where
         F: FnOnce() -> R,

diff --git a/tokio/src/runtime/handle.rs b/tokio/src/runtime/handle.rs
@@ -447,6 +447,9 @@ cfg_taskdump! {
     impl Handle {
         //github.com/ Captures a snapshot of the runtime's state.
         //github.com/
+        //github.com/ If you only want to capture a snapshot of a single future's state, you can use
+        //github.com/ [`Trace::capture`][crate::runtime::dump::Trace].
+        //github.com/
         //github.com/ This functionality is experimental, and comes with a number of
         //github.com/ requirements and limitations.
         //github.com/