Tracking Issue for poll.ready()?

[dtolnay]

Feature gate: #![feature(poll_ready)]

This is a tracking issue for the core::task::Poll::ready method, which combined with ? potentially supplants the ready! macro of #70922.

- let val = ready!(fut.poll(cx));
+ let val = fut.poll(cx).ready()?;

Public API

// core::task

impl<T> Poll<T> {
    pub fn ready(self) -> Ready<T>;
}

pub struct Ready<T> {...}

impl<T> Try for Ready<T> {
    type Output = T;
    type Residual = Ready<Infallible>;
    ...
}

impl<T> FromResidual for Ready<T> {...}

impl<T> FromResidual<Ready<Infallible>> for Poll<T> {...}

impl<T> Debug for Ready<T> {...}

Steps / History

• Add Poll::ready and revert stabilization of task::ready! #89651
• Remove unstable Poll::ready libs-team#214
• Remove unstable Poll::ready #107060

Unresolved Questions

• ?

[ibraheemdev]

One trivial item, should the debug implementation for Ready show the inner Poll<T>? I left it out initially without a good reason.

[m-ou-se]

One trivial item, should the debug implementation for Ready show the inner Poll<T>? I left it out initially without a good reason.

It doesn't matter much since it's unlikely that the Debug implementation for this type will be used much anyway, but the default #[derive(Debug)] implementation is probably fine here.

[BurntSushi]

Do we have a way of pinging async stakeholders here? There was a lot of discussion among several participants in #81050 for example. I can just pick out names from there, but if there's a better way...

[m-ou-se]

cc @rust-lang/wg-async-foundations

[cramertj]

Personally I find this less clear than the ready! macro:

With the .ready()? method

fn some_future_impl() -> Poll<Result<(), ()>> {
    some_check().ready()??;
    Poll::Ready(Ok(()))
}

fn some_stream_impl() -> Poll<Option<Result<(), ()>>> {
    some_check().ready()??;
    Poll::Ready(Some(Ok(())))
}

With the ready!(...) macro

fn some_future_impl() -> Poll<Result<(), ()>> {
    ready!(some_check())?;
    Poll::Ready(Ok(()))
}

fn some_stream_impl() -> Poll<Option<Result<(), ()>>> {
    ready!(some_check())?;
    Poll::Ready(Some(Ok(())))
}

The ?? in the former looks curious to me and it's not clear what order the various Try-like things are being processed (Result-like vs. Poll-like), while the latter looks more straightforward to me. That said, I also have a lot of experience using the system that exists today and never minded the ready! macro, so I'd appreciate hearing from folks who are newer to these APIs about their preferences.

[ibraheemdev]

You could write it this way:

fn some_future_impl() -> Poll<Result<(), ()>> {
    some_check()?.ready()?;
    Poll::Ready(Ok(()))
}

fn some_stream_impl() -> Poll<Option<Result<(), ()>>> {
    some_check()?.ready()?;
    Poll::Ready(Some(Ok(())))
}

Which makes it clearer IMO, because ? is generally used for Err propagation, and the .ready()? makes it clear that it is for Poll::Pending propagation.

The fact that there are two ways to use ? with Poll definitely adds complexity though.

[LucioFranco]

I have to agree with @cramertj I think the ready! macro provides a super clear "yield" point that the ready method does not have.

[eholk]

@rustbot label +AsyncAwait-triaged

[songzhi]

In the coding experience aspect, since rust-analyzer supports custom postfix-snippets, just define a snippet like the following one, you can write ready! as postfix. But this snippet completion takes effect globally, maybe confusing and annoying when writing unrelative codes.

"rust-analyzer.completion.snippets": {
    "ready!": {
      "postfix": "ready",
      "body": [
        "ready!(${receiver})",
      ],
      "requires": "std::task::ready",
      "description": "ready!()",
      "scope": "expr",
    }
}

[mjbshaw]

Drive by comment: I have to disagree with statements that ready! is clearer. As someone relatively new to async stuff, I was reading some code that used ready!. Later, after some more review, I was surprised to learn that ready! affected the control flow of the function. I was not expecting that when I was reading the code. On the other hand, I know ? will affect the control flow: that's the whole point of the ? operator. I know this is subjective and others may not agree, but I wanted to add the experience of a non-async expert here. I'd love to see poll.ready()? stabilized!

[joshtriplett]

@rfcbot merge