Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Stop storing a special inner body for the coroutine by-move body for async closures #128506

Merged
merged 2 commits into from
Aug 28, 2024

Conversation

compiler-errors
Copy link
Member

@compiler-errors compiler-errors commented Aug 1, 2024

...and instead, just synthesize an item which is treated mostly normally by the MIR pipeline.

This PR does a few things:

  • We synthesize a new DefId for the by-move body of a closure, which has its mir_built fed with the output of the ByMoveBody MIR transformation, and some other relevant queries.
  • This has the DefKind::ByMoveBody DefKind::SyntheticCoroutineBody, which we use to distinguish it from "real" bodies (that come from HIR) which need to be borrowck'd. Introduce TyCtxt::is_synthetic_mir to skip over mir_borrowck which is called by mir_promoted; borrowck isn't really possible to make work ATM since it heavily relies being called on a body generated from HIR, and is redundant by the construction of the by-move-body.
  • Remove the special PassManager hacks for handling the inner by_move_body stored within the coroutine's mir body. Instead, this body is fed like a regular MIR body, so it's goes through all of the tcx.*_mir stages normally (build -> promoted -> ...etc... -> optimized) ✨.
  • Remove the InstanceKind::ByMoveBody shim, since now we have a "regular" def id, we can just use InstanceKind::Item. This also allows us to remove the corresponding hacks from codegen, such as in fn_sig_for_fn_abi ✨.

Notable remarks:

  • I know it's kind of weird to be using DefKind::Closure here, since it's not a distinct closure but just a new MIR body. I don't believe it really matters, but I could also use a different DefKind... maybe one that we could use for synthetic MIR bodies in general? edit: We're doing this now.

@rustbot
Copy link
Collaborator

rustbot commented Aug 1, 2024

r? @chenyukang

rustbot has assigned @chenyukang.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

@rustbot rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. labels Aug 1, 2024
@rustbot
Copy link
Collaborator

rustbot commented Aug 1, 2024

Some changes occurred to the CTFE / Miri engine

cc @rust-lang/miri

Some changes occurred to MIR optimizations

cc @rust-lang/wg-mir-opt

@compiler-errors

This comment was marked as outdated.

@compiler-errors
Copy link
Member Author

Anywhomst, cc @RalfJung if you're curious about what this ended up looking like.

@compiler-errors compiler-errors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 1, 2024
@@ -102,25 +102,6 @@ impl<'tcx> MirPass<'tcx> for Validator {
}
}
}

// Enforce that coroutine-closure layouts are identical.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We stopped caring about this since #123021.

@compiler-errors
Copy link
Member Author

Let's get perf kicked off. I'll fix the codegen tests when I get home.

@bors try @rust-timer queue

@rust-timer

This comment has been minimized.

@rustbot rustbot added the S-waiting-on-perf Status: Waiting on a perf run to be completed. label Aug 1, 2024
bors added a commit to rust-lang-ci/rust that referenced this pull request Aug 1, 2024
Stop storing a special inner body for the coroutine by-move body for async closures

...and instead, just synthesize an item which is treated mostly normally by the MIR pipeline.

This PR does a few things:
* We synthesize a new `DefId` for the by-move body of a closure, which has its `mir_built` fed with the output of the `ByMoveBody` MIR transformation, and some other relevant queries.
* Remove the special `PassManager` hacks for handling the inner `by_move_body` stored within the coroutine's mir body. Instead, this body is fed like a regular MIR body, so it's goes through all of the `tcx.*_mir` stages normally (build -> promoted -> ...etc... -> optimized) ✨.
* Introduce `TyCtxt::is_synthetic_mir` to skip over `mir_borrowck` which is called by `mir_promoted`; borrowck isn't really possible to make work ATM since it heavily relies being called on a body generated from HIR, and is redundant by the construction of the by-move-body.
* Remove the `InstanceKind::ByMoveBody` shim, since now we have a "regular" def id, we can just use `InstanceKind::Item`. This also allows us to remove the corresponding hacks from codegen, such as in `fn_sig_for_fn_abi` ✨.

Notable remarks:
* I know it's kind of weird to be using `DefKind::Closure` here, since it's not a distinct closure but just a new MIR body. I don't believe it really matters, but I could also use a different `DefKind`... maybe one that we could use for synthetic MIR bodies in general?
@bors
Copy link
Contributor

bors commented Aug 1, 2024

⌛ Trying commit 36ed446 with merge 3904d97...

@rust-log-analyzer

This comment has been minimized.

@bors
Copy link
Contributor

bors commented Aug 1, 2024

☀️ Try build successful - checks-actions
Build commit: 3904d97 (3904d9726c8057476f260c7c166008d0eb4f50e4)

@rust-timer

This comment has been minimized.

@compiler-errors compiler-errors added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Aug 1, 2024
@rust-timer
Copy link
Collaborator

Finished benchmarking commit (3904d97): comparison URL.

Overall result: ❌ regressions - ACTION NEEDED

Benchmarking this pull request likely means that it is perf-sensitive, so we're automatically marking it as not fit for rolling up. While you can manually mark this PR as fit for rollup, we strongly recommend not doing so since this PR may lead to changes in compiler perf.

Next Steps: If you can justify the regressions found in this try perf run, please indicate this with @rustbot label: +perf-regression-triaged along with sufficient written justification. If you cannot justify the regressions please fix the regressions and do another perf run. If the next run shows neutral or positive results, the label will be automatically removed.

@bors rollup=never
@rustbot label: -S-waiting-on-perf +perf-regression

Instruction count

This is a highly reliable metric that was used to determine the overall result at the top of this comment.

