diff options
| -rw-r--r-- | library/alloc/src/task.rs | 12 | ||||
| -rw-r--r-- | library/core/src/task/wake.rs | 20 |
2 files changed, 26 insertions, 6 deletions
diff --git a/library/alloc/src/task.rs b/library/alloc/src/task.rs index 87db8629ad0..193c080d4bb 100644 --- a/library/alloc/src/task.rs +++ b/library/alloc/src/task.rs @@ -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,13 @@ 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()`][wi]. +/// It is also possible to convert to [`RawWaker`] in the same way. +/// +/// <!-- This impl is reachable from `alloc` but rustdoc only lists it in `std` +/// because `alloc` doesn't reexport `Waker` --> +/// [wi]: ../../std/task/struct.Waker.html#impl-From<Arc<W,+Global>>-for-Waker /// /// # Examples /// @@ -100,7 +106,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 { diff --git a/library/core/src/task/wake.rs b/library/core/src/task/wake.rs index 9ad71e394ea..c2c068977ef 100644 --- a/library/core/src/task/wake.rs +++ b/library/core/src/task/wake.rs @@ -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 { @@ -349,8 +353,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 { @@ -432,9 +440,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")] |