Skip to content

Commit

Permalink
tracing: clarify span enter docs warning (#2010)
Browse files Browse the repository at this point in the history
## Motivation

It took me several reads to understand why holding a guard over an await
was bad because my brain is naturally synchronous and could only think
about `my_async_function` and `some_other_async_function`

## Solution

Rather than just iterating "this is bad" use that opportunity to
introduce why. Remind the user that this is being executed concurrently
to other tasks

Co-authored-by: Eliza Weisman <eliza@buoyant.io>
  • Loading branch information
arifd and hawkw committed Mar 29, 2022
1 parent 092c0fd commit d589191
Showing 1 changed file with 6 additions and 2 deletions.
8 changes: 6 additions & 2 deletions tracing/src/span.rs
Original file line number Diff line number Diff line change
Expand Up @@ -605,9 +605,13 @@ impl Span {
/// async fn my_async_function() {
/// let span = info_span!("my_async_function");
///
/// // THIS WILL RESULT IN INCORRECT TRACES
/// // WARNING: This span will remain entered until this
/// // guard is dropped...
/// let _enter = span.enter();
/// some_other_async_function().await;
/// // ...but the `await` keyword may yield, causing the
/// // runtime to switch to another task, while remaining in
/// // this span!
/// some_other_async_function().await
///
/// // ...
/// }
Expand Down

0 comments on commit d589191

Please sign in to comment.