nordic-dev.net/rust
nordic-dev.net/rust
2
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2024-11-25 16:24:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Rollup merge of #128064 - ijackson:noop-waker-doc, r=workingjubilee

Browse Source 
Improve docs for Waker::noop and LocalWaker::noop

 * Add a warning about a likely misuse.  (See my commit message for longer rationale.)
 * Apply some probably-accidentally-omitted changes to `LocalWaker`'s docs
 * Add a comment about the clone-and-hack of the docs

I have used [semantic linefeeds](https://rhodesmill.org/brandon/2012/one-sentence-per-line/) for the docs formatting.
This commit is contained in:
Jubilee 2024-08-15 18:44:15 -07:00 committed by GitHub
commit f624f2d3f9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 19 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
library/core/src/task/wake.rs
View File

@ -530,10 +530,18 @@ impl Waker {
/// Returns a reference to a `Waker` that does nothing when used.
///
// Note! Much of the documentation for this method is duplicated
// in the docs for `LocalWaker::noop`.
// If you edit it, consider editing the other copy too.
//
/// This is mostly useful for writing tests that need a [`Context`] to poll
/// 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
@ -783,12 +791,22 @@ impl LocalWaker {
Self { waker }
}
/// Creates a new `LocalWaker` that does nothing when `wake` is called.
/// Returns a reference to a `LocalWaker` that does nothing when used.
///
// Note! Much of the documentation for this method is duplicated
// in the docs for `Waker::noop`.
// If you edit it, consider editing the other copy too.
//
/// This is mostly useful for writing tests that need a [`Context`] to poll
/// 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
///
/// ```