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 | } |
50 | |