Clarification needed on what happens when `Future::poll` wakes an old waker

[zopsicle]

Location

https://doc.rust-lang.org/std/future/trait.Future.html#tymethod.poll

Summary

The documentation for Future::poll reads:

Note that on multiple calls to poll, only the Waker from the Context passed to the most recent call should be scheduled to receive a wakeup.

The implications of violating this aren’t specified. One might conclude that it is a bug to wake both the old and new wakers, as it says only the new one should be used. On the other hand, it says “should”, not “must”.

Note that there is no way to avoid waking both wakers in certain cases. See for instance the answer to In async Rust, how can a Future make sure it only calls the most recent Waker?, which reads:

This may cause the old waker to be woken unnecessarily, but that's fine.

I believe the intent of this requirement for poll is that there is no guarantee waking old wakers has any effect, but it is not a bug to wake them in addition to waking the most recent one. Is that correct? If so we may want to clarify this, preferably replacing the word “should” with something more concrete.

[jieyouxu]

@rustbot label +A-async-await +T-libs -needs-triage

[traviscross]

@rustbot labels +AsyncAwait-Triaged +WG-async +I-async-nominated

We reviewed this today in WG-async triage.

We agree this is an interesting question in terms of how to clarify the documentation. Let's nominate so we discuss this later.

[mladedav]

@traviscross To be clear, the issue describes the current behavior? I.e. waking old wakers may or may not do some work or wake a task, but it will not cause any panics?