Stabilize core::task::ready!

[yoshuawuyts]

Tracking issue: #70922

This PR stabilizes the task::ready! macro. Similar to #80886, this PR was waiting on #74355 to be fixed.

The task::ready! API has existed in the futures ecosystem for several years, and was added on nightly last year in #70817. The motivation for this macro is the same as it was back then: virtually every single manual future implementation makes use of this; so much so that it's one of the few things included in the futures-core library.

r? @tmandry

cc/ @rust-lang/wg-async-foundations @rust-lang/libs

Example

use core::task::{Context, Poll};
use core::future::Future;
use core::pin::Pin;

async fn get_num() -> usize {
    42
}

pub fn do_poll(cx: &mut Context<'_>) -> Poll<()> {
    let mut f = get_num();
    let f = unsafe { Pin::new_unchecked(&mut f) };
    
    let num = ready!(f.poll(cx));
    // ... use num

    Poll::Ready(())
}

[jyn514]

Looking at the implementation of the macro, I would expect to use ? instead, since that makes it more clear that it short-circuits and returns if the task isn't ready. Have you considered implementing Try for Poll?

cc @scottmcm since I know you've been thinking a lot about Try recently

[yoshuawuyts]

@jyn514 Poll already implements Try if the inner type is an Option, Result, or Result of Option. I forget the reason, but I believe this may simply not be possible to implement on any type T without specialization.

Actually that makes for an interesting proposition. When I introduced this API early last year specialization seemed unstable enough that I didn't feel comfortable to even suggest it. However now.. perhaps? I haven't kept up with the progress of min_specialization enough to know whether it's feasible. If we could just make this work with ? that may indeed be preferable.

[scottmcm]

@jyn514 For the Poll impls, @cramertj knows more than I do.

[sfackler]

I'd be pretty hesitant to make ? behave wildly differently for different variants of Polls. I think we're just stuck with the fact that ? on Poll maps through to the inner value.

[yoshuawuyts]

I'd be pretty hesitant to make ? behave wildly differently for different variants of Polls. I think we're just stuck with the fact that ? on Poll maps through to the inner value.

That's fair; in which case I think we should proceed with stabilizing task::ready! as per this PR.

[KodrAus]

@rfcbot fcp merge

This stabilizes the task::ready! macro, which is used in manual futures implementations to early-return on Poll::Pending.

[rfcbot]

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

• @Amanieu
• @BurntSushi
• @KodrAus
• @dtolnay
• @m-ou-se
• @sfackler
• @withoutboats

Concerns:

• naming (Stabilize core::task::ready! #81050 (comment))

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.

[m-ou-se]

Poll already implements Try if the inner type is an Option, Result, or Result of Option.

? on Poll types like Poll<Option<Result>> working on the innermost None/Err instead of the outermost Pending was stabilized as part of the futures_api, but was never really discussed much separately in the context of stabilization (or FCP'd separately). This behaviour was called out in one comment on the futures_api stabilization PR, but that comment seems to have been ignored. :(

[KodrAus]

Do we expect manual futures implementations to continue to become more niche as async becomes available in more contexts?

[yoshuawuyts]

Do we expect manual futures implementations to continue to become more niche as async becomes available in more contexts?

To some degree. For example async gen fn may replace manual Stream impls just like gen fn might for Iter, but for industrial-grade libraries it seems likely manual implementations will continue to be used. Returning anonymous futures/streams are not nearly as flexible as named impls.

Also for some async traits like AsyncRead and AsyncWrite there is no clear path yet how language level features could obsolete the need to implement these by hand.

I think the usage of ready! will likely roughly remain where it is now. Arguably it's already a bit of a niche: understanding how to implement futures takes a fair bit of learning. I suspect more language features will not so much take away from existing implementations, as make async Rust accessible to a greater number of people.

[tmandry]

My concern with stabilizing this (and with the futures API it's based on) is that std::task::ready! is easily confused with std::future::ready, a function with very different semantics.

I remember thinking of other names in the past, like try_poll!. But I didn't feel like opening a bikeshed back then. So I guess I'm doing that now 😅

[yoshuawuyts]

@tmandry are you able to file a concern about naming? We probably should ensure we don't merge this until that's resolved.

I don't feel strongly about either ready! or try_poll!. The reasoning in favor of try_poll! makes sense to me and I wouldn't be opposed to going with that instead.

[taiki-e]

@tmandry

I remember thinking of other names in the past, like try_poll!. But I didn't feel like opening a bikeshed back then. So I guess I'm doing that now 😅

Personally, I don't think the name try_poll is easy-to-understand. AFAIK, many (most?) of the use of the term "try" in the APIs of the standard library (and futures) relates to results, options, or Try traits. I think it's confusing to add another try_* that behaves wildly differently from the Try implementation of Poll.

FWIW, In the past futures had a macro called try_poll that did something wildly different. rust-lang/futures-rs#1698. (There was also a macro called try_ready.)

[tmandry]

@tmandry are you able to file a concern about naming?

Not sure, but I can try...

@rfcbot concern naming

[tmandry]

Another idea I remember is poll_await!, since you're basically awaiting a future inside of a poll implementation.

[m-ou-se]

@rfcbot concern naming

[taiki-e]

Another idea I remember is poll_await!, since you're basically awaiting a future inside of a poll implementation.

I'm not sure it's preferable to use names that include await.
Unlike .await, ready returns early rather than suspending.
I know that some people are already writing broken code using ready like .await (i.e., the code that misunderstands that the state when ready is called is maintained in the next poll* call), but names that include await may be more misleading.

[rfcbot]

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

[Kestrer]

ready! is going to remain in Tokio's API surface for a while, even if it's deprecated

FWIW Tokio doesn't actually expose ready!. But so many other crates do that the point still stands.

[yoshuawuyts]

I've updated the PR back to core::task::ready!, reflecting the decision made by the libs team in #81050 (comment). That means that once the FCP expires this PR should be good to merge!

[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.

[m-ou-se]

@bors r+

[bors]

📌 Commit 18cc06c has been approved by m-ou-se