1 #![stable(feature = "futures_api", since = "1.36.0")]
4 use crate::marker::{PhantomData, Unpin};
6 /// A `RawWaker` allows the implementor of a task executor to create a [`Waker`]
7 /// which provides customized wakeup behavior.
9 /// [vtable]: https://en.wikipedia.org/wiki/Virtual_method_table
11 /// It consists of a data pointer and a [virtual function pointer table (vtable)][vtable]
12 /// that customizes the behavior of the `RawWaker`.
13 #[derive(PartialEq, Debug)]
14 #[stable(feature = "futures_api", since = "1.36.0")]
16 /// A data pointer, which can be used to store arbitrary data as required
17 /// by the executor. This could be e.g. a type-erased pointer to an `Arc`
18 /// that is associated with the task.
19 /// The value of this field gets passed to all functions that are part of
20 /// the vtable as the first parameter.
22 /// Virtual function pointer table that customizes the behavior of this waker.
23 vtable: &'static RawWakerVTable,
27 /// Creates a new `RawWaker` from the provided `data` pointer and `vtable`.
29 /// The `data` pointer can be used to store arbitrary data as required
30 /// by the executor. This could be e.g. a type-erased pointer to an `Arc`
31 /// that is associated with the task.
32 /// The value of this pointer will get passed to all functions that are part
33 /// of the `vtable` as the first parameter.
35 /// The `vtable` customizes the behavior of a `Waker` which gets created
36 /// from a `RawWaker`. For each operation on the `Waker`, the associated
37 /// function in the `vtable` of the underlying `RawWaker` will be called.
40 #[stable(feature = "futures_api", since = "1.36.0")]
41 #[rustc_const_stable(feature = "futures_api", since = "1.36.0")]
43 pub const fn new(data: *const (), vtable: &'static RawWakerVTable) -> RawWaker {
44 RawWaker { data, vtable }
48 /// A virtual function pointer table (vtable) that specifies the behavior
49 /// of a [`RawWaker`].
51 /// The pointer passed to all functions inside the vtable is the `data` pointer
52 /// from the enclosing [`RawWaker`] object.
54 /// The functions inside this struct are only intended to be called on the `data`
55 /// pointer of a properly constructed [`RawWaker`] object from inside the
56 /// [`RawWaker`] implementation. Calling one of the contained functions using
57 /// any other `data` pointer will cause undefined behavior.
58 #[stable(feature = "futures_api", since = "1.36.0")]
59 #[derive(PartialEq, Copy, Clone, Debug)]
60 pub struct RawWakerVTable {
61 /// This function will be called when the [`RawWaker`] gets cloned, e.g. when
62 /// the [`Waker`] in which the [`RawWaker`] is stored gets cloned.
64 /// The implementation of this function must retain all resources that are
65 /// required for this additional instance of a [`RawWaker`] and associated
66 /// task. Calling `wake` on the resulting [`RawWaker`] should result in a wakeup
67 /// of the same task that would have been awoken by the original [`RawWaker`].
68 clone: unsafe fn(*const ()) -> RawWaker,
70 /// This function will be called when `wake` is called on the [`Waker`].
71 /// It must wake up the task associated with this [`RawWaker`].
73 /// The implementation of this function must make sure to release any
74 /// resources that are associated with this instance of a [`RawWaker`] and
76 wake: unsafe fn(*const ()),
78 /// This function will be called when `wake_by_ref` is called on the [`Waker`].
79 /// It must wake up the task associated with this [`RawWaker`].
81 /// This function is similar to `wake`, but must not consume the provided data
83 wake_by_ref: unsafe fn(*const ()),
85 /// This function gets called when a [`RawWaker`] gets dropped.
87 /// The implementation of this function must make sure to release any
88 /// resources that are associated with this instance of a [`RawWaker`] and
90 drop: unsafe fn(*const ()),
94 /// Creates a new `RawWakerVTable` from the provided `clone`, `wake`,
95 /// `wake_by_ref`, and `drop` functions.
99 /// This function will be called when the [`RawWaker`] gets cloned, e.g. when
100 /// the [`Waker`] in which the [`RawWaker`] is stored gets cloned.
102 /// The implementation of this function must retain all resources that are
103 /// required for this additional instance of a [`RawWaker`] and associated
104 /// task. Calling `wake` on the resulting [`RawWaker`] should result in a wakeup
105 /// of the same task that would have been awoken by the original [`RawWaker`].
109 /// This function will be called when `wake` is called on the [`Waker`].
110 /// It must wake up the task associated with this [`RawWaker`].
112 /// The implementation of this function must make sure to release any
113 /// resources that are associated with this instance of a [`RawWaker`] and
118 /// This function will be called when `wake_by_ref` is called on the [`Waker`].
119 /// It must wake up the task associated with this [`RawWaker`].
121 /// This function is similar to `wake`, but must not consume the provided data
126 /// This function gets called when a [`RawWaker`] gets dropped.
128 /// The implementation of this function must make sure to release any
129 /// resources that are associated with this instance of a [`RawWaker`] and
132 #[stable(feature = "futures_api", since = "1.36.0")]
133 #[rustc_const_stable(feature = "futures_api", since = "1.36.0")]
134 #[rustc_allow_const_fn_unstable(const_fn_fn_ptr_basics)]
136 clone: unsafe fn(*const ()) -> RawWaker,
137 wake: unsafe fn(*const ()),
138 wake_by_ref: unsafe fn(*const ()),
139 drop: unsafe fn(*const ()),
141 Self { clone, wake, wake_by_ref, drop }
145 /// The `Context` of an asynchronous task.
147 /// Currently, `Context` only serves to provide access to a `&Waker`
148 /// which can be used to wake the current task.
149 #[stable(feature = "futures_api", since = "1.36.0")]
150 pub struct Context<'a> {
152 // Ensure we future-proof against variance changes by forcing
153 // the lifetime to be invariant (argument-position lifetimes
154 // are contravariant while return-position lifetimes are
156 _marker: PhantomData<fn(&'a ()) -> &'a ()>,
159 impl<'a> Context<'a> {
160 /// Create a new `Context` from a `&Waker`.
161 #[stable(feature = "futures_api", since = "1.36.0")]
164 pub fn from_waker(waker: &'a Waker) -> Self {
165 Context { waker, _marker: PhantomData }
168 /// Returns a reference to the `Waker` for the current task.
169 #[stable(feature = "futures_api", since = "1.36.0")]
172 pub fn waker(&self) -> &'a Waker {
177 #[stable(feature = "futures_api", since = "1.36.0")]
178 impl fmt::Debug for Context<'_> {
179 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
180 f.debug_struct("Context").field("waker", &self.waker).finish()
184 /// A `Waker` is a handle for waking up a task by notifying its executor that it
185 /// is ready to be run.
187 /// This handle encapsulates a [`RawWaker`] instance, which defines the
188 /// executor-specific wakeup behavior.
190 /// Implements [`Clone`], [`Send`], and [`Sync`].
192 #[stable(feature = "futures_api", since = "1.36.0")]
197 #[stable(feature = "futures_api", since = "1.36.0")]
198 impl Unpin for Waker {}
199 #[stable(feature = "futures_api", since = "1.36.0")]
200 unsafe impl Send for Waker {}
201 #[stable(feature = "futures_api", since = "1.36.0")]
202 unsafe impl Sync for Waker {}
205 /// Wake up the task associated with this `Waker`.
207 #[stable(feature = "futures_api", since = "1.36.0")]
209 // The actual wakeup call is delegated through a virtual function call
210 // to the implementation which is defined by the executor.
211 let wake = self.waker.vtable.wake;
212 let data = self.waker.data;
214 // Don't call `drop` -- the waker will be consumed by `wake`.
215 crate::mem::forget(self);
217 // SAFETY: This is safe because `Waker::from_raw` is the only way
218 // to initialize `wake` and `data` requiring the user to acknowledge
219 // that the contract of `RawWaker` is upheld.
220 unsafe { (wake)(data) };
223 /// Wake up the task associated with this `Waker` without consuming the `Waker`.
225 /// This is similar to `wake`, but may be slightly less efficient in the case
226 /// where an owned `Waker` is available. This method should be preferred to
227 /// calling `waker.clone().wake()`.
229 #[stable(feature = "futures_api", since = "1.36.0")]
230 pub fn wake_by_ref(&self) {
231 // The actual wakeup call is delegated through a virtual function call
232 // to the implementation which is defined by the executor.
234 // SAFETY: see `wake`
235 unsafe { (self.waker.vtable.wake_by_ref)(self.waker.data) }
238 /// Returns `true` if this `Waker` and another `Waker` have awoken the same task.
240 /// This function works on a best-effort basis, and may return false even
241 /// when the `Waker`s would awaken the same task. However, if this function
242 /// returns `true`, it is guaranteed that the `Waker`s will awaken the same task.
244 /// This function is primarily used for optimization purposes.
247 #[stable(feature = "futures_api", since = "1.36.0")]
248 pub fn will_wake(&self, other: &Waker) -> bool {
249 self.waker == other.waker
252 /// Creates a new `Waker` from [`RawWaker`].
254 /// The behavior of the returned `Waker` is undefined if the contract defined
255 /// in [`RawWaker`]'s and [`RawWakerVTable`]'s documentation is not upheld.
256 /// Therefore this method is unsafe.
259 #[stable(feature = "futures_api", since = "1.36.0")]
260 pub unsafe fn from_raw(waker: RawWaker) -> Waker {
265 #[stable(feature = "futures_api", since = "1.36.0")]
266 impl Clone for Waker {
268 fn clone(&self) -> Self {
270 // SAFETY: This is safe because `Waker::from_raw` is the only way
271 // to initialize `clone` and `data` requiring the user to acknowledge
272 // that the contract of [`RawWaker`] is upheld.
273 waker: unsafe { (self.waker.vtable.clone)(self.waker.data) },
278 #[stable(feature = "futures_api", since = "1.36.0")]
279 impl Drop for Waker {
282 // SAFETY: This is safe because `Waker::from_raw` is the only way
283 // to initialize `drop` and `data` requiring the user to acknowledge
284 // that the contract of `RawWaker` is upheld.
285 unsafe { (self.waker.vtable.drop)(self.waker.data) }
289 #[stable(feature = "futures_api", since = "1.36.0")]
290 impl fmt::Debug for Waker {
291 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
292 let vtable_ptr = self.waker.vtable as *const RawWakerVTable;
293 f.debug_struct("Waker")
294 .field("data", &self.waker.data)
295 .field("vtable", &vtable_ptr)