Rollup merge of rust-lang#157694 - xmh0511:main, r=Darksonn

Enhance documentation on wake call memory ordering

Author: JonathanBrouwer

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

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, such that 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