mean range count
Regressions ❌
(primary)
0.4% [0.2%, 0.8%] 54
Regressions ❌
(secondary)
0.7% [0.2%, 1.1%] 18
Improvements ✅
(primary)
- - 0
Improvements ✅
(secondary)
- - 0
All ❌✅ (primary) 0.4% [0.2%, 0.8%] 54

Max RSS (memory usage)

Results (primary 5.4%, secondary 8.5%)

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

mean range count
Regressions ❌
(primary)
5.4% [0.6%, 16.9%] 7
Regressions ❌
(secondary)
8.5% [6.8%, 11.8%] 3
Improvements ✅
(primary)
- - 0
Improvements ✅
(secondary)
- - 0
All ❌✅ (primary) 5.4% [0.6%, 16.9%] 7

Cycles

Results (primary 1.7%)

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

mean range count
Regressions ❌
(primary)
1.7% [1.2%, 2.1%] 2
Regressions ❌
(secondary)
- - 0
Improvements ✅
(primary)
- - 0
Improvements ✅
(secondary)
- - 0
All ❌✅ (primary) 1.7% [1.2%, 2.1%] 2

Binary size

This benchmark run did not return any relevant results for this metric.

Bootstrap: 756.054s -> 761.062s (0.66%)
Artifact size: 336.95 MiB -> 337.01 MiB (0.02%)

@rustbot rustbot added perf-regression Performance regression. and removed S-waiting-on-perf Status: Waiting on a perf run to be completed. labels Aug 2, 2024
@compiler-errors
Copy link
Member Author

If this doesn't help things, I'll investigate adding a new DefKind::SyntheticBody or something, to avoid needing to add tcx.is_synthetic_mir as a query.

@compiler-errors
Copy link
Member Author

@bors try @rust-timer queue

@rust-timer

This comment has been minimized.

@rustbot rustbot added the S-waiting-on-perf Status: Waiting on a perf run to be completed. label Aug 2, 2024
@bors
Copy link
Contributor

bors commented Aug 2, 2024

⌛ Trying commit bca0ea9 with merge a92413e...

@compiler-errors
Copy link
Member Author

windows should stop being a supported operating system tbh

@bors retry

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 27, 2024
@bors
Copy link
Contributor

bors commented Aug 27, 2024

⌛ Testing commit 93295ff with merge ba2f204...

bors added a commit to rust-lang-ci/rust that referenced this pull request Aug 27, 2024
…llot

Stop storing a special inner body for the coroutine by-move body for async closures

...and instead, just synthesize an item which is treated mostly normally by the MIR pipeline.

This PR does a few things:
* We synthesize a new `DefId` for the by-move body of a closure, which has its `mir_built` fed with the output of the `ByMoveBody` MIR transformation, and some other relevant queries.
* This has the `DefKind::ByMoveBody`, which we use to distinguish it from "real" bodies (that come from HIR) which need to be borrowck'd. Introduce `TyCtxt::is_synthetic_mir` to skip over `mir_borrowck` which is called by `mir_promoted`; borrowck isn't really possible to make work ATM since it heavily relies being called on a body generated from HIR, and is redundant by the construction of the by-move-body.
* Remove the special `PassManager` hacks for handling the inner `by_move_body` stored within the coroutine's mir body. Instead, this body is fed like a regular MIR body, so it's goes through all of the `tcx.*_mir` stages normally (build -> promoted -> ...etc... -> optimized) ✨.
* Remove the `InstanceKind::ByMoveBody` shim, since now we have a "regular" def id, we can just use `InstanceKind::Item`. This also allows us to remove the corresponding hacks from codegen, such as in `fn_sig_for_fn_abi` ✨.

Notable remarks:
* ~~I know it's kind of weird to be using `DefKind::Closure` here, since it's not a distinct closure but just a new MIR body. I don't believe it really matters, but I could also use a different `DefKind`... maybe one that we could use for synthetic MIR bodies in general?~~ edit: We're doing this now.
@rust-log-analyzer
Copy link
Collaborator

The job x86_64-msvc-ext failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)
[RUSTC-TIMING] miri test:false 4.457
error: failed to remove file `C:\a\rust\rust\build\x86_64-pc-windows-msvc\stage1-tools\x86_64-pc-windows-msvc\release\miri.exe`

Caused by:
  Access is denied. (os error 5)
Command has failed. Rerun with -v to see more details.
  local time: Tue, Aug 27, 2024  6:27:19 PM
  network time: Tue, 27 Aug 2024 18:27:19 GMT
##[error]Process completed with exit code 1.
Post job cleanup.

@bors
Copy link
Contributor

bors commented Aug 27, 2024

💔 Test failed - checks-actions

@bors bors added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Aug 27, 2024
@compiler-errors
Copy link
Member Author

@bors retry

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 27, 2024
@bors
Copy link
Contributor

bors commented Aug 27, 2024

⌛ Testing commit 93295ff with merge d9a2cc4...

@bors
Copy link
Contributor

bors commented Aug 28, 2024

☀️ Test successful - checks-actions
Approved by: cjgillot
Pushing d9a2cc4 to master...

@bors bors added the merged-by-bors This PR was explicitly merged by bors. label Aug 28, 2024
@bors bors merged commit d9a2cc4 into rust-lang:master Aug 28, 2024
7 checks passed
@rustbot rustbot added this to the 1.82.0 milestone Aug 28, 2024
@bors bors mentioned this pull request Aug 28, 2024
@rust-timer
Copy link
Collaborator

Finished benchmarking commit (d9a2cc4): comparison URL.

Overall result: ✅ improvements - no action needed

@rustbot label: -perf-regression

Instruction count

This is a highly reliable metric that was used to determine the overall result at the top of this comment.

