Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

document expectations for Waker::wake #93966

Merged
merged 3 commits into from
May 25, 2022
Merged

document expectations for Waker::wake #93966

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f52ebaa
document expectations for Waker::wake
rkuhn Feb 13, 2022
2946f7a
improve wording of Waker::wake documentation
rkuhn Feb 20, 2022
3d808d5
add caveat discussed in #74335
rkuhn May 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions library/core/src/task/wake.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment on lines +226 to +227
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't necessarily true; the executor could choose to poll this task again immediately instead of polling other tasks in a fair manner. See related discussion on #74335.

The above guarantee does say that you are allowed to yield without breaking your code (just not that it will do anything useful). I'm quite happy to add that to the documentation.

You may want to add the caveat I mentioned to the one you wrote below.

///
/// 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) {
Expand Down