Jason Macnak | ea22e81 | 2020-03-18 01:29:19 +0000 | [diff] [blame] | 1 | use alloc::sync::Arc; |
| 2 | |
| 3 | /// A way of waking up a specific task. |
| 4 | /// |
| 5 | /// By implementing this trait, types that are expected to be wrapped in an `Arc` |
| 6 | /// can be converted into [`Waker`] objects. |
| 7 | /// Those Wakers can be used to signal executors that a task it owns |
| 8 | /// is ready to be `poll`ed again. |
| 9 | /// |
| 10 | /// Currently, there are two ways to convert `ArcWake` into [`Waker`]: |
| 11 | /// |
| 12 | /// * [`waker`](super::waker()) converts `Arc<impl ArcWake>` into [`Waker`]. |
| 13 | /// * [`waker_ref`](super::waker_ref()) converts `&Arc<impl ArcWake>` into [`WakerRef`] that |
| 14 | /// provides access to a [`&Waker`][`Waker`]. |
| 15 | /// |
| 16 | /// [`Waker`]: std::task::Waker |
| 17 | /// [`WakerRef`]: super::WakerRef |
| 18 | // Note: Send + Sync required because `Arc<T>` doesn't automatically imply |
| 19 | // those bounds, but `Waker` implements them. |
| 20 | pub trait ArcWake: Send + Sync { |
| 21 | /// Indicates that the associated task is ready to make progress and should |
| 22 | /// be `poll`ed. |
| 23 | /// |
| 24 | /// This function can be called from an arbitrary thread, including threads which |
| 25 | /// did not create the `ArcWake` based [`Waker`]. |
| 26 | /// |
| 27 | /// Executors generally maintain a queue of "ready" tasks; `wake` should place |
| 28 | /// the associated task onto this queue. |
| 29 | /// |
| 30 | /// [`Waker`]: std::task::Waker |
| 31 | fn wake(self: Arc<Self>) { |
| 32 | Self::wake_by_ref(&self) |
| 33 | } |
| 34 | |
| 35 | /// Indicates that the associated task is ready to make progress and should |
| 36 | /// be `poll`ed. |
| 37 | /// |
| 38 | /// This function can be called from an arbitrary thread, including threads which |
| 39 | /// did not create the `ArcWake` based [`Waker`]. |
| 40 | /// |
| 41 | /// Executors generally maintain a queue of "ready" tasks; `wake_by_ref` should place |
| 42 | /// the associated task onto this queue. |
| 43 | /// |
| 44 | /// This function is similar to [`wake`](ArcWake::wake), but must not consume the provided data |
| 45 | /// pointer. |
| 46 | /// |
| 47 | /// [`Waker`]: std::task::Waker |
| 48 | fn wake_by_ref(arc_self: &Arc<Self>); |
| 49 | } |