1#![stable(feature = "futures_api", since = "1.36.0")]
2
3use crate::any::Any;
4use crate::marker::PhantomData;
5use crate::mem::{ManuallyDrop, transmute};
6use crate::panic::AssertUnwindSafe;
7use 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")]
22pub 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
33impl 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)]
108pub 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
141impl 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)]
206enum 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"]
217pub 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
231impl<'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")]
271impl 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)]
300pub 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
314impl<'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"]
406pub struct Waker {
407 waker: RawWaker,
408}
409
410#[stable(feature = "futures_api", since = "1.36.0")]
411impl Unpin for Waker {}
412#[stable(feature = "futures_api", since = "1.36.0")]
413unsafe impl Send for Waker {}
414#[stable(feature = "futures_api", since = "1.36.0")]
415unsafe impl Sync for Waker {}
416
417impl 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")]
589impl 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")]
645impl 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")]
656impl 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)]
717pub struct LocalWaker {
718 waker: RawWaker,
719}
720
721#[unstable(feature = "local_waker", issue = "118959")]
722impl Unpin for LocalWaker {}
723
724impl 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")]
883impl 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")]
903impl 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")]
911impl 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")]
922impl 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")]
933impl !Send for LocalWaker {}
934#[unstable(feature = "local_waker", issue = "118959")]
935impl !Sync for LocalWaker {}
936