diff --git a/library/alloc/src/task.rs b/library/alloc/src/task.rs index bc668f78bf740..0e36c91f466fd 100644 --- a/library/alloc/src/task.rs +++ b/library/alloc/src/task.rs @@ -37,6 +37,10 @@ use crate::sync::Arc; /// link ../../std/task/struct.Waker.html#impl-From%3CArc%3CW,+Global%3E%3E-for-Waker /// without getting a link-checking error in CI. --> /// +/// # Memory Ordering +/// +/// To avoid missed wakeups, all executors must adhere to the requirement described for [`Waker::wake`]. +/// /// # Examples /// /// A basic `block_on` function that takes a future and runs it to completion on diff --git a/library/core/src/task/wake.rs b/library/core/src/task/wake.rs index 14f0980ff6045..bdf6c59a80b80 100644 --- a/library/core/src/task/wake.rs +++ b/library/core/src/task/wake.rs @@ -418,15 +418,16 @@ unsafe impl Sync for Waker {} impl Waker { /// Wakes up the task associated with this `Waker`. /// - /// As long as the executor keeps running and the task is not finished, it is - /// guaranteed that each invocation of [`wake()`](Self::wake) (or + /// As long as the executor keeps running and the task is not finished, + /// it is guaranteed that each invocation of [`wake()`](Self::wake) (or /// [`wake_by_ref()`](Self::wake_by_ref)) will be followed by at least one - /// [`poll()`] of the task to which this `Waker` belongs. This makes - /// it possible to temporarily yield to other tasks while running potentially - /// unbounded processing loops. + /// [`poll()`] of the task to which this `Waker` belongs, and the call to + /// [`wake()`](Self::wake) (or [`wake_by_ref()`](Self::wake_by_ref)) _happens-before_ + /// the beginning of the invocation of [`poll()`]. This makes it possible to temporarily + /// yield to other tasks while running potentially unbounded processing loops. /// /// Note that the above implies that multiple wake-ups may be coalesced into a - /// single [`poll()`] invocation by the runtime. + /// single [`poll()`] invocation by the executor. /// /// Also note that yielding to competing tasks is not guaranteed: it is the /// executor’s choice which task to run and the executor may choose to run the