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, the runtime 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,13 @@ impl Waker {
     /// executor’s choice which task to run and the executor may choose to run the
     /// current task again.
     ///
+    /// To avoid missed wakeups, the runtime must ensure that for any call to `wake`, 
+    /// there is a subsequent call to `poll` such that the returned `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 `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")]