Rollup merge of #116387 - kpreid:wake-doc, r=cuviper
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:
commit
5d114f3c99
2 changed files with 27 additions and 6 deletions
|
@ -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 {
|
||||
|
|
|
@ -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")]
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue