wake.rs - source
Skip to main content core/task/ wake.rs 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 #[allow(unpredictable_function_pointer_comparisons)] 108 #[derive( PartialEq , Copy , Clone , Debug )] 109 pub 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 142 impl 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`] i
The rest of this page is on the live site.