mean range count
Regressions ❌
(primary)
- - 0
Regressions ❌
(secondary)
- - 0
Improvements ✅
(primary)
- - 0
Improvements ✅
(secondary)
-1.2% [-1.2%, -1.2%] 1
All ❌✅ (primary) - - 0

Max RSS (memory usage)

This benchmark run did not return any relevant results for this metric.

Cycles

Results (primary 2.2%, secondary 2.5%)

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

mean range count
Regressions ❌
(primary)
2.2% [2.2%, 2.2%] 1
Regressions ❌
(secondary)
2.5% [2.1%, 3.0%] 16
Improvements ✅
(primary)
- - 0
Improvements ✅
(secondary)
- - 0
All ❌✅ (primary) 2.2% [2.2%, 2.2%] 1

Binary size

This benchmark run did not return any relevant results for this metric.

Bootstrap: 752.135s -> 754.016s (0.25%)
Artifact size: 338.76 MiB -> 338.88 MiB (0.03%)

@traviscross traviscross added the F-async_closure `#![feature(async_closure)]` label Aug 28, 2024
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this pull request Sep 7, 2024
…idtwco

Do not call query to compute coroutine layout for synthetic body of async closure

There is code in the MIR validator that attempts to prevent query cycles when inlining a coroutine into itself, and will use the coroutine layout directly from the body when it detects that's the same coroutine as the one that's being validated. After rust-lang#128506, this logic didn't take into account the fact that the coroutine def id will differ if it's the "by-move body" of an async closure. This PR implements that.

Fixes rust-lang#129811
rust-timer added a commit to rust-lang-ci/rust that referenced this pull request Sep 8, 2024
Rollup merge of rust-lang#129847 - compiler-errors:async-cycle, r=davidtwco

Do not call query to compute coroutine layout for synthetic body of async closure

There is code in the MIR validator that attempts to prevent query cycles when inlining a coroutine into itself, and will use the coroutine layout directly from the body when it detects that's the same coroutine as the one that's being validated. After rust-lang#128506, this logic didn't take into account the fact that the coroutine def id will differ if it's the "by-move body" of an async closure. This PR implements that.

Fixes rust-lang#129811
bors added a commit to rust-lang-ci/rust that referenced this pull request Sep 16, 2024
…=cjgillot

Don't use `typeck_root_def_id` in codegen for finding closure's root

