1 | #![stable(feature = "futures_api", since = "1.36.0")] |
---|---|
2 | |
3 | use crate::any::Any; |
4 | use crate::marker::PhantomData; |
5 | use crate::mem::{ManuallyDrop, transmute}; |
6 | use crate::panic::AssertUnwindSafe; |
7 | use crate::{fmt, ptr}; |
8 | |
9 | /// A `RawWaker` allows the implementor of a task executor to create a [`Waker`] |
10 | /// or a [`LocalWaker`] which provides customized wakeup behavior. |
11 | /// |
12 | /// It consists of a data pointer and a [virtual function pointer table (vtable)][vtable] |
13 | /// that customizes the behavior of the `RawWaker`. |
14 | /// |
15 | /// `RawWaker`s are unsafe to use. |
16 | /// Implementing the [`Wake`] trait is a safe alternative that requires memory allocation. |
17 | /// |
18 | /// [vtable]: https://en.wikipedia.org/wiki/Virtual_method_table |
19 | /// [`Wake`]: ../../alloc/task/trait.Wake.html |
20 | #[derive(PartialEq, Debug)] |
21 | #[stable(feature = "futures_api", since = "1.36.0")] |
22 | pub struct RawWaker { |
23 | /// A data pointer, which can be used to store arbitrary data as required |
24 | /// by the executor. This could be e.g. a type-erased pointer to an `Arc` |
25 | /// that is associated with the task. |
26 | /// The value of this field gets passed to all functions that are part of |
27 | /// the vtable as the first parameter. |
28 | data: *const (), |
29 | /// Virtual function pointer table that customizes the behavior of this waker. |
30 | vtable: &'static RawWakerVTable, |
31 | } |
32 | |
33 | impl RawWaker { |
34 | /// Creates a new `RawWaker` from the provided `data` pointer and `vtable`. |
35 | /// |
36 | /// The `data` pointer can be used to store arbitrary data as required |
37 | /// by the executor. This could be e.g. a type-erased pointer to an `Arc` |
38 | /// that is associated with the task. |
39 | /// The value of this pointer will get passed to all functions that are part |
40 | /// of the `vtable` as the first parameter. |
41 | /// |
42 | /// It is important to consider that the `data` pointer must point to a |
43 | /// thread safe type such as an `Arc<T: Send + Sync>` |
44 | /// when used to construct a [`Waker`]. This restriction is lifted when |
45 | /// constructing a [`LocalWaker`], which allows using types that do not implement |
46 | /// <code>[Send] + [Sync]</code> like `Rc<T>`. |
47 | /// |
48 | /// The `vtable` customizes the behavior of a `Waker` which gets created |
49 | /// from a `RawWaker`. For each operation on the `Waker`, the associated |
50 | /// function in the `vtable` of the underlying `RawWaker` will be called. |
51 | #[inline] |
52 | #[rustc_promotable] |
53 | #[stable(feature = "futures_api", since = "1.36.0")] |
54 | #[rustc_const_stable(feature = "futures_api", since = "1.36.0")] |
55 | #[must_use] |
56 | pub const fn new(data: *const (), vtable: &'static RawWakerVTable) -> RawWaker { |
57 | RawWaker { data, vtable } |
58 | } |
59 | |
60 | #[stable(feature = "noop_waker", since = "1.85.0")] |
61 | const NOOP: RawWaker = { |
62 | const VTABLE: RawWakerVTable = RawWakerVTable::new( |
63 | // Cloning just returns a new no-op raw waker |
64 | |_| RawWaker::NOOP, |
65 | // `wake` does nothing |
66 | |_| {}, |
67 | // `wake_by_ref` does nothing |
68 | |_| {}, |
69 | // Dropping does nothing as we don't allocate anything |
70 | |_| {}, |
71 | ); |
72 | RawWaker::new(ptr::null(), &VTABLE) |
73 | }; |
74 | } |
75 | |
76 | /// A virtual function pointer table (vtable) that specifies the behavior |
77 | /// of a [`RawWaker`]. |
78 | /// |
79 | /// The pointer passed to all functions inside the vtable is the `data` pointer |
80 | /// from the enclosing [`RawWaker`] object. |
81 | /// |
82 | /// The functions inside this struct are only intended to be called on the `data` |
83 | /// pointer of a properly constructed [`RawWaker`] object from inside the |
84 | /// [`RawWaker`] implementation. Calling one of the contained functions using |
85 | /// any other `data` pointer will cause undefined behavior. |
86 | /// |
87 | /// Note that while this type implements `PartialEq`, comparing function pointers, and hence |
88 | /// comparing structs like this that contain function pointers, is unreliable: pointers to the same |
89 | /// function can compare inequal (because functions are duplicated in multiple codegen units), and |
90 | /// pointers to *different* functions can compare equal (since identical functions can be |
91 | /// deduplicated within a codegen unit). |
92 | /// |
93 | /// # Thread safety |
94 | /// If the [`RawWaker`] will be used to construct a [`Waker`] then |
95 | /// these functions must all be thread-safe (even though [`RawWaker`] is |
96 | /// <code>\![Send] + \![Sync]</code>). This is because [`Waker`] is <code>[Send] + [Sync]</code>, |
97 | /// and it may be moved to arbitrary threads or invoked by `&` reference. For example, |
98 | /// this means that if the `clone` and `drop` functions manage a reference count, |
99 | /// they must do so atomically. |
100 | /// |
101 | /// However, if the [`RawWaker`] will be used to construct a [`LocalWaker`] instead, then |
102 | /// these functions don't need to be thread safe. This means that <code>\![Send] + \![Sync]</code> |
103 | /// data can be stored in the data pointer, and reference counting does not need any atomic |
104 | /// synchronization. This is because [`LocalWaker`] is not thread safe itself, so it cannot |
105 | /// be sent across threads. |
106 | #[stable(feature = "futures_api", since = "1.36.0")] |
107 | #[derive(PartialEq, Copy, Clone, Debug)] |
108 | pub struct RawWakerVTable { |
109 | /// This function will be called when the [`RawWaker`] gets cloned, e.g. when |
110 | /// the [`Waker`] in which the [`RawWaker`] is stored gets cloned. |
111 | /// |
112 | /// The implementation of this function must retain all resources that are |
113 | /// required for this additional instance of a [`RawWaker`] and associated |
114 | /// task. Calling `wake` on the resulting [`RawWaker`] should result in a wakeup |
115 | /// of the same task that would have been awoken by the original [`RawWaker`]. |
116 | clone: unsafe fn(*const ()) -> RawWaker, |
117 | |
118 | /// This function will be called when `wake` is called on the [`Waker`]. |
119 | /// It must wake up the task associated with this [`RawWaker`]. |
120 | /// |
121 | /// The implementation of this function must make sure to release any |
122 | /// resources that are associated with this instance of a [`RawWaker`] and |
123 | /// associated task. |
124 | wake: unsafe fn(*const ()), |
125 | |
126 | /// This function will be called when `wake_by_ref` is called on the [`Waker`]. |
127 | /// It must wake up the task associated with this [`RawWaker`]. |
128 | /// |
129 | /// This function is similar to `wake`, but must not consume the provided data |
130 | /// pointer. |
131 | wake_by_ref: unsafe fn(*const ()), |
132 | |
133 | /// This function will be called when a [`Waker`] gets dropped. |
134 | /// |
135 | /// The implementation of this function must make sure to release any |
136 | /// resources that are associated with this instance of a [`RawWaker`] and |
137 | /// associated task. |
138 | drop: unsafe fn(*const ()), |
139 | } |
140 | |
141 | impl RawWakerVTable { |
142 | /// Creates a new `RawWakerVTable` from the provided `clone`, `wake`, |
143 | /// `wake_by_ref`, and `drop` functions. |
144 | /// |
145 | /// If the [`RawWaker`] will be used to construct a [`Waker`] then |
146 | /// these functions must all be thread-safe (even though [`RawWaker`] is |
147 | /// <code>\![Send] + \![Sync]</code>). This is because [`Waker`] is <code>[Send] + [Sync]</code>, |
148 | /// and it may be moved to arbitrary threads or invoked by `&` reference. For example, |
149 | /// this means that if the `clone` and `drop` functions manage a reference count, |
150 | /// they must do so atomically. |
151 | /// |
152 | /// However, if the [`RawWaker`] will be used to construct a [`LocalWaker`] instead, then |
153 | /// these functions don't need to be thread safe. This means that <code>\![Send] + \![Sync]</code> |
154 | /// data can be stored in the data pointer, and reference counting does not need any atomic |
155 | /// synchronization. This is because [`LocalWaker`] is not thread safe itself, so it cannot |
156 | /// be sent across threads. |
157 | /// # `clone` |
158 | /// |
159 | /// This function will be called when the [`RawWaker`] gets cloned, e.g. when |
160 | /// the [`Waker`]/[`LocalWaker`] in which the [`RawWaker`] is stored gets cloned. |
161 | /// |
162 | /// The implementation of this function must retain all resources that are |
163 | /// required for this additional instance of a [`RawWaker`] and associated |
164 | /// task. Calling `wake` on the resulting [`RawWaker`] should result in a wakeup |
165 | /// of the same task that would have been awoken by the original [`RawWaker`]. |
166 | /// |
167 | /// # `wake` |
168 | /// |
169 | /// This function will be called when `wake` is called on the [`Waker`]. |
170 | /// It must wake up the task associated with this [`RawWaker`]. |
171 | /// |
172 | /// The implementation of this function must make sure to release any |
173 | /// resources that are associated with this instance of a [`RawWaker`] and |
174 | /// associated task. |
175 | /// |
176 | /// # `wake_by_ref` |
177 | /// |
178 | /// This function will be called when `wake_by_ref` is called on the [`Waker`]. |
179 | /// It must wake up the task associated with this [`RawWaker`]. |
180 | /// |
181 | /// This function is similar to `wake`, but must not consume the provided data |
182 | /// pointer. |
183 | /// |
184 | /// # `drop` |
185 | /// |
186 | /// This function will be called when a [`Waker`]/[`LocalWaker`] gets |
187 | /// dropped. |
188 | /// |
189 | /// The implementation of this function must make sure to release any |
190 | /// resources that are associated with this instance of a [`RawWaker`] and |
191 | /// associated task. |
192 | #[rustc_promotable] |
193 | #[stable(feature = "futures_api", since = "1.36.0")] |
194 | #[rustc_const_stable(feature = "futures_api", since = "1.36.0")] |
195 | pub const fn new( |
196 | clone: unsafe fn(*const ()) -> RawWaker, |
197 | wake: unsafe fn(*const ()), |
198 | wake_by_ref: unsafe fn(*const ()), |
199 | drop: unsafe fn(*const ()), |
200 | ) -> Self { |
201 | Self { clone, wake, wake_by_ref, drop } |
202 | } |
203 | } |
204 | |
205 | #[derive(Debug)] |
206 | enum ExtData<'a> { |
207 | Some(&'a mut dyn Any), |
208 | None(()), |
209 | } |
210 | |
211 | /// The context of an asynchronous task. |
212 | /// |
213 | /// Currently, `Context` only serves to provide access to a [`&Waker`](Waker) |
214 | /// which can be used to wake the current task. |
215 | #[stable(feature = "futures_api", since = "1.36.0")] |
216 | #[lang= "Context"] |
217 | pub struct Context<'a> { |
218 | waker: &'a Waker, |
219 | local_waker: &'a LocalWaker, |
220 | ext: AssertUnwindSafe<ExtData<'a>>, |
221 | // Ensure we future-proof against variance changes by forcing |
222 | // the lifetime to be invariant (argument-position lifetimes |
223 | // are contravariant while return-position lifetimes are |
224 | // covariant). |
225 | _marker: PhantomData<fn(&'a ()) -> &'a ()>, |
226 | // Ensure `Context` is `!Send` and `!Sync` in order to allow |
227 | // for future `!Send` and / or `!Sync` fields. |
228 | _marker2: PhantomData<*mut ()>, |
229 | } |
230 | |
231 | impl<'a> Context<'a> { |
232 | /// Creates a new `Context` from a [`&Waker`](Waker). |
233 | #[stable(feature = "futures_api", since = "1.36.0")] |
234 | #[rustc_const_stable(feature = "const_waker", since = "1.82.0")] |
235 | #[must_use] |
236 | #[inline] |
237 | pub const fn from_waker(waker: &'a Waker) -> Self { |
238 | ContextBuilder::from_waker(waker).build() |
239 | } |
240 | |
241 | /// Returns a reference to the [`Waker`] for the current task. |
242 | #[inline] |
243 | #[must_use] |
244 | #[stable(feature = "futures_api", since = "1.36.0")] |
245 | #[rustc_const_stable(feature = "const_waker", since = "1.82.0")] |
246 | pub const fn waker(&self) -> &'a Waker { |
247 | &self.waker |
248 | } |
249 | |
250 | /// Returns a reference to the [`LocalWaker`] for the current task. |
251 | #[inline] |
252 | #[unstable(feature = "local_waker", issue = "118959")] |
253 | pub const fn local_waker(&self) -> &'a LocalWaker { |
254 | &self.local_waker |
255 | } |
256 | |
257 | /// Returns a reference to the extension data for the current task. |
258 | #[inline] |
259 | #[unstable(feature = "context_ext", issue = "123392")] |
260 | pub const fn ext(&mut self) -> &mut dyn Any { |
261 | // FIXME: this field makes Context extra-weird about unwind safety |
262 | // can we justify AssertUnwindSafe if we stabilize this? do we care? |
263 | match &mut self.ext.0 { |
264 | ExtData::Some(data) => *data, |
265 | ExtData::None(unit) => unit, |
266 | } |
267 | } |
268 | } |
269 | |
270 | #[stable(feature = "futures_api", since = "1.36.0")] |
271 | impl fmt::Debug for Context<'_> { |
272 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
273 | f.debug_struct("Context").field(name: "waker", &self.waker).finish() |
274 | } |
275 | } |
276 | |
277 | /// A Builder used to construct a `Context` instance |
278 | /// with support for `LocalWaker`. |
279 | /// |
280 | /// # Examples |
281 | /// ``` |
282 | /// #![feature(local_waker)] |
283 | /// use std::task::{ContextBuilder, LocalWaker, Waker, Poll}; |
284 | /// use std::future::Future; |
285 | /// |
286 | /// let local_waker = LocalWaker::noop(); |
287 | /// let waker = Waker::noop(); |
288 | /// |
289 | /// let mut cx = ContextBuilder::from_waker(&waker) |
290 | /// .local_waker(&local_waker) |
291 | /// .build(); |
292 | /// |
293 | /// let mut future = std::pin::pin!(async { 20 }); |
294 | /// let poll = future.as_mut().poll(&mut cx); |
295 | /// assert_eq!(poll, Poll::Ready(20)); |
296 | /// |
297 | /// ``` |
298 | #[unstable(feature = "local_waker", issue = "118959")] |
299 | #[derive(Debug)] |
300 | pub struct ContextBuilder<'a> { |
301 | waker: &'a Waker, |
302 | local_waker: &'a LocalWaker, |
303 | ext: ExtData<'a>, |
304 | // Ensure we future-proof against variance changes by forcing |
305 | // the lifetime to be invariant (argument-position lifetimes |
306 | // are contravariant while return-position lifetimes are |
307 | // covariant). |
308 | _marker: PhantomData<fn(&'a ()) -> &'a ()>, |
309 | // Ensure `Context` is `!Send` and `!Sync` in order to allow |
310 | // for future `!Send` and / or `!Sync` fields. |
311 | _marker2: PhantomData<*mut ()>, |
312 | } |
313 | |
314 | impl<'a> ContextBuilder<'a> { |
315 | /// Creates a ContextBuilder from a Waker. |
316 | #[inline] |
317 | #[unstable(feature = "local_waker", issue = "118959")] |
318 | pub const fn from_waker(waker: &'a Waker) -> Self { |
319 | // SAFETY: LocalWaker is just Waker without thread safety |
320 | let local_waker = unsafe { transmute(waker) }; |
321 | Self { |
322 | waker, |
323 | local_waker, |
324 | ext: ExtData::None(()), |
325 | _marker: PhantomData, |
326 | _marker2: PhantomData, |
327 | } |
328 | } |
329 | |
330 | /// Creates a ContextBuilder from an existing Context. |
331 | #[inline] |
332 | #[unstable(feature = "context_ext", issue = "123392")] |
333 | pub const fn from(cx: &'a mut Context<'_>) -> Self { |
334 | let ext = match &mut cx.ext.0 { |
335 | ExtData::Some(ext) => ExtData::Some(*ext), |
336 | ExtData::None(()) => ExtData::None(()), |
337 | }; |
338 | Self { |
339 | waker: cx.waker, |
340 | local_waker: cx.local_waker, |
341 | ext, |
342 | _marker: PhantomData, |
343 | _marker2: PhantomData, |
344 | } |
345 | } |
346 | |
347 | /// Sets the value for the waker on `Context`. |
348 | #[inline] |
349 | #[unstable(feature = "context_ext", issue = "123392")] |
350 | pub const fn waker(self, waker: &'a Waker) -> Self { |
351 | Self { waker, ..self } |
352 | } |
353 | |
354 | /// Sets the value for the local waker on `Context`. |
355 | #[inline] |
356 | #[unstable(feature = "local_waker", issue = "118959")] |
357 | pub const fn local_waker(self, local_waker: &'a LocalWaker) -> Self { |
358 | Self { local_waker, ..self } |
359 | } |
360 | |
361 | /// Sets the value for the extension data on `Context`. |
362 | #[inline] |
363 | #[unstable(feature = "context_ext", issue = "123392")] |
364 | pub const fn ext(self, data: &'a mut dyn Any) -> Self { |
365 | Self { ext: ExtData::Some(data), ..self } |
366 | } |
367 | |
368 | /// Builds the `Context`. |
369 | #[inline] |
370 | #[unstable(feature = "local_waker", issue = "118959")] |
371 | pub const fn build(self) -> Context<'a> { |
372 | let ContextBuilder { waker, local_waker, ext, _marker, _marker2 } = self; |
373 | Context { waker, local_waker, ext: AssertUnwindSafe(ext), _marker, _marker2 } |
374 | } |
375 | } |
376 | |
377 | /// A `Waker` is a handle for waking up a task by notifying its executor that it |
378 | /// is ready to be run. |
379 | /// |
380 | /// This handle encapsulates a [`RawWaker`] instance, which defines the |
381 | /// executor-specific wakeup behavior. |
382 | /// |
383 | /// The typical life of a `Waker` is that it is constructed by an executor, wrapped in a |
384 | /// [`Context`], then passed to [`Future::poll()`]. Then, if the future chooses to return |
385 | /// [`Poll::Pending`], it must also store the waker somehow and call [`Waker::wake()`] when |
386 | /// the future should be polled again. |
387 | /// |
388 | /// Implements [`Clone`], [`Send`], and [`Sync`]; therefore, a waker may be invoked |
389 | /// from any thread, including ones not in any way managed by the executor. For example, |
390 | /// this might be done to wake a future when a blocking function call completes on another |
391 | /// thread. |
392 | /// |
393 | /// Note that it is preferable to use `waker.clone_from(&new_waker)` instead |
394 | /// of `*waker = new_waker.clone()`, as the former will avoid cloning the waker |
395 | /// unnecessarily if the two wakers [wake the same task](Self::will_wake). |
396 | /// |
397 | /// Constructing a `Waker` from a [`RawWaker`] is unsafe. |
398 | /// Implementing the [`Wake`] trait is a safe alternative that requires memory allocation. |
399 | /// |
400 | /// [`Future::poll()`]: core::future::Future::poll |
401 | /// [`Poll::Pending`]: core::task::Poll::Pending |
402 | /// [`Wake`]: ../../alloc/task/trait.Wake.html |
403 | #[repr(transparent)] |
404 | #[stable(feature = "futures_api", since = "1.36.0")] |
405 | #[rustc_diagnostic_item= "Waker"] |
406 | pub struct Waker { |
407 | waker: RawWaker, |
408 | } |
409 | |
410 | #[stable(feature = "futures_api", since = "1.36.0")] |
411 | impl Unpin for Waker {} |
412 | #[stable(feature = "futures_api", since = "1.36.0")] |
413 | unsafe impl Send for Waker {} |
414 | #[stable(feature = "futures_api", since = "1.36.0")] |
415 | unsafe impl Sync for Waker {} |
416 | |
417 | impl Waker { |
418 | /// Wakes up the task associated with this `Waker`. |
419 | /// |
420 | /// As long as the executor keeps running and the task is not finished, it is |
421 | /// guaranteed that each invocation of [`wake()`](Self::wake) (or |
422 | /// [`wake_by_ref()`](Self::wake_by_ref)) will be followed by at least one |
423 | /// [`poll()`] of the task to which this `Waker` belongs. This makes |
424 | /// it possible to temporarily yield to other tasks while running potentially |
425 | /// unbounded processing loops. |
426 | /// |
427 | /// Note that the above implies that multiple wake-ups may be coalesced into a |
428 | /// single [`poll()`] invocation by the runtime. |
429 | /// |
430 | /// Also note that yielding to competing tasks is not guaranteed: it is the |
431 | /// executor’s choice which task to run and the executor may choose to run the |
432 | /// current task again. |
433 | /// |
434 | /// [`poll()`]: crate::future::Future::poll |
435 | #[inline] |
436 | #[stable(feature = "futures_api", since = "1.36.0")] |
437 | pub fn wake(self) { |
438 | // The actual wakeup call is delegated through a virtual function call |
439 | // to the implementation which is defined by the executor. |
440 | |
441 | // Don't call `drop` -- the waker will be consumed by `wake`. |
442 | let this = ManuallyDrop::new(self); |
443 | |
444 | // SAFETY: This is safe because `Waker::from_raw` is the only way |
445 | // to initialize `wake` and `data` requiring the user to acknowledge |
446 | // that the contract of `RawWaker` is upheld. |
447 | unsafe { (this.waker.vtable.wake)(this.waker.data) }; |
448 | } |
449 | |
450 | /// Wakes up the task associated with this `Waker` without consuming the `Waker`. |
451 | /// |
452 | /// This is similar to [`wake()`](Self::wake), but may be slightly less efficient in |
453 | /// the case where an owned `Waker` is available. This method should be preferred to |
454 | /// calling `waker.clone().wake()`. |
455 | #[inline] |
456 | #[stable(feature = "futures_api", since = "1.36.0")] |
457 | pub fn wake_by_ref(&self) { |
458 | // The actual wakeup call is delegated through a virtual function call |
459 | // to the implementation which is defined by the executor. |
460 | |
461 | // SAFETY: see `wake` |
462 | unsafe { (self.waker.vtable.wake_by_ref)(self.waker.data) } |
463 | } |
464 | |
465 | /// Returns `true` if this `Waker` and another `Waker` would awake the same task. |
466 | /// |
467 | /// This function works on a best-effort basis, and may return false even |
468 | /// when the `Waker`s would awaken the same task. However, if this function |
469 | /// returns `true`, it is guaranteed that the `Waker`s will awaken the same task. |
470 | /// |
471 | /// This function is primarily used for optimization purposes — for example, |
472 | /// this type's [`clone_from`](Self::clone_from) implementation uses it to |
473 | /// avoid cloning the waker when they would wake the same task anyway. |
474 | #[inline] |
475 | #[must_use] |
476 | #[stable(feature = "futures_api", since = "1.36.0")] |
477 | pub fn will_wake(&self, other: &Waker) -> bool { |
478 | // We optimize this by comparing vtable addresses instead of vtable contents. |
479 | // This is permitted since the function is documented as best-effort. |
480 | let RawWaker { data: a_data, vtable: a_vtable } = self.waker; |
481 | let RawWaker { data: b_data, vtable: b_vtable } = other.waker; |
482 | a_data == b_data && ptr::eq(a_vtable, b_vtable) |
483 | } |
484 | |
485 | /// Creates a new `Waker` from the provided `data` pointer and `vtable`. |
486 | /// |
487 | /// The `data` pointer can be used to store arbitrary data as required |
488 | /// by the executor. This could be e.g. a type-erased pointer to an `Arc` |
489 | /// that is associated with the task. |
490 | /// The value of this pointer will get passed to all functions that are part |
491 | /// of the `vtable` as the first parameter. |
492 | /// |
493 | /// It is important to consider that the `data` pointer must point to a |
494 | /// thread safe type such as an `Arc`. |
495 | /// |
496 | /// The `vtable` customizes the behavior of a `Waker`. For each operation |
497 | /// on the `Waker`, the associated function in the `vtable` will be called. |
498 | /// |
499 | /// # Safety |
500 | /// |
501 | /// The behavior of the returned `Waker` is undefined if the contract defined |
502 | /// in [`RawWakerVTable`]'s documentation is not upheld. |
503 | /// |
504 | /// (Authors wishing to avoid unsafe code may implement the [`Wake`] trait instead, at the |
505 | /// cost of a required heap allocation.) |
506 | /// |
507 | /// [`Wake`]: ../../alloc/task/trait.Wake.html |
508 | #[inline] |
509 | #[must_use] |
510 | #[stable(feature = "waker_getters", since = "1.83.0")] |
511 | #[rustc_const_stable(feature = "waker_getters", since = "1.83.0")] |
512 | pub const unsafe fn new(data: *const (), vtable: &'static RawWakerVTable) -> Self { |
513 | Waker { waker: RawWaker { data, vtable } } |
514 | } |
515 | |
516 | /// Creates a new `Waker` from [`RawWaker`]. |
517 | /// |
518 | /// # Safety |
519 | /// |
520 | /// The behavior of the returned `Waker` is undefined if the contract defined |
521 | /// in [`RawWaker`]'s and [`RawWakerVTable`]'s documentation is not upheld. |
522 | /// |
523 | /// (Authors wishing to avoid unsafe code may implement the [`Wake`] trait instead, at the |
524 | /// cost of a required heap allocation.) |
525 | /// |
526 | /// [`Wake`]: ../../alloc/task/trait.Wake.html |
527 | #[inline] |
528 | #[must_use] |
529 | #[stable(feature = "futures_api", since = "1.36.0")] |
530 | #[rustc_const_stable(feature = "const_waker", since = "1.82.0")] |
531 | pub const unsafe fn from_raw(waker: RawWaker) -> Waker { |
532 | Waker { waker } |
533 | } |
534 | |
535 | /// Returns a reference to a `Waker` that does nothing when used. |
536 | /// |
537 | // Note! Much of the documentation for this method is duplicated |
538 | // in the docs for `LocalWaker::noop`. |
539 | // If you edit it, consider editing the other copy too. |
540 | // |
541 | /// This is mostly useful for writing tests that need a [`Context`] to poll |
542 | /// some futures, but are not expecting those futures to wake the waker or |
543 | /// do not need to do anything specific if it happens. |
544 | /// |
545 | /// More generally, using `Waker::noop()` to poll a future |
546 | /// means discarding the notification of when the future should be polled again. |
547 | /// So it should only be used when such a notification will not be needed to make progress. |
548 | /// |
549 | /// If an owned `Waker` is needed, `clone()` this one. |
550 | /// |
551 | /// # Examples |
552 | /// |
553 | /// ``` |
554 | /// use std::future::Future; |
555 | /// use std::task; |
556 | /// |
557 | /// let mut cx = task::Context::from_waker(task::Waker::noop()); |
558 | /// |
559 | /// let mut future = Box::pin(async { 10 }); |
560 | /// assert_eq!(future.as_mut().poll(&mut cx), task::Poll::Ready(10)); |
561 | /// ``` |
562 | #[inline] |
563 | #[must_use] |
564 | #[stable(feature = "noop_waker", since = "1.85.0")] |
565 | #[rustc_const_stable(feature = "noop_waker", since = "1.85.0")] |
566 | pub const fn noop() -> &'static Waker { |
567 | const WAKER: &Waker = &Waker { waker: RawWaker::NOOP }; |
568 | WAKER |
569 | } |
570 | |
571 | /// Gets the `data` pointer used to create this `Waker`. |
572 | #[inline] |
573 | #[must_use] |
574 | #[stable(feature = "waker_getters", since = "1.83.0")] |
575 | pub fn data(&self) -> *const () { |
576 | self.waker.data |
577 | } |
578 | |
579 | /// Gets the `vtable` pointer used to create this `Waker`. |
580 | #[inline] |
581 | #[must_use] |
582 | #[stable(feature = "waker_getters", since = "1.83.0")] |
583 | pub fn vtable(&self) -> &'static RawWakerVTable { |
584 | self.waker.vtable |
585 | } |
586 | } |
587 | |
588 | #[stable(feature = "futures_api", since = "1.36.0")] |
589 | impl Clone for Waker { |
590 | #[inline] |
591 | fn clone(&self) -> Self { |
592 | Waker { |
593 | // SAFETY: This is safe because `Waker::from_raw` is the only way |
594 | // to initialize `clone` and `data` requiring the user to acknowledge |
595 | // that the contract of [`RawWaker`] is upheld. |
596 | waker: unsafe { (self.waker.vtable.clone)(self.waker.data) }, |
597 | } |
598 | } |
599 | |
600 | /// Assigns a clone of `source` to `self`, unless [`self.will_wake(source)`][Waker::will_wake] anyway. |
601 | /// |
602 | /// This method is preferred over simply assigning `source.clone()` to `self`, |
603 | /// as it avoids cloning the waker if `self` is already the same waker. |
604 | /// |
605 | /// # Examples |
606 | /// |
607 | /// ``` |
608 | /// use std::future::Future; |
609 | /// use std::pin::Pin; |
610 | /// use std::sync::{Arc, Mutex}; |
611 | /// use std::task::{Context, Poll, Waker}; |
612 | /// |
613 | /// struct Waiter { |
614 | /// shared: Arc<Mutex<Shared>>, |
615 | /// } |
616 | /// |
617 | /// struct Shared { |
618 | /// waker: Waker, |
619 | /// // ... |
620 | /// } |
621 | /// |
622 | /// impl Future for Waiter { |
623 | /// type Output = (); |
624 | /// fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> { |
625 | /// let mut shared = self.shared.lock().unwrap(); |
626 | /// |
627 | /// // update the waker |
628 | /// shared.waker.clone_from(cx.waker()); |
629 | /// |
630 | /// // readiness logic ... |
631 | /// # Poll::Ready(()) |
632 | /// } |
633 | /// } |
634 | /// |
635 | /// ``` |
636 | #[inline] |
637 | fn clone_from(&mut self, source: &Self) { |
638 | if !self.will_wake(source) { |
639 | *self = source.clone(); |
640 | } |
641 | } |
642 | } |
643 | |
644 | #[stable(feature = "futures_api", since = "1.36.0")] |
645 | impl Drop for Waker { |
646 | #[inline] |
647 | fn drop(&mut self) { |
648 | // SAFETY: This is safe because `Waker::from_raw` is the only way |
649 | // to initialize `drop` and `data` requiring the user to acknowledge |
650 | // that the contract of `RawWaker` is upheld. |
651 | unsafe { (self.waker.vtable.drop)(self.waker.data) } |
652 | } |
653 | } |
654 | |
655 | #[stable(feature = "futures_api", since = "1.36.0")] |
656 | impl fmt::Debug for Waker { |
657 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
658 | let vtable_ptr: *const RawWakerVTable = self.waker.vtable as *const RawWakerVTable; |
659 | f&mut DebugStruct<'_, '_>.debug_struct("Waker") |
660 | .field("data", &self.waker.data) |
661 | .field(name:"vtable", &vtable_ptr) |
662 | .finish() |
663 | } |
664 | } |
665 | |
666 | /// A `LocalWaker` is analogous to a [`Waker`], but it does not implement [`Send`] or [`Sync`]. |
667 | /// |
668 | /// This handle encapsulates a [`RawWaker`] instance, which defines the |
669 | /// executor-specific wakeup behavior. |
670 | /// |
671 | /// Local wakers can be requested from a `Context` with the [`local_waker`] method. |
672 | /// |
673 | /// The typical life of a `LocalWaker` is that it is constructed by an executor, wrapped in a |
674 | /// [`Context`] using [`ContextBuilder`], then passed to [`Future::poll()`]. Then, if the future chooses to return |
675 | /// [`Poll::Pending`], it must also store the waker somehow and call [`LocalWaker::wake()`] when |
676 | /// the future should be polled again. |
677 | /// |
678 | /// Implements [`Clone`], but neither [`Send`] nor [`Sync`]; therefore, a local waker may |
679 | /// not be moved to other threads. In general, when deciding to use wakers or local wakers, |
680 | /// local wakers are preferable unless the waker needs to be sent across threads. This is because |
681 | /// wakers can incur in additional cost related to memory synchronization. |
682 | /// |
683 | /// Note that it is preferable to use `local_waker.clone_from(&new_waker)` instead |
684 | /// of `*local_waker = new_waker.clone()`, as the former will avoid cloning the waker |
685 | /// unnecessarily if the two wakers [wake the same task](Self::will_wake). |
686 | /// |
687 | /// # Examples |
688 | /// Usage of a local waker to implement a future analogous to `std::thread::yield_now()`. |
689 | /// ``` |
690 | /// #![feature(local_waker)] |
691 | /// use std::future::{Future, poll_fn}; |
692 | /// use std::task::Poll; |
693 | /// |
694 | /// // a future that returns pending once. |
695 | /// fn yield_now() -> impl Future<Output=()> + Unpin { |
696 | /// let mut yielded = false; |
697 | /// poll_fn(move |cx| { |
698 | /// if !yielded { |
699 | /// yielded = true; |
700 | /// cx.local_waker().wake_by_ref(); |
701 | /// return Poll::Pending; |
702 | /// } |
703 | /// return Poll::Ready(()) |
704 | /// }) |
705 | /// } |
706 | /// |
707 | /// # async fn __() { |
708 | /// yield_now().await; |
709 | /// # } |
710 | /// ``` |
711 | /// |
712 | /// [`Future::poll()`]: core::future::Future::poll |
713 | /// [`Poll::Pending`]: core::task::Poll::Pending |
714 | /// [`local_waker`]: core::task::Context::local_waker |
715 | #[unstable(feature = "local_waker", issue = "118959")] |
716 | #[repr(transparent)] |
717 | pub struct LocalWaker { |
718 | waker: RawWaker, |
719 | } |
720 | |
721 | #[unstable(feature = "local_waker", issue = "118959")] |
722 | impl Unpin for LocalWaker {} |
723 | |
724 | impl LocalWaker { |
725 | /// Wakes up the task associated with this `LocalWaker`. |
726 | /// |
727 | /// As long as the executor keeps running and the task is not finished, it is |
728 | /// guaranteed that each invocation of [`wake()`](Self::wake) (or |
729 | /// [`wake_by_ref()`](Self::wake_by_ref)) will be followed by at least one |
730 | /// [`poll()`] of the task to which this `LocalWaker` belongs. This makes |
731 | /// it possible to temporarily yield to other tasks while running potentially |
732 | /// unbounded processing loops. |
733 | /// |
734 | /// Note that the above implies that multiple wake-ups may be coalesced into a |
735 | /// single [`poll()`] invocation by the runtime. |
736 | /// |
737 | /// Also note that yielding to competing tasks is not guaranteed: it is the |
738 | /// executor’s choice which task to run and the executor may choose to run the |
739 | /// current task again. |
740 | /// |
741 | /// [`poll()`]: crate::future::Future::poll |
742 | #[inline] |
743 | #[unstable(feature = "local_waker", issue = "118959")] |
744 | pub fn wake(self) { |
745 | // The actual wakeup call is delegated through a virtual function call |
746 | // to the implementation which is defined by the executor. |
747 | |
748 | // Don't call `drop` -- the waker will be consumed by `wake`. |
749 | let this = ManuallyDrop::new(self); |
750 | |
751 | // SAFETY: This is safe because `Waker::from_raw` is the only way |
752 | // to initialize `wake` and `data` requiring the user to acknowledge |
753 | // that the contract of `RawWaker` is upheld. |
754 | unsafe { (this.waker.vtable.wake)(this.waker.data) }; |
755 | } |
756 | |
757 | /// Wakes up the task associated with this `LocalWaker` without consuming the `LocalWaker`. |
758 | /// |
759 | /// This is similar to [`wake()`](Self::wake), but may be slightly less efficient in |
760 | /// the case where an owned `Waker` is available. This method should be preferred to |
761 | /// calling `waker.clone().wake()`. |
762 | #[inline] |
763 | #[unstable(feature = "local_waker", issue = "118959")] |
764 | pub fn wake_by_ref(&self) { |
765 | // The actual wakeup call is delegated through a virtual function call |
766 | // to the implementation which is defined by the executor. |
767 | |
768 | // SAFETY: see `wake` |
769 | unsafe { (self.waker.vtable.wake_by_ref)(self.waker.data) } |
770 | } |
771 | |
772 | /// Returns `true` if this `LocalWaker` and another `LocalWaker` would awake the same task. |
773 | /// |
774 | /// This function works on a best-effort basis, and may return false even |
775 | /// when the `Waker`s would awaken the same task. However, if this function |
776 | /// returns `true`, it is guaranteed that the `Waker`s will awaken the same task. |
777 | /// |
778 | /// This function is primarily used for optimization purposes — for example, |
779 | /// this type's [`clone_from`](Self::clone_from) implementation uses it to |
780 | /// avoid cloning the waker when they would wake the same task anyway. |
781 | #[inline] |
782 | #[must_use] |
783 | #[unstable(feature = "local_waker", issue = "118959")] |
784 | pub fn will_wake(&self, other: &LocalWaker) -> bool { |
785 | // We optimize this by comparing vtable addresses instead of vtable contents. |
786 | // This is permitted since the function is documented as best-effort. |
787 | let RawWaker { data: a_data, vtable: a_vtable } = self.waker; |
788 | let RawWaker { data: b_data, vtable: b_vtable } = other.waker; |
789 | a_data == b_data && ptr::eq(a_vtable, b_vtable) |
790 | } |
791 | |
792 | /// Creates a new `LocalWaker` from the provided `data` pointer and `vtable`. |
793 | /// |
794 | /// The `data` pointer can be used to store arbitrary data as required |
795 | /// by the executor. This could be e.g. a type-erased pointer to an `Arc` |
796 | /// that is associated with the task. |
797 | /// The value of this pointer will get passed to all functions that are part |
798 | /// of the `vtable` as the first parameter. |
799 | /// |
800 | /// The `vtable` customizes the behavior of a `LocalWaker`. For each |
801 | /// operation on the `LocalWaker`, the associated function in the `vtable` |
802 | /// will be called. |
803 | /// |
804 | /// # Safety |
805 | /// |
806 | /// The behavior of the returned `Waker` is undefined if the contract defined |
807 | /// in [`RawWakerVTable`]'s documentation is not upheld. |
808 | /// |
809 | #[inline] |
810 | #[must_use] |
811 | #[unstable(feature = "local_waker", issue = "118959")] |
812 | pub const unsafe fn new(data: *const (), vtable: &'static RawWakerVTable) -> Self { |
813 | LocalWaker { waker: RawWaker { data, vtable } } |
814 | } |
815 | |
816 | /// Creates a new `LocalWaker` from [`RawWaker`]. |
817 | /// |
818 | /// The behavior of the returned `LocalWaker` is undefined if the contract defined |
819 | /// in [`RawWaker`]'s and [`RawWakerVTable`]'s documentation is not upheld. |
820 | /// Therefore this method is unsafe. |
821 | #[inline] |
822 | #[must_use] |
823 | #[unstable(feature = "local_waker", issue = "118959")] |
824 | pub const unsafe fn from_raw(waker: RawWaker) -> LocalWaker { |
825 | Self { waker } |
826 | } |
827 | |
828 | /// Returns a reference to a `LocalWaker` that does nothing when used. |
829 | /// |
830 | // Note! Much of the documentation for this method is duplicated |
831 | // in the docs for `Waker::noop`. |
832 | // If you edit it, consider editing the other copy too. |
833 | // |
834 | /// This is mostly useful for writing tests that need a [`Context`] to poll |
835 | /// some futures, but are not expecting those futures to wake the waker or |
836 | /// do not need to do anything specific if it happens. |
837 | /// |
838 | /// More generally, using `LocalWaker::noop()` to poll a future |
839 | /// means discarding the notification of when the future should be polled again, |
840 | /// So it should only be used when such a notification will not be needed to make progress. |
841 | /// |
842 | /// If an owned `LocalWaker` is needed, `clone()` this one. |
843 | /// |
844 | /// # Examples |
845 | /// |
846 | /// ``` |
847 | /// #![feature(local_waker)] |
848 | /// use std::future::Future; |
849 | /// use std::task::{ContextBuilder, LocalWaker, Waker, Poll}; |
850 | /// |
851 | /// let mut cx = ContextBuilder::from_waker(Waker::noop()) |
852 | /// .local_waker(LocalWaker::noop()) |
853 | /// .build(); |
854 | /// |
855 | /// let mut future = Box::pin(async { 10 }); |
856 | /// assert_eq!(future.as_mut().poll(&mut cx), Poll::Ready(10)); |
857 | /// ``` |
858 | #[inline] |
859 | #[must_use] |
860 | #[unstable(feature = "local_waker", issue = "118959")] |
861 | pub const fn noop() -> &'static LocalWaker { |
862 | const WAKER: &LocalWaker = &LocalWaker { waker: RawWaker::NOOP }; |
863 | WAKER |
864 | } |
865 | |
866 | /// Gets the `data` pointer used to create this `LocalWaker`. |
867 | #[inline] |
868 | #[must_use] |
869 | #[unstable(feature = "local_waker", issue = "118959")] |
870 | pub fn data(&self) -> *const () { |
871 | self.waker.data |
872 | } |
873 | |
874 | /// Gets the `vtable` pointer used to create this `LocalWaker`. |
875 | #[inline] |
876 | #[must_use] |
877 | #[unstable(feature = "local_waker", issue = "118959")] |
878 | pub fn vtable(&self) -> &'static RawWakerVTable { |
879 | self.waker.vtable |
880 | } |
881 | } |
882 | #[unstable(feature = "local_waker", issue = "118959")] |
883 | impl Clone for LocalWaker { |
884 | #[inline] |
885 | fn clone(&self) -> Self { |
886 | LocalWaker { |
887 | // SAFETY: This is safe because `Waker::from_raw` is the only way |
888 | // to initialize `clone` and `data` requiring the user to acknowledge |
889 | // that the contract of [`RawWaker`] is upheld. |
890 | waker: unsafe { (self.waker.vtable.clone)(self.waker.data) }, |
891 | } |
892 | } |
893 | |
894 | #[inline] |
895 | fn clone_from(&mut self, source: &Self) { |
896 | if !self.will_wake(source) { |
897 | *self = source.clone(); |
898 | } |
899 | } |
900 | } |
901 | |
902 | #[unstable(feature = "local_waker", issue = "118959")] |
903 | impl AsRef<LocalWaker> for Waker { |
904 | fn as_ref(&self) -> &LocalWaker { |
905 | // SAFETY: LocalWaker is just Waker without thread safety |
906 | unsafe { transmute(self) } |
907 | } |
908 | } |
909 | |
910 | #[unstable(feature = "local_waker", issue = "118959")] |
911 | impl Drop for LocalWaker { |
912 | #[inline] |
913 | fn drop(&mut self) { |
914 | // SAFETY: This is safe because `LocalWaker::from_raw` is the only way |
915 | // to initialize `drop` and `data` requiring the user to acknowledge |
916 | // that the contract of `RawWaker` is upheld. |
917 | unsafe { (self.waker.vtable.drop)(self.waker.data) } |
918 | } |
919 | } |
920 | |
921 | #[unstable(feature = "local_waker", issue = "118959")] |
922 | impl fmt::Debug for LocalWaker { |
923 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
924 | let vtable_ptr: *const RawWakerVTable = self.waker.vtable as *const RawWakerVTable; |
925 | f&mut DebugStruct<'_, '_>.debug_struct("LocalWaker") |
926 | .field("data", &self.waker.data) |
927 | .field(name:"vtable", &vtable_ptr) |
928 | .finish() |
929 | } |
930 | } |
931 | |
932 | #[unstable(feature = "local_waker", issue = "118959")] |
933 | impl !Send for LocalWaker {} |
934 | #[unstable(feature = "local_waker", issue = "118959")] |
935 | impl !Sync for LocalWaker {} |
936 |
Definitions
- RawWaker
- data
- vtable
- new
- RawWakerVTable
- clone
- wake
- wake_by_ref
- drop
- new
- ExtData
- Some
- None
- Context
- waker
- local_waker
- ext
- _marker
- _marker2
- from_waker
- waker
- local_waker
- ext
- fmt
- ContextBuilder
- waker
- local_waker
- ext
- _marker
- _marker2
- from_waker
- from
- waker
- local_waker
- ext
- build
- waker
- local_waker
- ext
- _marker
- _marker2
- Waker
- waker
- wake
- wake_by_ref
- will_wake
- new
- from_raw
- noop
- data
- vtable
- clone
- clone_from
- drop
- fmt
- LocalWaker
- waker
- wake
- wake_by_ref
- will_wake
- new
- from_raw
- noop
- data
- vtable
- clone
- clone_from
- as_ref
- drop
Learn Rust with the experts
Find out more