From ccd6513c6777e9f4083743bc80abc16cd7a744d6 Mon Sep 17 00:00:00 2001 From: Kevin Reid Date: Tue, 3 Oct 2023 08:53:40 -0700 Subject: [PATCH 1/3] 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). --- library/alloc/src/task.rs | 12 +++++++++--- 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 87db8629ad09a..193c080d4bbc7 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`](Arc) and call [`Waker::from()`][wi]. +/// It is also possible to convert to [`RawWaker`] in the same way. +/// +/// +/// [wi]: ../../std/task/struct.Waker.html#impl-From>-for-Waker /// /// # Examples /// @@ -100,7 +106,7 @@ pub trait Wake { #[cfg(target_has_atomic = "ptr")] #[stable(feature = "wake_trait", since = "1.51.0")] impl From> 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) -> Waker { diff --git a/library/core/src/task/wake.rs b/library/core/src/task/wake.rs index 9ad71e394eacf..c2c068977ef59 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")] From cef46f9e3dca21fc9da6206177af43bb1ce7e664 Mon Sep 17 00:00:00 2001 From: Kevin Reid Date: Mon, 6 Nov 2023 08:06:07 -0800 Subject: [PATCH 2/3] URL-encode chars in fragment. --- library/alloc/src/task.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/alloc/src/task.rs b/library/alloc/src/task.rs index 193c080d4bbc7..1409c2d4d3456 100644 --- a/library/alloc/src/task.rs +++ b/library/alloc/src/task.rs @@ -34,7 +34,7 @@ use core::task::Waker; /// /// -/// [wi]: ../../std/task/struct.Waker.html#impl-From>-for-Waker +/// [wi]: ../../std/task/struct.Waker.html#impl-From%3CArc%3CW,+Global%3E%3E-for-Waker /// /// # Examples /// From a6c91f0ae33ade5a495ee7124b41a05157723006 Mon Sep 17 00:00:00 2001 From: Kevin Reid Date: Sat, 10 Feb 2024 22:16:18 -0800 Subject: [PATCH 3/3] Remove the link. --- library/alloc/src/task.rs | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/library/alloc/src/task.rs b/library/alloc/src/task.rs index 1409c2d4d3456..b214f4946b1b5 100644 --- a/library/alloc/src/task.rs +++ b/library/alloc/src/task.rs @@ -29,12 +29,13 @@ use core::task::Waker; /// exists as an alternative for those systems. /// /// To construct a [`Waker`] from some type `W` implementing this trait, -/// wrap it in an [`Arc`](Arc) and call [`Waker::from()`][wi]. +/// wrap it in an [`Arc`](Arc) and call `Waker::from()` on that. /// It is also possible to convert to [`RawWaker`] in the same way. /// -/// -/// [wi]: ../../std/task/struct.Waker.html#impl-From%3CArc%3CW,+Global%3E%3E-for-Waker +/// /// /// # Examples ///