core/task/
wake.rs

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