Add `Future::poll_once` #92116

ibraheemdev · 2021-12-20T05:07:45Z

This PR adds Future::poll_once, which returns the output of polling a future once.

let f = ready(1);
assert_eq!(f.poll_once().await, Poll::Ready(1));

let mut f = pending();
assert_eq!(f.poll_once().await, Poll::Pending);

I'm not sure what a good name for this would be (try_await?). It isn't polling once any more than Future::poll is. Maybe keeping it as a macro/free-standing function is the best way to resolve the ambiguity?

Prior Art: https://docs.rs/futures/latest/futures/macro.poll.html

(Can someone on the team cc/ @rust-lang/wg-async-foundations?)

rust-highfive · 2021-12-20T05:07:48Z

r? @scottmcm

(rust-highfive has picked a reviewer for you, use r? to override)

rust-log-analyzer · 2021-12-20T05:19:35Z

The job mingw-check failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

configure: rust.debug-assertions := True
configure: rust.overflow-checks := True
configure: llvm.assertions      := True
configure: dist.missing-tools   := True
configure: build.configure-args := ['--enable-sccache', '--disable-manage-submodu ...
configure: writing `config.toml` in current directory
configure: 
configure: run `python /checkout/x.py --help`
configure: 
---
Building stage0 std artifacts (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)
    Finished release [optimized] target(s) in 0.18s
Copying stage0 std from stage0 (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu / x86_64-unknown-linux-gnu)
 Documenting core v0.0.0 (/checkout/library/core)
error: unresolved link to `poll_once`
  |
  |
8 | /// This `struct` is created by [`poll_once()`]. See its
  |                                   ^^^^^^^^^^^ no item named `poll_once` in scope
  |
  = note: `-D rustdoc::broken-intra-doc-links` implied by `-D warnings`
  = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
error: could not document `core`

Caused by:
Caused by:
  process didn't exit successfully: `/checkout/obj/build/bootstrap/debug/rustdoc --edition=2018 --crate-type lib --crate-name core library/core/src/lib.rs --target x86_64-unknown-linux-gnu -o /checkout/obj/build/x86_64-unknown-linux-gnu/stage0-std/x86_64-unknown-linux-gnu/doc --error-format=json --json=diagnostic-rendered-ansi --markdown-css rust.css --markdown-no-toc -Z unstable-options --resource-suffix 1.59.0 --index-page /checkout/src/doc/index.md -C metadata=4599449636879869 -L dependency=/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-std/x86_64-unknown-linux-gnu/release/deps -L dependency=/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-std/release/deps --cfg=bootstrap -Zsymbol-mangling-version=legacy -Dwarnings '-Wrustdoc::invalid_codeblock_attributes' --crate-version '1.59.0-nightly
  (0faca5355
  2021-12-20)' '-Zcrate-attr=doc(html_root_url="https://doc.rust-lang.org/nightly/")'` (exit status: 1)


command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "rustdoc" "--target" "x86_64-unknown-linux-gnu" "-Zbinary-dep-depinfo" "-j" "16" "--release" "--locked" "--color" "always" "--features" "panic-unwind backtrace compiler-builtins-c" "--manifest-path" "/checkout/library/test/Cargo.toml" "-p" "core" "-Zskip-rustdoc-fingerprint" "--" "--markdown-css" "rust.css" "--markdown-no-toc" "-Z" "unstable-options" "--resource-suffix" "1.59.0" "--index-page" "/checkout/src/doc/index.md"


Build completed unsuccessfully in 0:00:07

taiki-e · 2021-12-20T05:38:32Z

If you use this function without considering the cancellation safety of the underlying future, it may cause various bugs (rust-lang/futures-rs#2452 (review)). So, I do not agree with adding this without caveats.

taiki-e · 2021-12-20T05:39:08Z

cc @rust-lang/wg-async-foundations

yoshuawuyts · 2021-12-20T10:16:39Z

I don't mind this feature too much, but it is worth noting the applications of this are definitely limited. We never added this functionality to async-std, and I don't recall anyone requesting we add this either. In particular the F: Unpin bound limits what this can be used for in practice.

I agree with @taiki-e that the "drop in-place" nature of poll_once has the potential to lead to bugs: state is often contained within a future, and destructors are run on drop. This indeed means that using poll_once by someone who doesn't understand Rust's futures poll model can lead to logic bugs, and needs to be warned against.

Overall it seems poll_once would be most useful for showing how futures internals work (example: stdlib docs), or (in limited cases) testing futures manually authored futures state machines. Whether this is enough to carry this feature I'm unsure about.

nrc · 2021-12-20T10:30:40Z

I agree with both concerns (level of motivation and drop/cancellation safety). I think at the least, the docs need expanding to properly explain what this function does, why it is different to poll (which as you say, also only polls once), and what can go wrong with cancellation. I think it needs better motivation here before we add it to std, in particular, why this has to be in std rather than in a crate, given that it seems both dangerous and somewhat niche in its usage.

scottmcm · 2021-12-20T10:38:02Z

Marking this for team discussion, since I don't have enough context to know whether to take this.

joshtriplett · 2021-12-21T07:23:37Z

I'd love to see a specific use case for this as well.

cramertj · 2021-12-21T18:12:46Z

I don't think we should begin piecemeal importing combinators like this into std. I think there should be a design RFC first on if and how to transition combinator methods from futures-rs and tokio into std. Until then, functions like this can exist in those external crates.

JohnCSimon · 2022-01-23T01:12:02Z

Ping from triage:
@ibraheemdev can you post your status on this PR and address the comments from the reviewers?

taiki-e · 2022-01-23T15:34:39Z

@yoshuawuyts This and #93176 are different features, not like a superset.

the way this works is instead of calling poll_once which consumes self, you can instead pin! the future on the stack, and then call poll repeatedly as desired.

Note that you need to have a feature to get the context in the async function/block to do the same in this way.

yoshuawuyts · 2022-01-24T00:34:17Z

@yoshuawuyts This and #93176 are different features, not like a superset.

I see. I've gone and deleted my comment further confusion. Apologies for the noise.

nikomatsakis · 2022-01-25T19:47:35Z

I don't know that this should be in std, but I did encounter a case where I wanted it. Specifically, I have some functionality that sometimes blocks and sometimes doesn't, depending on its input. That function needs to be async, but in the cases where it doesn't block, it gets called from non-async functions. I manually invoke poll and then assert that it returns Ready in these cases to bridge the gap. It required me to pin which is fine but mildly annoying.

danielhenrymantilla · 2022-01-31T14:25:09Z

library/core/src/future/poll_once.rs

+/// documentation for more.
+#[unstable(feature = "future_poll_once", issue = "92115")]
+pub struct PollOnce<F> {
+    pub(crate) future: F,


Idea to support ?Unpin:

Suggested change

pub(crate) future: F,

pub(crate) future: Option<F>,

(and a impl<F> Unpin for PollOnce<F>)

danielhenrymantilla · 2022-01-31T14:27:24Z

library/core/src/future/poll_once.rs

+    F: Future + Unpin,
+{
+    type Output = Poll<F::Output>;
+
+    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
+        Poll::Ready(Pin::new(&mut self.future).poll(cx))
+    }


Suggested change

F: Future + Unpin,

{

type Output = Poll<F::Output>;

fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {

Poll::Ready(Pin::new(&mut self.future).poll(cx))

}

F: Future,

{

type Output = Poll<F::Output>;

fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {

let future = pin!(self.future.take().expect("Polled after completion"));

Poll::Ready(future.poll(cx))

}

(c.f. Add Future::poll_once #92116 (comment))

If the dependency on a macro is deemed unsatisfactory to begin with, we could always hand-roll a Pin::new_unchecked(). This is also a nice instance to showcase the safe .pinned() (🚲 🏠) closure-based combinator:

self.future .take() .expect("Polled after completion") .pinned(|future| Poll::Ready(future.poll(cx)))

danielhenrymantilla · 2022-01-31T14:27:55Z

library/core/src/future/future.rs

+    where
+        Self: Sized,
+    {
+        PollOnce { future: self }


Suggested change

PollOnce { future: self }

PollOnce { future: Some(self) }

(c.f. Add Future::poll_once #92116 (comment))

JohnCSimon · 2022-02-27T19:18:42Z

Ping from triage:
@ibraheemdev Can you please address the comments from the reviewers?

ibraheemdev · 2022-02-27T19:28:49Z

I'd love to see a specific use case for this as well.

One that recently came up was using async in the context of a GUI/TUI event loop. One might want to periodically check a resource's status without blocking (yielding).

yoshuawuyts · 2022-02-28T10:00:33Z

One might want to periodically check a resource's status without blocking (yielding).

But poll_once consumes self? I'm not sure how that is compatible with repeatedly checking a resource? If you could, providing a concrete example for how this works would be helpful.

Darksonn · 2022-02-28T10:03:21Z

I mean, since Pin<&mut F> implements future, you could do pinned_fut.as_mut().poll_once() to do it repeatedly.

yoshuawuyts · 2022-02-28T11:32:24Z

Oh I see. It's starting to make more sense to me why this might sometimes be useful. I think it'd be helpful if we could include examples of this usage as part of the docs examples.

Also after some github searching I found that there is also prior art for poll_once in futures_lite::future::poll_once. Along with futures that then makes two libraries which provide APIs for this. Some places which seem to be using some variant of poll_once are:

JohnCSimon · 2022-04-11T02:26:08Z

@ibraheemdev
Ping from triage: Can you please post the status of this PR? This has broken tests.
Thank you.

ibraheemdev · 2022-04-11T02:38:32Z

Waiting for a decision on whether this should be added before putting in more work @JohnCSimon

joshtriplett · 2022-04-27T19:14:41Z

We discussed this in today's @rust-lang/libs-api meeting. We didn't have an objection to adding this, since it does have uses (per #92116 (comment) ). But we'd like confirmation that this is the correct API; should it be non-consuming by default, rather than taking self?

Also, is this the right name?

cc @yoshuawuyts

yoshuawuyts · 2022-04-27T23:42:19Z

But we'd like confirmation that this is the correct API; should it be non-consuming by default, rather than taking self?

I think the current API is correct as written. If the method did not consume self, I believe the self-type should be pinned (e.g. self: Pin<&mut Self>) so that we can guarantee the future won't move between calls - consuming the value is one way to guarantee this ¹.

It's interesting to think of what this might look like. Now that we seem to have a promising way to stack-pin types (std::pin::pin!) it may not be too bad to require it. This is what the use case outlined in #92116 (comment) would look like under both models:

#![feature(pin_macro)]
use std::task::Poll;
use std::pin::Pin;

// current proposed API:
let pinned_fut = pin!(future::ready(()));
assert_eq!(pinned_fut.as_mut().poll_once(), Poll::Ready(()));

// using a pinned `Self`-type in the signature:
let pinned_fut = pin!(future::ready(()));
assert_eq!(pinned_fut.poll_once(), Poll::Ready(())); // note the omission of `as_mut` here.

Going even further though: I think the main innovation of poll_once is that it surfaces the underlying std::task::Context type from within an async fn. With that in mind, if we had a function which would just return that, we wouldn't need to use poll_once and could instead call Future::poll with the passed context:

#![feature(pin_macro)]
use std::task::{self, Poll};
use std::pin::Pin;

// using a function to get the underlying `Context` object:
let pinned_fut = pin!(future::ready(()));
let cx = task::context().await; // this method is made up, it just returns the underlying `Context`
assert_eq!(pinned_fut.poll(cx), Poll::Ready(()));

The main benefit I see with this approach is that it would compose well with other poll_ methods such as AsyncIterator::poll_next. But whether this is the right API to pursue instead of poll_once I don't feel capable of accurately judging at the moment.

I'm half-remembering things here. I think this is right, but I've been out sick for a month now, which means I'm less confident than I might usually be. If folks reading along could double check this is in fact correct, I'd appreciate that. ↩

Darksonn · 2022-04-28T07:28:05Z

I agree that it should consume self. When you consume self, you support both the use-cases of consuming it and not consuming it (by calling it on a &mut F or Pin<&mut F>), whereas if you don't consume self, the use-case where you want to call it on an !Unpin future requires pinning it even if you're just consuming it.

ibraheemdev · 2022-04-29T03:03:00Z

Also, is this the right name?

I don't really think so because of the ambiguity between this and the synchronous now_or_never which uses a noop waker. As @yoshuawuyts pointed out, there's been discussion about a task::context! intrinsic (can't be a method because of the lifetime) that exposes the Context of the async fn's future. That could make things more consistent and eliminate the need for both methods:

let f = pin!(f);
f.poll(task::context!()); // poll_once
f.poll(task::noop_context()); // now_or_never

c410-f3r · 2022-05-29T10:46:57Z

What is the status of this feature?

JohnCSimon · 2022-07-03T01:29:12Z

What is the status of this feature?

@ibraheemdev - can you comment on this?

JohnCSimon · 2022-07-24T00:25:38Z

@ibraheemdev
Ping from triage: I'm closing this due to inactivity, Please reopen when you are ready to continue with this.
Note: if you do please open the PR BEFORE you push to it, else you won't be able to reopen - this is a quirk of github.
Thanks for your contribution.

@rustbot label: +S-inactive

c410-f3r · 2022-07-25T12:49:06Z

If it is OK to the OP, I will re-create this PR.

ibraheemdev · 2022-07-25T15:32:47Z

@c410-f3r see #92116 (comment), I think this is a better way forward.

c410-f3r · 2022-07-25T19:50:25Z

@c410-f3r see #92116 (comment), I think this is a better way forward.

I was hoping to experiment this feature as an user (not as a Rustc developer) but since the API requires more discussion (which is a bit strange for nightly), then I give up due to the lack of personal energy.

add Future::poll_once

c9fb387

rust-highfive assigned scottmcm Dec 20, 2021

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Dec 20, 2021

ibraheemdev mentioned this pull request Dec 20, 2021

Tracking Issue for Future::poll_once. #92115

Closed

3 tasks

nrc added A-async-await Area: Async & Await T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Dec 20, 2021

scottmcm added I-libs-api-nominated The issue / PR has been nominated for discussion during a libs-api team meeting. S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). labels Dec 20, 2021

dtolnay added T-libs-api Relevant to the library API team, which will review and decide on the PR/issue. and removed T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Dec 20, 2021

m-ou-se removed the I-libs-api-nominated The issue / PR has been nominated for discussion during a libs-api team meeting. label Dec 22, 2021

danielhenrymantilla reviewed Jan 31, 2022

View reviewed changes

scottmcm assigned joshtriplett and unassigned scottmcm Mar 20, 2022

JohnCSimon added the I-needs-decision Issue: In need of a decision. label Apr 11, 2022

joshtriplett removed the I-needs-decision Issue: In need of a decision. label Apr 27, 2022

JohnCSimon closed this Jul 24, 2022

rustbot added the S-inactive Status: Inactive and waiting on the author. This is often applied to closed PRs. label Jul 24, 2022

ibraheemdev mentioned this pull request Dec 2, 2022

Implement core::future::lazy #91648

Closed

taiki-e mentioned this pull request May 8, 2023

Add Future::map #111347

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add `Future::poll_once` #92116

Add `Future::poll_once` #92116

ibraheemdev commented Dec 20, 2021 •

edited

rust-highfive commented Dec 20, 2021

rust-log-analyzer commented Dec 20, 2021

taiki-e commented Dec 20, 2021

taiki-e commented Dec 20, 2021

yoshuawuyts commented Dec 20, 2021 •

edited

nrc commented Dec 20, 2021

scottmcm commented Dec 20, 2021

joshtriplett commented Dec 21, 2021

cramertj commented Dec 21, 2021

JohnCSimon commented Jan 23, 2022

taiki-e commented Jan 23, 2022 •

edited

yoshuawuyts commented Jan 24, 2022 •

edited

nikomatsakis commented Jan 25, 2022

danielhenrymantilla Jan 31, 2022 •

edited

danielhenrymantilla Jan 31, 2022 •

edited

danielhenrymantilla Jan 31, 2022 •

edited

JohnCSimon commented Feb 27, 2022

ibraheemdev commented Feb 27, 2022

yoshuawuyts commented Feb 28, 2022

Darksonn commented Feb 28, 2022

yoshuawuyts commented Feb 28, 2022 •

edited

JohnCSimon commented Apr 11, 2022

ibraheemdev commented Apr 11, 2022

joshtriplett commented Apr 27, 2022 •

edited

yoshuawuyts commented Apr 27, 2022 •

edited

Darksonn commented Apr 28, 2022

ibraheemdev commented Apr 29, 2022

c410-f3r commented May 29, 2022

JohnCSimon commented Jul 3, 2022

JohnCSimon commented Jul 24, 2022

c410-f3r commented Jul 25, 2022

ibraheemdev commented Jul 25, 2022

c410-f3r commented Jul 25, 2022

Add Future::poll_once #92116

Add Future::poll_once #92116

Conversation

ibraheemdev commented Dec 20, 2021 • edited

rust-highfive commented Dec 20, 2021

rust-log-analyzer commented Dec 20, 2021

taiki-e commented Dec 20, 2021

taiki-e commented Dec 20, 2021

yoshuawuyts commented Dec 20, 2021 • edited

nrc commented Dec 20, 2021

scottmcm commented Dec 20, 2021

joshtriplett commented Dec 21, 2021

cramertj commented Dec 21, 2021

JohnCSimon commented Jan 23, 2022

taiki-e commented Jan 23, 2022 • edited

yoshuawuyts commented Jan 24, 2022 • edited

nikomatsakis commented Jan 25, 2022

danielhenrymantilla Jan 31, 2022 • edited

Choose a reason for hiding this comment

danielhenrymantilla Jan 31, 2022 • edited

Choose a reason for hiding this comment

danielhenrymantilla Jan 31, 2022 • edited

Choose a reason for hiding this comment

JohnCSimon commented Feb 27, 2022

ibraheemdev commented Feb 27, 2022

yoshuawuyts commented Feb 28, 2022

Darksonn commented Feb 28, 2022

yoshuawuyts commented Feb 28, 2022 • edited

JohnCSimon commented Apr 11, 2022

ibraheemdev commented Apr 11, 2022

joshtriplett commented Apr 27, 2022 • edited

yoshuawuyts commented Apr 27, 2022 • edited

Footnotes

Darksonn commented Apr 28, 2022

ibraheemdev commented Apr 29, 2022

c410-f3r commented May 29, 2022

JohnCSimon commented Jul 3, 2022

JohnCSimon commented Jul 24, 2022

c410-f3r commented Jul 25, 2022

ibraheemdev commented Jul 25, 2022

c410-f3r commented Jul 25, 2022

Add `Future::poll_once` #92116

Add `Future::poll_once` #92116

ibraheemdev commented Dec 20, 2021 •

edited

yoshuawuyts commented Dec 20, 2021 •

edited

taiki-e commented Jan 23, 2022 •

edited

yoshuawuyts commented Jan 24, 2022 •

edited

danielhenrymantilla Jan 31, 2022 •

edited

danielhenrymantilla Jan 31, 2022 •

edited

danielhenrymantilla Jan 31, 2022 •

edited

yoshuawuyts commented Feb 28, 2022 •

edited

joshtriplett commented Apr 27, 2022 •

edited

yoshuawuyts commented Apr 27, 2022 •

edited