bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Rollup merge of #116387 - kpreid:wake-doc, r=cuviper

Browse source 
Additional doc links and explanation of `Wake`.

This is intended to clarify:

* That `Wake` exists and can be used instead of `RawWaker`.
* How to construct a `Waker` when you are looking at `Wake` (which was previously only documented in the example).
This commit is contained in:
Oli Scherer 2024-02-14 11:53:37 +01:00 • committed by GitHub
commit 5d114f3c99
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 27 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

13
library/alloc/src/task.rs
View file

@ -19,7 +19,7 @@ use core::task::Waker;
/// The implementation of waking a task on an executor.
///
/// This trait can be used to create a [`Waker`]. An executor can define an
/// implementation of this trait, and use that to construct a Waker to pass
/// implementation of this trait, and use that to construct a [`Waker`] to pass
/// to the tasks that are executed on that executor.
///
/// This trait is a memory-safe and ergonomic alternative to constructing a
@ -28,7 +28,14 @@ use core::task::Waker;
/// those for embedded systems) cannot use this API, which is why [`RawWaker`]
/// exists as an alternative for those systems.
///
/// [arc]: ../../std/sync/struct.Arc.html
/// To construct a [`Waker`] from some type `W` implementing this trait,
/// wrap it in an [`Arc<W>`](Arc) and call `Waker::from()` on that.
/// It is also possible to convert to [`RawWaker`] in the same way.
///
/// <!-- Ideally we'd link to the `From` impl, but rustdoc doesn't generate any page for it within
/// `alloc` because `alloc` neither defines nor re-exports `From` or `Waker`, and we can't
/// link ../../std/task/struct.Waker.html#impl-From%3CArc%3CW,+Global%3E%3E-for-Waker
/// without getting a link-checking error in CI. -->
///
/// # Examples
///
@ -100,7 +107,7 @@ pub trait Wake {
#[cfg(target_has_atomic = "ptr")]
#[stable(feature = "wake_trait", since = "1.51.0")]
impl<W: Wake + Send + Sync + 'static> From<Arc<W>> for Waker {
/// Use a `Wake`-able type as a `Waker`.
/// Use a [`Wake`]-able type as a `Waker`.
///
/// No heap allocations or atomic operations are used for this conversion.
fn from(waker: Arc<W>) -> Waker {

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

@ -9,10 +9,14 @@ use crate::ptr;
/// A `RawWaker` allows the implementor of a task executor to create a [`Waker`]
/// or a [`LocalWaker`] which provides customized wakeup behavior.
///
/// [vtable]: https://en.wikipedia.org/wiki/Virtual_method_table
///
/// It consists of a data pointer and a [virtual function pointer table (vtable)][vtable]
/// that customizes the behavior of the `RawWaker`.
///
/// `RawWaker`s are unsafe to use.
/// Implementing the [`Wake`] trait is a safe alternative that requires memory allocation.
///
/// [vtable]: https://en.wikipedia.org/wiki/Virtual_method_table
/// [`Wake`]: ../../alloc/task/trait.Wake.html
#[derive(PartialEq, Debug)]
#[stable(feature = "futures_api", since = "1.36.0")]
pub struct RawWaker {
@ -355,8 +359,12 @@ impl<'a> ContextBuilder<'a> {
/// of `*waker = new_waker.clone()`, as the former will avoid cloning the waker
/// unnecessarily if the two wakers [wake the same task](Self::will_wake).
///
/// Constructing a `Waker` from a [`RawWaker`] is unsafe.
/// Implementing the [`Wake`] trait is a safe alternative that requires memory allocation.
///
/// [`Future::poll()`]: core::future::Future::poll
/// [`Poll::Pending`]: core::task::Poll::Pending
/// [`Wake`]: ../../alloc/task/trait.Wake.html
#[cfg_attr(not(doc), repr(transparent))] // work around https://github.com/rust-lang/rust/issues/66401
#[stable(feature = "futures_api", since = "1.36.0")]
pub struct Waker {
@ -438,9 +446,15 @@ impl Waker {
/// Creates a new `Waker` from [`RawWaker`].
///
/// # Safety
///
/// The behavior of the returned `Waker` is undefined if the contract defined
/// in [`RawWaker`]'s and [`RawWakerVTable`]'s documentation is not upheld.
/// Therefore this method is unsafe.
///
/// (Authors wishing to avoid unsafe code may implement the [`Wake`] trait instead, at the
/// cost of a required heap allocation.)
///
/// [`Wake`]: ../../alloc/task/trait.Wake.html
#[inline]
#[must_use]
#[stable(feature = "futures_api", since = "1.36.0")]