From 9a95573c2bb3e76643f0c1c4deb5eea24c37ec5c Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Mon, 5 Aug 2024 17:25:00 +0100 Subject: [PATCH] Add cautionary paragraph about noop wakers. Based on a suggestion from @kpreid, with some further editing. --- library/core/src/task/wake.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/library/core/src/task/wake.rs b/library/core/src/task/wake.rs index baa8a956f8a..4d2de6be025 100644 --- a/library/core/src/task/wake.rs +++ b/library/core/src/task/wake.rs @@ -539,6 +539,10 @@ pub fn will_wake(&self, other: &Waker) -> bool { /// some futures, but are not expecting those futures to wake the waker or /// do not need to do anything specific if it happens. /// + /// More generally, using `Waker::noop()` to poll a future + /// means discarding the notification of when the future should be polled again. + /// So it should only be used when such a notification will not be needed to make progress. + /// /// If an owned `Waker` is needed, `clone()` this one. /// /// # Examples @@ -796,6 +800,10 @@ pub fn will_wake(&self, other: &LocalWaker) -> bool { /// some futures, but are not expecting those futures to wake the waker or /// do not need to do anything specific if it happens. /// + /// More generally, using `LocalWaker::noop()` to poll a future + /// means discarding the notification of when the future should be polled again, + /// So it should only be used when such a notification will not be needed to make progress. + /// /// If an owned `LocalWaker` is needed, `clone()` this one. /// /// # Examples