Stabilize core::future::{pending,ready}

[yoshuawuyts]

This PR stabilizes core::future::{pending,ready}, tracking issue #70921.

Motivation

These functions have been on nightly for three months now, and have lived as part of the futures ecosystem for several years. In that time these functions have undergone several iterations, with the async-std impls probably diverging the most (using async fn, which in hindsight was a mistake).

It seems the space around these functions has been thoroughly explored over the last couple of years, and the ecosystem has settled on the current shape of the functions. It seems highly unlikely we'd want to make any further changes to these functions, so I propose we stabilize.

Implementation notes

This stabilization PR was fairly straightforward; this feature has already thoroughly been reviewed by the libs team already in #70834. So all this PR does is remove the feature gate.

[rust-highfive]

r? @withoutboats

(rust_highfive has picked a reviewer for you, use r? to override)

[Mark-Simulacrum]

with the async-std impls probably diverging the most (using async fn, which in hindsight was a mistake).

Can you elaborate on this? Is there some issue that we could reference?

[taiki-e]

have lived as part of the futures ecosystem for several years

Note that most of these periods are before the async-await stabilizes.
Now that async-await is stable, most of the use of ready can actually be replaced with async blocks.
In some cases, it's more convenient than async blocks, but I don't think it's as common as it used to be.

[yoshuawuyts]

with the async-std impls probably diverging the most (using async fn, which in hindsight was a mistake).

Can you elaborate on this? Is there some issue that we could reference?

@Mark-Simulacrum I guess I hinted at this in the text of my original PR but didn't cover it explicitly (#70834):

Why future::ready?

Arguably future::ready and async {} can be considered equivalent. The main differences are that future::ready returns a future that implements Unpin, and the returned future is a concrete type. This is useful for traits that require a future as an associated type that can sometimes be a no-op (example).

The future returned from an async fn or async {} cannot be stored inside structs without boxing. This is not very common, but has come up before when trying to implement a no-op for traits that expect associated futures (example trait, workaround). Prefering manual futures over async fn in the stdlib feel similar to how the stdlib prefers named generics over impl trait because it's more widely applicable (e.g. enables the use of Turbofish) [1].

---

Now that async-await is stable, most of the use of ready can actually be replaced with async blocks. In some cases, it's more convenient than async blocks, but I don't think it's as common as it used to be.

@taiki-e Yeah I agree; future::ready is definitely mostly a helper function. It's useful when needing to store futures inside structs, but most predominantly when writing examples. Especially as a counterpart to future::pending, because while std::future::ready may be replaced by async {} in many cases, there is no replacement for future::pending.

Together they make a good pairing to convey the Future state inside examples, as for example in async_std::future::race:

use async_std::future;

let a = future::pending();
let b = future::ready(1u8);

assert_eq!(a.race(b).await, 1u8);

This example wouldn't be possible without some form of future::pending. And future::ready forms a natural counterpart to it that clearly conveys the state of the future as part of the name.

---

[1]: I'd be happy to elaborate more on this if desired. It may be useful to establish guidelines about async fn vs manual future impls in the stdlib at some point.

[withoutboats]

@rfcbot fcp merge

These two functions return, respectively, a future that is ready and a future that is pending. The ready function takes an argument, which will be returned.

The pending version would have to be implemented basically as it is.

The ready version is importantly distinct from the async identity function because it implements Unpin and has a named future that can be stored in a struct.

[rfcbot]

Team member @withoutboats has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @SimonSapin
• @dtolnay
• @sfackler
• @withoutboats

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[taiki-e]

@yoshuawuyts
Could you add a description about the difference between ready and async identity function to ready docs?
(They were also described in the PR that implemented this feature, but they were not documented, so the same question was repeated in this PR.)

most predominantly when writing examples

This depends on the content of the example. async block is more powerful, flexible, and allows delayed execution, so I'd basically recommend using async block unless you need Unpin or a named future.

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

The RFC will be merged soon.

[bors]

☔ The latest upstream changes (presumably #73265) made this pull request unmergeable. Please resolve the merge conflicts.

[yoshuawuyts]

Rebased to address the merge conflict and addressed @taiki-e's final comments.

[Nemo157]

impl<T> Debug for Pending<T> where
    T: Debug, 

T: Debug seems unnecessary here, this should probably have an explicit impl instead of a derive.

[yoshuawuyts]

@Nemo157 I'm not sure I follow? #[derive(Debug)] has the same behavior as impl<T: Debug> for Pending<T> (playground)?

[sfackler]

@Nemo157's saying that the impl can just be impl<T> Debug for Pending<T> since there isn't actually a T value to print.

[yoshuawuyts]

ah yes that makes sense! Updated with @Nemo157's feedback!

[sfackler]

Needs an ./x.py fmt, but r=me after tidy passes.

[yoshuawuyts]

@sfackler build passed!

[Dylan-DPC-zz]

@bors r=sfackler

[bors]

📌 Commit 688f447 has been approved by sfackler

[bors]

⌛ Testing commit 688f447 with merge 94a7ea2...

[bors]

☀️ Test successful - checks-actions, checks-azure
Approved by: sfackler
Pushing 94a7ea2 to master...

[yoshuawuyts]

@Dylan-DPC is the 1.47 feature flag here correct? Shouldn't this be 1.48 since the first beta has already been cut?

[Dylan-DPC-zz]

Ah ye. Can you submit a new PR with that small change? thanks