Enhance documentation on wake call memory ordering

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 runtimes 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

@@ -432,6 +432,14 @@ impl Waker {
     /// executor’s choice which task to run and the executor may choose to run the
     /// current task again.
     ///
+    /// To avoid missed wakeups, runtimes must ensure that for any call to
+    /// `wake`, there is a subsequent call to `poll` such that the call to
+    /// `wake()` _happens-before_ the beginning of the invocation of `poll`. In
+    /// particular, this means that if a task self-wakes (invokes `wake` on
+    /// itself during `poll`), then the `poll` must be invoked again because the
+    /// call to `wake` _happens-after_ the beginning of the current invocation
+    /// of `poll`.
+    ///
     /// [`poll()`]: crate::future::Future::poll
     #[inline]
     #[stable(feature = "futures_api", since = "1.36.0")]