From f52ebaa45dcb35a7dbb8fcb1a19ad41de02ab581 Mon Sep 17 00:00:00 2001 From: Roland Kuhn Date: Sun, 13 Feb 2022 17:08:30 +0100 Subject: [PATCH 1/3] document expectations for Waker::wake fixes #93961 --- library/core/src/task/wake.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/library/core/src/task/wake.rs b/library/core/src/task/wake.rs index 27af227a1f27f..c3e6c1f84ade9 100644 --- a/library/core/src/task/wake.rs +++ b/library/core/src/task/wake.rs @@ -219,6 +219,13 @@ unsafe impl Sync for Waker {} impl Waker { /// Wake up the task associated with this `Waker`. + /// + /// Multiple wake-ups (through clones of this `Waker` or `wake_by_ref`) may be + /// coalesced into a single `poll` invocation by the runtime, and as long as + /// the runtime keeps running and the task is not finished it is expected that + /// each wake-up is followed by an invocation of `poll`, even in the absence of + /// other events. This makes it possible to yield to other tasks when running + /// potentially unbounded processing loops in order to maintain fairness. #[inline] #[stable(feature = "futures_api", since = "1.36.0")] pub fn wake(self) { From 2946f7aad17c5445c3837a6691bf2b7f51e883a8 Mon Sep 17 00:00:00 2001 From: Roland Kuhn Date: Sun, 20 Feb 2022 12:23:26 +0100 Subject: [PATCH 2/3] improve wording of Waker::wake documentation --- library/core/src/task/wake.rs | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/library/core/src/task/wake.rs b/library/core/src/task/wake.rs index c3e6c1f84ade9..301cfacb554ad 100644 --- a/library/core/src/task/wake.rs +++ b/library/core/src/task/wake.rs @@ -220,12 +220,14 @@ unsafe impl Sync for Waker {} impl Waker { /// Wake up the task associated with this `Waker`. /// - /// Multiple wake-ups (through clones of this `Waker` or `wake_by_ref`) may be - /// coalesced into a single `poll` invocation by the runtime, and as long as - /// the runtime keeps running and the task is not finished it is expected that - /// each wake-up is followed by an invocation of `poll`, even in the absence of - /// other events. This makes it possible to yield to other tasks when running - /// potentially unbounded processing loops in order to maintain fairness. + /// 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. #[inline] #[stable(feature = "futures_api", since = "1.36.0")] pub fn wake(self) { From 3d808d52dec3db864532403f980a38ff98e3af8a Mon Sep 17 00:00:00 2001 From: Roland Kuhn Date: Wed, 4 May 2022 10:58:23 +0200 Subject: [PATCH 3/3] add caveat discussed in #74335 --- library/core/src/task/wake.rs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/library/core/src/task/wake.rs b/library/core/src/task/wake.rs index 301cfacb554ad..9e74bcc541ea2 100644 --- a/library/core/src/task/wake.rs +++ b/library/core/src/task/wake.rs @@ -228,6 +228,10 @@ impl Waker { /// /// 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) {