1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
<!-- Do not edit README.md manually. Instead, edit the module comment of `backtrace/lib.rs`. -->
# async-backtrace
Efficient, logical 'stack' traces of async functions.
## Usage
To use, annotate your async functions with `#[async_backtrace::framed]`,
like so:
```rust
#[tokio::main]
async fn main() {
tokio::select! {
_ = tokio::spawn(async_backtrace::frame!(pending())) => {}
_ = foo() => {}
};
}
#[async_backtrace::framed]
async fn pending() {
std::future::pending::<()>().await
}
#[async_backtrace::framed]
async fn foo() {
bar().await;
}
#[async_backtrace::framed]
async fn bar() {
futures::join!(fiz(), buz());
}
#[async_backtrace::framed]
async fn fiz() {
tokio::task::yield_now().await;
}
#[async_backtrace::framed]
async fn buz() {
println!("{}", baz().await);
}
#[async_backtrace::framed]
async fn baz() -> String {
async_backtrace::taskdump_tree(true)
}
```
This example program will print out something along the lines of:
```
╼ taskdump::foo::{{closure}} at backtrace/examples/taskdump.rs:20:1
└╼ taskdump::bar::{{closure}} at backtrace/examples/taskdump.rs:25:1
├╼ taskdump::buz::{{closure}} at backtrace/examples/taskdump.rs:35:1
│ └╼ taskdump::baz::{{closure}} at backtrace/examples/taskdump.rs:40:1
└╼ taskdump::fiz::{{closure}} at backtrace/examples/taskdump.rs:30:1
╼ taskdump::pending::{{closure}} at backtrace/examples/taskdump.rs:15:1
```
## Minimizing Overhead
To minimize overhead, ensure that futures you spawn with your async runtime
are marked with `#[framed]`.
In other words, avoid doing this:
```rust
tokio::spawn(async {
foo().await;
bar().await;
}).await;
#[async_backtrace::framed] async fn foo() {}
#[async_backtrace::framed] async fn bar() {}
```
...and prefer doing this:
```rust
tokio::spawn(async_backtrace::location!().frame(async {
foo().await;
bar().await;
})).await;
#[async_backtrace::framed] async fn foo() {}
#[async_backtrace::framed] async fn bar() {}
```
## Estimating Overhead
To estimate the overhead of adopting `#[framed]` in your application, refer
to the benchmarks and interpretive guidance in
`./backtrace/benches/frame_overhead.rs`. You can run these benchmarks with
`cargo bench`.
## License
This project is licensed under the [MIT license].
[MIT license]: https://github.com/tokio-rs/async-backtrace/blob/main/LICENSE
### Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in async-backtrace by you, shall be licensed as MIT, without any
additional terms or conditions.
|