Generating debuginfo in codegen currently peels off all the closure-specific generics (which presumably is done because they're redundant). This doesn't currently work correctly for the bodies we synthesize for async closures's returned coroutines (rust-lang#128506), leading to rust-lang#129702.

Specifically, `typeck_root_def_id` for some `DefKind::SyntheticCoroutineBody` just returns itself (because it loops while `is_typeck_child` is `true`, and that returns `false` for this defkind), which means we don't end up peeling off the coroutine-specific generics, and we end up encountering an otherwise unreachable `CoroutineWitness` type leading to an ICE.

This PR fixes `is_typeck_child` to consider `DefKind::SyntheticCorotuineBody` to be a typeck child, fixing `typeck_root_def_id` and suppressing this debuginfo bug.

Fixes rust-lang#129702
bors added a commit to rust-lang-ci/rust that referenced this pull request Dec 13, 2024
…i-obk

Stabilize async closures (RFC 3668)

# Async Closures Stabilization Report

This report proposes the stabilization of `#![feature(async_closure)]` ([RFC 3668](https://rust-lang.github.io/rfcs/3668-async-closures.html)). This is a long-awaited feature that increases the expressiveness of the Rust language and fills a pressing gap in the async ecosystem.

## Stabilization summary

* You can write async closures like `async || {}` which return futures that can borrow from their captures and can be higher-ranked in their argument lifetimes.
* You can express trait bounds for these async closures using the `AsyncFn` family of traits, analogous to the `Fn` family.

```rust
async fn takes_an_async_fn(f: impl AsyncFn(&str)) {
    futures::join(f("hello"), f("world")).await;
}

takes_an_async_fn(async |s| { other_fn(s).await }).await;
```

## Motivation

Without this feature, users hit two major obstacles when writing async code that uses closures and `Fn` trait bounds:

- The inability to express higher-ranked async function signatures.
- That closures cannot return futures that borrow from the closure captures.

That is, for the first, we cannot write:

```rust
// We cannot express higher-ranked async function signatures.
async fn f<Fut>(_: impl for<'a> Fn(&'a u8) -> Fut)
where
    Fut: Future<Output = ()>,
{ todo!() }

async fn main() {
    async fn g(_: &u8) { todo!() }
    f(g).await;
    //~^ ERROR mismatched types
    //~| ERROR one type is more general than the other
}
```

And for the second, we cannot write:

```rust
// Closures cannot return futures that borrow closure captures.
async fn f<Fut: Future<Output = ()>>(_: impl FnMut() -> Fut)
{ todo!() }

async fn main() {
    let mut xs = vec![];
    f(|| async {
        async fn g() -> u8 { todo!() }
        xs.push(g().await);
    });
    //~^ ERROR captured variable cannot escape `FnMut` closure body
}
```

Async closures provide a first-class solution to these problems.

For further background, please refer to the [motivation section](https://rust-lang.github.io/rfcs/3668-async-closures.html#motivation) of the RFC.

## Major design decisions since RFC

The RFC had left open the question of whether we would spell the bounds syntax for async closures...

```rust
// ...as this...
fn f() -> impl AsyncFn() -> u8 { todo!() }
// ...or as this:
fn f() -> impl async Fn() -> u8 { todo!() }
```

We've decided to spell this as `AsyncFn{,Mut,Once}`.

The `Fn` family of traits is special in many ways.  We had originally argued that, due to this specialness, that perhaps the `async Fn` syntax could be adopted without having to decide whether a general `async Trait` mechanism would ever be adopted.  However, concerns have been raised that we may not want to use `async Fn` syntax unless we would pursue more general trait modifiers.  Since there remain substantial open questions on those -- and we don't want to rush any design work there -- it makes sense to ship this needed feature using the `AsyncFn`-style bounds syntax.

Since we would, in no case, be shipping a generalized trait modifier system anytime soon, we'll be continuing to see `AsyncFoo` traits appear across the ecosystem regardless.  If we were to ever later ship some general mechanism, we could at that time manage the migration from `AsyncFn` to `async Fn`, just as we'd be enabling and managing the migration of many other traits.

Note that, as specified in RFC 3668, the details of the `AsyncFn*` traits are not exposed and they can only be named via the "parentheses sugar".  That is, we can write `T: AsyncFn() -> u8` but not `T: AsyncFn<Output = u8>`.

Unlike the `Fn` traits, we cannot project to the `Output` associated type of the `AsyncFn` traits.  That is, while we can write...

```rust
fn f<F: Fn() -> u8>(_: F::Output) {}
```

...we cannot write:

```rust
fn f<F: AsyncFn() -> u8>(_: F::Output) {}
//~^ ERROR
```

The choice of `AsyncFn{,Mut,Once}` bounds syntax obviates, for our purposes here, another question decided after that RFC, which was how to order bound modifiers such as `for<'a> async Fn()`.

Other than answering the open question in the RFC on syntax, nothing has changed about the design of this feature between RFC 3668 and this stabilization.

## What is stabilized

For those interested in the technical details, please see [the dev guide section](https://rustc-dev-guide.rust-lang.org/coroutine-closures.html) I authored.

#### Async closures

Other than in how they solve the problems described above, async closures act similarly to closures that return async blocks, and can have parts of their signatures specified:

```rust
// They can have arguments annotated with types:
let _ = async |_: u8| { todo!() };

// They can have their return types annotated:
let _ = async || -> u8 { todo!() };

// They can be higher-ranked:
let _ = async |_: &str| { todo!() };

// They can capture values by move:
let x = String::from("hello, world");
let _ = async move || do_something(&x).await };
```

When called, they return an anonymous future type corresponding to the (not-yet-executed) body of the closure. These can be awaited like any other future.

What distinguishes async closures is that, unlike closures that return async blocks, the futures returned from the async closure can capture state from the async closure. For example:

```rust
let vec: Vec<String> = vec![];

let closure = async || {
    vec.push(ready(String::from("")).await);
};
```

The async closure captures `vec` with some `&'closure mut Vec<String>` which lives until the closure is dropped. Every call to `closure()` returns a future which reborrows that mutable reference `&'call mut Vec<String>` which lives until the future is dropped (e.g. it is `await`ed).

As another example:

```rust
let string: String = "Hello, world".into();

let closure = async move || {
    ready(&string).await;
};
```

The closure is marked with `move`, which means it takes ownership of the string by *value*. The future that is returned by calling `closure()` returns a future which borrows a reference `&'call String` which lives until the future is dropped (e.g. it is `await`ed).

#### Async fn trait family

To support the lending capability of async closures, and to provide a first-class way to express higher-ranked async closures, we introduce the `AsyncFn*` family of traits. See the [corresponding section](https://rust-lang.github.io/rfcs/3668-async-closures.html#asyncfn) of the RFC.

We stabilize naming `AsyncFn*` via the "parenthesized sugar" syntax that normal `Fn*` traits can be named. The `AsyncFn*` trait can be used anywhere a `Fn*` trait bound is allowed, such as:

```rust
/// In return-position impl trait:
fn closure() -> impl AsyncFn() { async || {} }

/// In trait bounds:
trait Foo<F>: Sized
where
    F: AsyncFn()
{
    fn new(f: F) -> Self;
}

/// in GATs:
trait Gat {
    type AsyncHasher<T>: AsyncFn(T) -> i32;
}
```

Other than using them in trait bounds, the definitions of these traits are not directly observable, but certain aspects of their behavior can be indirectly observed such as the fact that:

* `AsyncFn::async_call` and `AsyncFnMut::async_call_mut` return a future which is *lending*, and therefore borrows the `&self` lifetime of the callee.

```rust
fn by_ref_call(c: impl AsyncFn()) {
    let fut = c();
    drop(c);
    //   ^ Cannot drop `c` since it is borrowed by `fut`.
}
```

* `AsyncFnOnce::async_call_once` returns a future that takes ownership of the callee.

```rust
fn by_ref_call(c: impl AsyncFnOnce()) {
    let fut = c();
    let _ = c();
    //      ^ Cannot call `c` since calling it takes ownership the callee.
}
```

* All currently-stable callable types (i.e., closures, function items, function pointers, and `dyn Fn*` trait objects) automatically implement `AsyncFn*() -> T` if they implement `Fn*() -> Fut` for some output type `Fut`, and `Fut` implements `Future<Output = T>`.
    * This is to make sure that `AsyncFn*()` trait bounds have maximum compatibility with existing callable types which return futures, such as async function items and closures which return boxed futures.
    * For now, this only works currently for *concrete* callable types -- for example, a argument-position impl trait like `impl Fn() -> impl Future<Output = ()>` does not implement `AsyncFn()`, due to the fact that a `AsyncFn`-if-`Fn` blanket impl does not exist in reality. This may be relaxed in the future. Users can work around this by wrapping their type in an async closure and calling it. I expect this to not matter much in practice, as users are encouraged to write `AsyncFn` bounds directly.

```rust
fn is_async_fn(_: impl AsyncFn(&str)) {}

async fn async_fn_item(s: &str) { todo!() }
is_async_fn(s);
// ^^^ This works.

fn generic(f: impl Fn() -> impl Future<Output = ()>) {
    is_async_fn(f);
    // ^^^ This does not work (yet).
}
```

#### The by-move future

When async closures are called with `AsyncFn`/`AsyncFnMut`, they return a coroutine that borrows from the closure. However, when they are called via `AsyncFnOnce`, we consume that closure, and cannot return a coroutine that borrows from data that is now dropped.

To work around around this limitation, we synthesize a separate future type for calling the async closure via `AsyncFnOnce`.

This future executes identically to the by-ref future returned from calling the async closure, except for the fact that it has a different set of captures, since we must *move* the captures from the parent async into the child future.

#### Interactions between async closures and the `Fn*` family of traits

Async closures always implement `FnOnce`, since they always can be called once. They may also implement `Fn` or `FnMut` if their body is compatible with the calling mode (i.e. if they do not mutate their captures, or they do not capture their captures, respectively) and if the future returned by the async closure is not *lending*.

```rust
let id = String::new();

let mapped: Vec</* impl Future */> =
    [/* elements */]
    .into_iter()
    // `Iterator::map` takes an `impl FnMut`
    .map(async |element| {
        do_something(&id, element).await;
    })
    .collect();
```

See [the dev guide](https://rustc-dev-guide.rust-lang.org/coroutine-closures.html#follow-up-when-do-async-closures-implement-the-regular-fn-traits) for a detailed explanation for the situations where this may not be possible due to the lending nature of async closures.

#### Other notable features of async closures shared with synchronous closures

* Async closures are `Copy` and/or `Clone` if their captures are `Copy`/`Clone`.
* Async closures do closure signature inference: If an async closure is passed to a function with a `AsyncFn` or `Fn` trait bound, we can eagerly infer the argument types of the closure. More details are provided in [the dev guide](https://rustc-dev-guide.rust-lang.org/coroutine-closures.html#closure-signature-inference).

#### Lints

This PR also stabilizes the `CLOSURE_RETURNING_ASYNC_BLOCK` lint as an `allow` lint. This lints on "old-style" async closures:

```rust
#![warn(closure_returning_async_block)]
let c = |x: &str| async {};
```

We should encourage users to use `async || {}` where possible. This lint remains `allow` and may be refined in the future because it has a few false positives (namely, see: "Where do we expect rewriting `|| async {}` into `async || {}` to fail?")

An alternative that could be made at the time of stabilization is to put this lint behind another gate, so we can decide to stabilize it later.

## What isn't stabilized (aka, potential future work)

#### `async Fn*()` bound syntax

We decided to stabilize async closures without the `async Fn*()` bound modifier syntax. The general direction of this syntax and how it fits is still being considered by T-lang (e.g. in [RFC 3710](rust-lang/rfcs#3710)).

#### Naming the futures returned by async closures

This stabilization PR does not provide a way of naming the futures returned by calling `AsyncFn*`.

Exposing a stable way to refer to these futures is important for building async-closure-aware combinators, and will be an important future step.

#### Return type notation-style bounds for async closures

The RFC described an RTN-like syntax for putting bounds on the future returned by an async closure:

```rust
async fn foo(x: F) -> Result<()>
where
    F: AsyncFn(&str) -> Result<()>,
    // The future from calling `F` is `Send` and `'static`.
    F(..): Send + 'static,
{}
```

This stabilization PR does not stabilize that syntax yet, which remains unimplemented (though will be soon).

#### `dyn AsyncFn*()`

`AsyncFn*` are not dyn-compatible yet. This will likely be implemented in the future along with the dyn-compatibility of async fn in trait, since the same issue (dealing with the future returned by a call) applies there.

## Tests

Tests exist for this feature in [`tests/ui/async-await/async-closures`](https://github.com/rust-lang/rust/tree/5b542866400ad4a294f468cfa7e059d95c27a079/tests/ui/async-await/async-closures).

<details>
    <summary>A selected set of tests:</summary>

* Lending behavior of async closures
    * `tests/ui/async-await/async-closures/mutate.rs`
    * `tests/ui/async-await/async-closures/captures.rs`
    * `tests/ui/async-await/async-closures/precise-captures.rs`
    * `tests/ui/async-await/async-closures/no-borrow-from-env.rs`
* Async closures may be higher-ranked
    * `tests/ui/async-await/async-closures/higher-ranked.rs`
    * `tests/ui/async-await/async-closures/higher-ranked-return.rs`
* Async closures may implement `Fn*` traits
    * `tests/ui/async-await/async-closures/is-fn.rs`
    * `tests/ui/async-await/async-closures/implements-fnmut.rs`
* Async closures may be cloned
    * `tests/ui/async-await/async-closures/clone-closure.rs`
* Ownership of the upvars when `AsyncFnOnce` is called
    * `tests/ui/async-await/async-closures/drop.rs`
    * `tests/ui/async-await/async-closures/move-is-async-fn.rs`
    * `tests/ui/async-await/async-closures/force-move-due-to-inferred-kind.rs`
    * `tests/ui/async-await/async-closures/force-move-due-to-actually-fnonce.rs`
* Closure signature inference
    * `tests/ui/async-await/async-closures/signature-deduction.rs`
    * `tests/ui/async-await/async-closures/sig-from-bare-fn.rs`
    * `tests/ui/async-await/async-closures/signature-inference-from-two-part-bound.rs`

</details>

## Remaining bugs and open issues

* rust-lang#120694 tracks moving onto more general `LendingFn*` traits. No action needed, since it's not observable.
* rust-lang#124020 - Polymorphization ICE. Polymorphization needs to be heavily reworked. No action needed.
* rust-lang#127227 - Tracking reworking the way that rustdoc re-sugars bounds.
    * The part relevant to to `AsyncFn` is fixed by rust-lang#132697.

## Where do we expect rewriting `|| async {}` into `async || {}` to fail?

* Fn pointer coercions
    * Currently, it is not possible to coerce an async closure to an fn pointer like regular closures can be. This functionality may be implemented in the future.
```rust
let x: fn() -> _ = async || {};
```
* Argument capture
    * Like async functions, async closures always capture their input arguments. This is in contrast to something like `|t: T| async {}`, which doesn't capture `t` unless it is used in the async block. This may affect the `Send`-ness of the future or affect its outlives.
```rust
fn needs_send_future(_: impl Fn(NotSendArg) -> Fut)
where
    Fut: Future<Output = ()>,
{}

needs_send_future(async |_| {});
```

## History

#### Important feature history

- rust-lang#51580
- rust-lang#62292
- rust-lang#120361
- rust-lang#120712
- rust-lang#121857
- rust-lang#123660
- rust-lang#125259
- rust-lang#128506
- rust-lang#127482

## Acknowledgements

Thanks to `@oli-obk` for reviewing the bulk of the work for this feature. Thanks to `@nikomatsakis` for his design blog posts which generated interest for this feature, `@traviscross` for feedback and additions to this stabilization report. All errors are my own.

r? `@ghost`
github-actions bot pushed a commit to rust-lang/miri that referenced this pull request Dec 13, 2024
Stabilize async closures (RFC 3668)

# Async Closures Stabilization Report

This report proposes the stabilization of `#![feature(async_closure)]` ([RFC 3668](https://rust-lang.github.io/rfcs/3668-async-closures.html)). This is a long-awaited feature that increases the expressiveness of the Rust language and fills a pressing gap in the async ecosystem.

## Stabilization summary

* You can write async closures like `async || {}` which return futures that can borrow from their captures and can be higher-ranked in their argument lifetimes.
* You can express trait bounds for these async closures using the `AsyncFn` family of traits, analogous to the `Fn` family.

```rust
async fn takes_an_async_fn(f: impl AsyncFn(&str)) {
    futures::join(f("hello"), f("world")).await;
}

takes_an_async_fn(async |s| { other_fn(s).await }).await;
```

## Motivation

Without this feature, users hit two major obstacles when writing async code that uses closures and `Fn` trait bounds:

- The inability to express higher-ranked async function signatures.
- That closures cannot return futures that borrow from the closure captures.

That is, for the first, we cannot write:

```rust
// We cannot express higher-ranked async function signatures.
async fn f<Fut>(_: impl for<'a> Fn(&'a u8) -> Fut)
where
    Fut: Future<Output = ()>,
{ todo!() }

async fn main() {
    async fn g(_: &u8) { todo!() }
    f(g).await;
    //~^ ERROR mismatched types
    //~| ERROR one type is more general than the other
}
```

And for the second, we cannot write:

```rust
// Closures cannot return futures that borrow closure captures.
async fn f<Fut: Future<Output = ()>>(_: impl FnMut() -> Fut)
{ todo!() }

async fn main() {
    let mut xs = vec![];
    f(|| async {
        async fn g() -> u8 { todo!() }
        xs.push(g().await);
    });
    //~^ ERROR captured variable cannot escape `FnMut` closure body
}
```

Async closures provide a first-class solution to these problems.

For further background, please refer to the [motivation section](https://rust-lang.github.io/rfcs/3668-async-closures.html#motivation) of the RFC.

## Major design decisions since RFC

The RFC had left open the question of whether we would spell the bounds syntax for async closures...

```rust
// ...as this...
fn f() -> impl AsyncFn() -> u8 { todo!() }
// ...or as this:
fn f() -> impl async Fn() -> u8 { todo!() }
```

We've decided to spell this as `AsyncFn{,Mut,Once}`.

The `Fn` family of traits is special in many ways.  We had originally argued that, due to this specialness, that perhaps the `async Fn` syntax could be adopted without having to decide whether a general `async Trait` mechanism would ever be adopted.  However, concerns have been raised that we may not want to use `async Fn` syntax unless we would pursue more general trait modifiers.  Since there remain substantial open questions on those -- and we don't want to rush any design work there -- it makes sense to ship this needed feature using the `AsyncFn`-style bounds syntax.

Since we would, in no case, be shipping a generalized trait modifier system anytime soon, we'll be continuing to see `AsyncFoo` traits appear across the ecosystem regardless.  If we were to ever later ship some general mechanism, we could at that time manage the migration from `AsyncFn` to `async Fn`, just as we'd be enabling and managing the migration of many other traits.

Note that, as specified in RFC 3668, the details of the `AsyncFn*` traits are not exposed and they can only be named via the "parentheses sugar".  That is, we can write `T: AsyncFn() -> u8` but not `T: AsyncFn<Output = u8>`.

Unlike the `Fn` traits, we cannot project to the `Output` associated type of the `AsyncFn` traits.  That is, while we can write...

```rust
fn f<F: Fn() -> u8>(_: F::Output) {}
```

...we cannot write:

```rust
fn f<F: AsyncFn() -> u8>(_: F::Output) {}
//~^ ERROR
```

The choice of `AsyncFn{,Mut,Once}` bounds syntax obviates, for our purposes here, another question decided after that RFC, which was how to order bound modifiers such as `for<'a> async Fn()`.

Other than answering the open question in the RFC on syntax, nothing has changed about the design of this feature between RFC 3668 and this stabilization.

## What is stabilized

For those interested in the technical details, please see [the dev guide section](https://rustc-dev-guide.rust-lang.org/coroutine-closures.html) I authored.

#### Async closures

Other than in how they solve the problems described above, async closures act similarly to closures that return async blocks, and can have parts of their signatures specified:

```rust
// They can have arguments annotated with types:
let _ = async |_: u8| { todo!() };

// They can have their return types annotated:
let _ = async || -> u8 { todo!() };

// They can be higher-ranked:
let _ = async |_: &str| { todo!() };

// They can capture values by move:
let x = String::from("hello, world");
let _ = async move || do_something(&x).await };
```

When called, they return an anonymous future type corresponding to the (not-yet-executed) body of the closure. These can be awaited like any other future.

What distinguishes async closures is that, unlike closures that return async blocks, the futures returned from the async closure can capture state from the async closure. For example:

```rust
let vec: Vec<String> = vec![];

let closure = async || {
    vec.push(ready(String::from("")).await);
};
```

The async closure captures `vec` with some `&'closure mut Vec<String>` which lives until the closure is dropped. Every call to `closure()` returns a future which reborrows that mutable reference `&'call mut Vec<String>` which lives until the future is dropped (e.g. it is `await`ed).

As another example:

```rust
let string: String = "Hello, world".into();

let closure = async move || {
    ready(&string).await;
};
```

The closure is marked with `move`, which means it takes ownership of the string by *value*. The future that is returned by calling `closure()` returns a future which borrows a reference `&'call String` which lives until the future is dropped (e.g. it is `await`ed).

#### Async fn trait family

To support the lending capability of async closures, and to provide a first-class way to express higher-ranked async closures, we introduce the `AsyncFn*` family of traits. See the [corresponding section](https://rust-lang.github.io/rfcs/3668-async-closures.html#asyncfn) of the RFC.

We stabilize naming `AsyncFn*` via the "parenthesized sugar" syntax that normal `Fn*` traits can be named. The `AsyncFn*` trait can be used anywhere a `Fn*` trait bound is allowed, such as:

```rust
/// In return-position impl trait:
fn closure() -> impl AsyncFn() { async || {} }

/// In trait bounds:
trait Foo<F>: Sized
where
    F: AsyncFn()
{
    fn new(f: F) -> Self;
}

/// in GATs:
trait Gat {
    type AsyncHasher<T>: AsyncFn(T) -> i32;
}
```

Other than using them in trait bounds, the definitions of these traits are not directly observable, but certain aspects of their behavior can be indirectly observed such as the fact that:

* `AsyncFn::async_call` and `AsyncFnMut::async_call_mut` return a future which is *lending*, and therefore borrows the `&self` lifetime of the callee.

```rust
fn by_ref_call(c: impl AsyncFn()) {
    let fut = c();
    drop(c);
    //   ^ Cannot drop `c` since it is borrowed by `fut`.
}
```

* `AsyncFnOnce::async_call_once` returns a future that takes ownership of the callee.

```rust
fn by_ref_call(c: impl AsyncFnOnce()) {
    let fut = c();
    let _ = c();
    //      ^ Cannot call `c` since calling it takes ownership the callee.
}
```

* All currently-stable callable types (i.e., closures, function items, function pointers, and `dyn Fn*` trait objects) automatically implement `AsyncFn*() -> T` if they implement `Fn*() -> Fut` for some output type `Fut`, and `Fut` implements `Future<Output = T>`.
    * This is to make sure that `AsyncFn*()` trait bounds have maximum compatibility with existing callable types which return futures, such as async function items and closures which return boxed futures.
    * For now, this only works currently for *concrete* callable types -- for example, a argument-position impl trait like `impl Fn() -> impl Future<Output = ()>` does not implement `AsyncFn()`, due to the fact that a `AsyncFn`-if-`Fn` blanket impl does not exist in reality. This may be relaxed in the future. Users can work around this by wrapping their type in an async closure and calling it. I expect this to not matter much in practice, as users are encouraged to write `AsyncFn` bounds directly.

```rust
fn is_async_fn(_: impl AsyncFn(&str)) {}

async fn async_fn_item(s: &str) { todo!() }
is_async_fn(s);
// ^^^ This works.

fn generic(f: impl Fn() -> impl Future<Output = ()>) {
    is_async_fn(f);
    // ^^^ This does not work (yet).
}
```

#### The by-move future

When async closures are called with `AsyncFn`/`AsyncFnMut`, they return a coroutine that borrows from the closure. However, when they are called via `AsyncFnOnce`, we consume that closure, and cannot return a coroutine that borrows from data that is now dropped.

To work around around this limitation, we synthesize a separate future type for calling the async closure via `AsyncFnOnce`.

This future executes identically to the by-ref future returned from calling the async closure, except for the fact that it has a different set of captures, since we must *move* the captures from the parent async into the child future.

#### Interactions between async closures and the `Fn*` family of traits

Async closures always implement `FnOnce`, since they always can be called once. They may also implement `Fn` or `FnMut` if their body is compatible with the calling mode (i.e. if they do not mutate their captures, or they do not capture their captures, respectively) and if the future returned by the async closure is not *lending*.

```rust
let id = String::new();

let mapped: Vec</* impl Future */> =
    [/* elements */]
    .into_iter()
    // `Iterator::map` takes an `impl FnMut`
    .map(async |element| {
        do_something(&id, element).await;
    })
    .collect();
```

See [the dev guide](https://rustc-dev-guide.rust-lang.org/coroutine-closures.html#follow-up-when-do-async-closures-implement-the-regular-fn-traits) for a detailed explanation for the situations where this may not be possible due to the lending nature of async closures.

#### Other notable features of async closures shared with synchronous closures

* Async closures are `Copy` and/or `Clone` if their captures are `Copy`/`Clone`.
* Async closures do closure signature inference: If an async closure is passed to a function with a `AsyncFn` or `Fn` trait bound, we can eagerly infer the argument types of the closure. More details are provided in [the dev guide](https://rustc-dev-guide.rust-lang.org/coroutine-closures.html#closure-signature-inference).

#### Lints

This PR also stabilizes the `CLOSURE_RETURNING_ASYNC_BLOCK` lint as an `allow` lint. This lints on "old-style" async closures:

```rust
#![warn(closure_returning_async_block)]
let c = |x: &str| async {};
```

We should encourage users to use `async || {}` where possible. This lint remains `allow` and may be refined in the future because it has a few false positives (namely, see: "Where do we expect rewriting `|| async {}` into `async || {}` to fail?")

An alternative that could be made at the time of stabilization is to put this lint behind another gate, so we can decide to stabilize it later.

## What isn't stabilized (aka, potential future work)

#### `async Fn*()` bound syntax

We decided to stabilize async closures without the `async Fn*()` bound modifier syntax. The general direction of this syntax and how it fits is still being considered by T-lang (e.g. in [RFC 3710](rust-lang/rfcs#3710)).

#### Naming the futures returned by async closures

This stabilization PR does not provide a way of naming the futures returned by calling `AsyncFn*`.

Exposing a stable way to refer to these futures is important for building async-closure-aware combinators, and will be an important future step.

#### Return type notation-style bounds for async closures

The RFC described an RTN-like syntax for putting bounds on the future returned by an async closure:

```rust
async fn foo(x: F) -> Result<()>
where
    F: AsyncFn(&str) -> Result<()>,
    // The future from calling `F` is `Send` and `'static`.
    F(..): Send + 'static,
{}
```

This stabilization PR does not stabilize that syntax yet, which remains unimplemented (though will be soon).

#### `dyn AsyncFn*()`

`AsyncFn*` are not dyn-compatible yet. This will likely be implemented in the future along with the dyn-compatibility of async fn in trait, since the same issue (dealing with the future returned by a call) applies there.

## Tests

Tests exist for this feature in [`tests/ui/async-await/async-closures`](https://github.com/rust-lang/rust/tree/5b542866400ad4a294f468cfa7e059d95c27a079/tests/ui/async-await/async-closures).

<details>
    <summary>A selected set of tests:</summary>

* Lending behavior of async closures
    * `tests/ui/async-await/async-closures/mutate.rs`
    * `tests/ui/async-await/async-closures/captures.rs`
    * `tests/ui/async-await/async-closures/precise-captures.rs`
    * `tests/ui/async-await/async-closures/no-borrow-from-env.rs`
* Async closures may be higher-ranked
    * `tests/ui/async-await/async-closures/higher-ranked.rs`
    * `tests/ui/async-await/async-closures/higher-ranked-return.rs`
* Async closures may implement `Fn*` traits
    * `tests/ui/async-await/async-closures/is-fn.rs`
    * `tests/ui/async-await/async-closures/implements-fnmut.rs`
* Async closures may be cloned
    * `tests/ui/async-await/async-closures/clone-closure.rs`
* Ownership of the upvars when `AsyncFnOnce` is called
    * `tests/ui/async-await/async-closures/drop.rs`
    * `tests/ui/async-await/async-closures/move-is-async-fn.rs`
    * `tests/ui/async-await/async-closures/force-move-due-to-inferred-kind.rs`
    * `tests/ui/async-await/async-closures/force-move-due-to-actually-fnonce.rs`
* Closure signature inference
    * `tests/ui/async-await/async-closures/signature-deduction.rs`
    * `tests/ui/async-await/async-closures/sig-from-bare-fn.rs`
    * `tests/ui/async-await/async-closures/signature-inference-from-two-part-bound.rs`

</details>

## Remaining bugs and open issues

* rust-lang/rust#120694 tracks moving onto more general `LendingFn*` traits. No action needed, since it's not observable.
* rust-lang/rust#124020 - Polymorphization ICE. Polymorphization needs to be heavily reworked. No action needed.
* rust-lang/rust#127227 - Tracking reworking the way that rustdoc re-sugars bounds.
    * The part relevant to to `AsyncFn` is fixed by rust-lang/rust#132697.

## Where do we expect rewriting `|| async {}` into `async || {}` to fail?

* Fn pointer coercions
    * Currently, it is not possible to coerce an async closure to an fn pointer like regular closures can be. This functionality may be implemented in the future.
```rust
let x: fn() -> _ = async || {};
```
* Argument capture
    * Like async functions, async closures always capture their input arguments. This is in contrast to something like `|t: T| async {}`, which doesn't capture `t` unless it is used in the async block. This may affect the `Send`-ness of the future or affect its outlives.
```rust
fn needs_send_future(_: impl Fn(NotSendArg) -> Fut)
where
    Fut: Future<Output = ()>,
{}

needs_send_future(async |_| {});
```

## History

#### Important feature history

- rust-lang/rust#51580
- rust-lang/rust#62292
- rust-lang/rust#120361
- rust-lang/rust#120712
- rust-lang/rust#121857
- rust-lang/rust#123660
- rust-lang/rust#125259
- rust-lang/rust#128506
- rust-lang/rust#127482

## Acknowledgements

Thanks to `@oli-obk` for reviewing the bulk of the work for this feature. Thanks to `@nikomatsakis` for his design blog posts which generated interest for this feature, `@traviscross` for feedback and additions to this stabilization report. All errors are my own.

r? `@ghost`
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
F-async_closure `#![feature(async_closure)]` merged-by-bors This PR was explicitly merged by bors. PG-exploit-mitigations Project group: Exploit mitigations S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-compiler Relevant to the compiler team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

9 participants