diff --git a/library/core/src/task/wake.rs b/library/core/src/task/wake.rs index 27af227a1f27f..9e74bcc541ea2 100644 --- a/library/core/src/task/wake.rs +++ b/library/core/src/task/wake.rs @@ -219,6 +219,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) {