`timeout-tracing` allows executing an async function with a timeout (much like `tokio::time::timeout`).
When the timeout elapses it returns the exact location where the async code was awaiting at that specific moment.
# Basic usage
The basic usage looks as follows:
```rust,no_run
use std::time::Duration;
use timeout_tracing::{CaptureSpanTrace, timeout};
use tokio::time::sleep;
use tracing::instrument;
use tracing_error::ErrorLayer;
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};
#[tokio::main]
async fn main() {
// (1)
tracing_subscriber::registry()
.with(ErrorLayer::default())
.init();
// (2)
match timeout(Duration::from_secs(1), CaptureSpanTrace, computation(25)).await {
Ok(()) => println!("Completed"),
Err(elapsed) => println!("{elapsed}"), // (4)
}
}
// (5)
#[instrument]
async fn computation(n: i32) {
for i in 0..n {
step(i).await;
}
}
#[instrument]
async fn step(i: i32) {
sleep(Duration::from_millis(100)).await;
}
```
This prints out:
```skip
timeout elapsed at:
trace 0:
0: basic::step
with i=9
at examples/basic.rs:31
1: basic::computation
with n=25
at examples/basic.rs:24
```
1. `tracing-error` must be initialized, as it is used (by default) to gather span traces.
2. `timeout_tracing::timeout` executes the future with a timeout
3. `CaptureSpanTrace` is the object that captures the stack. The default implementation captures span trace (via `tracing-error`). It is also possible to capture a stack trace as well using `CaptureSpanAndStackTrace` (via Rust standard library; the `RUST_BACKTRACE=1` environment variable must be set for stack trace capture to work)
4. If the future does not complete within the given time limit, an error is returned. It contains a set of traces for each active leaf await point within the future.
5. The executed functions should be instrumented with `tokio-tracing` spans (for example, by using the `#[tokio-tracing::instrument]` macro) for span trace to work.