Text of rust.docs.kernel.org › next › src › core › task › wake.rs.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

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 /// This struct is guaranteed to be aligned to at least 8 bytes. 94 /// 95 /// # Thread safety 96 /// If the [`RawWaker`] will be used to construct a [`Waker`] then 97 /// these functions must all be thread-safe (even though [`RawWaker`] is 98 /// <code>\![Send] + \![Sync]</code>). This is because [`Waker`] is <code>[Send] + [Sync]</code>, 99 /// and it may be moved to arbitrary threads or invoked by `&` reference.

For example, 100 /// this means that if the `clone` and `drop` functions manage a reference count, 101 /// they must do so atomically. 102 /// 103 /// However, if the [`RawWaker`] will be used to construct a [`LocalWaker`] instead, then 104 /// these functions don't need to be thread safe. This means that <code>\![Send] + \![Sync]</code> 105 /// data can be stored in the data pointer, and reference counting does not need any atomic 106 /// synchronization.

This is because [`LocalWaker`] is not thread safe itself, so it cannot 107 /// be sent across threads. 108 #[stable(feature = "futures_api" , since = "1.36.0" )] 109 #[allow(unpredictable_function_pointer_comparisons)] 110 #[derive( PartialEq , Copy , Clone , Debug )] 111 // For bit-stuffing pointers we guarantee align >= 8. 112 #[repr(align( 8 ))] 113 pub struct RawWakerVTable { 114 /// This function will be called when the [`RawWaker`] gets cloned, e.g. when 115 /// the [`Waker`] in which the [`RawWaker`] is stored gets cloned.

116 /// 117 /// The implementation of this function must retain all resources that are 118 /// required for this additional instance of a [`RawWaker`] and associated 119 /// task. Calling `wake` on the resulting [`RawWaker`] should result in a wakeup 120 /// of the same task that would have been awoken by the original [`RawWaker`]. 121 clone: unsafe fn ( *const ()) -> RawWaker , 122 123 /// This function will be called when `wake` is called on the [`Waker`].

124 /// It must wake up the task associated with this [`RawWaker`]. 125 /// 126 /// The implementation of this function must make sure to release any 127 /// resources that are associated with this instance of a [`RawWaker`] and 128 /// associated task. 129 wake: unsafe fn ( *const ()), 130 131 /// This function will be called when `wake_by_ref` is called on the [`Waker`]. 132 /// It must wake up the task associated with this [`RawWaker`].

133 /// 134 /// This function is similar to `wake`, but must not consume the provided data 135 /// pointer. 136 wake_by_ref: unsafe fn ( *const ()), 137 138 /// This function will be called when a [`Waker`] gets dropped. 139 /// 140 /// The implementation of this function must make sure to release any 141 /// resources that are associated with this instance of a [`RawWaker`] and 142 /// associated task. 143 drop: unsafe fn ( *const ()), 144 } 145 146 impl RawWakerVTable { 147 /// Creates a new `RawWakerVTable` from the provided `clone`, `wake`, 148 /// `wake_by_ref`, and `drop` functions.

149 /// 150 /// If the [`RawWaker`] will be used to construct a [`Waker`] then 151 /// these functions must all be thread-safe (even though [`RawWaker`] is 152 /// <code>\![Send] + \![Sync]</code>). This is because [`Waker`] is <code>[Send] + [Sync]</code>, 153 /// and it may be moved to arbitrary threads or invoked by `&` reference. For example, 154 /// this means that if the `clone` and `drop` functions manage a reference count, 155 /// they must do so atomically.

156 /// 157 /// However, if the [`RawWaker`] will be used to construct a [`LocalWaker`] instead, then 158 /// these functions don't need to be thread safe. This means that <code>\![Send] + \![Sync]</code> 159 /// data can be stored in the data pointer, and reference counting does not need any atomic 160 /// synchronization. This is because [`LocalWaker`] is not thread safe itself, so it cannot 161 /// be sent acr

The rest of this page is on the live site.