1use 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.
20pub 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