Rollup merge of #93966 - rkuhn:patch-1, r=tmandry

document expectations for Waker::wake

fixes #93961

Opened PR for a discussion on the precise wording.

1 files changed, 13 insertions, 0 deletions

diff --git a/library/core/src/task/wake.rs b/library/core/src/task/wake.rs
index 413fe7e6cc4..87d4a25afd5 100644
--- a/library/core/src/task/wake.rs
+++ b/library/core/src/task/wake.rs
@@ -218,6 +218,19 @@ unsafe impl Sync for Waker {}
 
 impl Waker {
     /// Wake up the task associated with this `Waker`.
+    ///
+    /// As long as the runtime keeps running and the task is not finished, it is
+    /// guaranteed that each invocation of `wake` (or `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.
+    ///
+    /// Note that the above implies that multiple wake-ups may be coalesced into a
+    /// single `poll` invocation by the runtime.
+    ///
+    /// 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
+    /// current task again.
     #[inline]
     #[stable(feature = "futures_api", since = "1.36.0")]
     pub fn wake(self) {