clarify the semantics of core::task::Waker::wake()

[rkuhn]

Based on reading e.g. the Tokio sources and knowledge passed down from async monks to novices, I assume that calling cx.waker().wake_by_ref() from the task that is currently being polled will ensure that the task is polled again soon, even if no external reason arises. However, this behaviour is not documented, at least not unambiguously — the documentation for core::future::Future only states that the waker provided by the context can be used to wake up the task, which may technically require the task to be “sleeping” for this to have an effect.

If there is consensus that wake_by_ref will always and unconditionally ensure one further call to poll, then we should document this expectation as part of the Future contract. Who agrees? Anyone against? Am I missing something?

[Thomasdezeeuw]

If there is consensus that wake_by_ref will always and unconditionally ensure one further call to poll, then we should document this expectation as part of the Future contract.

I don't think you can guarantee that. A simple counter example would be shutting down the (async) runtime after a Future is awoken via Waker::wake or wake_by_ref. These kind of guarantees (or their lack of) is a property of the runtime, not Future or Waker.

[rkuhn]

The case of a vanishing runtime is outside the control of both the Future implementor and the runtime implementor, so I think we can carve that out of the discussion. The fact that futures can disappear at any moment does not make other guarantees worthless, like the one I’m after.

Saying that this is a runtime concern is also not going to work, at least not with the path Rust async has chosen. Cooperative scheduling can only work well if there is an agreed upon mechanism for temporarily yielding the CPU to other tasks, and with the Rust API of Future/Context/Waker there is no other option but to register oneself for later wake-up and then returning Poll::Pending.

[Thomasdezeeuw]

If there is consensus that wake_by_ref will always and unconditionally ensure one further call to poll, then we should document this expectation as part of the Future contract.

The case of a vanishing runtime is outside the control of both the Future implementor and the runtime implementor, so I think we can carve that out of the discussion.

(my emphasis)

These two statements conflict. You can't just throw away part of the problem and still speak of always and unconditionally.

The fact that futures can disappear at any moment does not make other guarantees worthless, like the one I’m after.

Could you please restate the guarantee you'll looking for? Including (very reasonable) assumptions such as the runtime is still running.

Saying that this is a runtime concern is also not going to work, at least not with the path Rust async has chosen.

I'm not sure why this isn't going to work as a runtime concern? Could you elaborate?

Cooperative scheduling can only work well if there is an agreed upon mechanism for temporarily yielding the CPU to other tasks, and with the Rust API of Future/Context/Waker there is no other option but to register oneself for later wake-up and then returning Poll::Pending.

Isn't that the agreed upon mechanism already? Waker marks a Future as ready to be polled again. If the runtime (or waker implementation) decides it's not going to poll the Future any more their is little we can do. We could/should document a best-effort attempt to poll the Future again, but I don't think forcing guarantees here is the right path.

[rkuhn]

I think we’re in violent agreement here :-) And since you confirm the agreed upon mechanism, I’ll just open a PR where we can hammer out the precise wording.

[tmandry]

Related to #74335