Semantics of control flow operators (return, continue, ?) in async blocks is severely underdocumented

[matklad]

As a novice Rust programmer, I was quite surprised that the following works:

#[tokio::main]
async fn main() {
    let f = async { return 92 };
    assert_eq!(f.await, 92);
}

I don't remeber reading that in any kind of docs, and looking at the

• async book https://rust-lang.github.io/async-book/01_getting_started/04_async_await_primer.html
• async keyword https://doc.rust-lang.org/stable/std/keyword.async.html
• return keyword https://doc.rust-lang.org/stable/std/keyword.return.html

didn't show up any example of the syntax.

This is documented in the reference (rust-lang/reference#1262), but without an example.

[Lynnesbian]

I'd be interested in claiming this as my first issue.

This behaviour is documented in the Async Rust Book as of this commit.

---

The current docs for the async keyword are fairly minimal, so I'm not sure how much they should be expanded, but so far I've come up with something like this, adding to the existing comment:

Use async in front of fn, closure, or a block to turn the marked code into a Future.
As such the code will not be run immediately, but will only be evaluated when the returned
future is .awaited.

return and ? statements within async blocks do not return from the parent function; rather, they
cause the Future returned by the block to return with that value.

For example, the following Rust function will return 5, assigning the ! value to x:

#[expect(unused_variables)]
fn example() -> i32 {
    let x = {
      return 5;
    };
}

In contrast, the following asynchronous function assigns a Future<Output = i32> to x, and only returns 5 when x is .awaited:

async fn example() -> i32 {
    let x = async {
        return 5;
    };
    
    x.await
}

Code using ? behaves similarly - it causes the async block to return a Result without affecting the parent function.
Note that you cannot use break or continue from within an async block to affect the control flow of a loop in the parent function.

---

@rustbot claim