library/core/src/task/wake.rs

   1 #![stable(feature = "futures_api", since = "1.36.0")]
   2
   3 use crate::fmt;
   4 use crate::marker::{PhantomData, Unpin};
   5
   6 /// A `RawWaker` allows the implementor of a task executor to create a [`Waker`]
   7 /// which provides customized wakeup behavior.
   8 ///
   9 /// [vtable]: https://en.wikipedia.org/wiki/Virtual_method_table
  10 ///
  11 /// It consists of a data pointer and a [virtual function pointer table (vtable)][vtable]
  12 /// that customizes the behavior of the `RawWaker`.
  13 #[derive(PartialEq, Debug)]
  14 #[stable(feature = "futures_api", since = "1.36.0")]
  15 pub struct RawWaker {
  16     /// A data pointer, which can be used to store arbitrary data as required
  17     /// by the executor. This could be e.g. a type-erased pointer to an `Arc`
  18     /// that is associated with the task.
  19     /// The value of this field gets passed to all functions that are part of
  20     /// the vtable as the first parameter.
  21     data: *const (),
  22     /// Virtual function pointer table that customizes the behavior of this waker.
  23     vtable: &'static RawWakerVTable,
  24 }
  25
  26 impl RawWaker {
  27     /// Creates a new `RawWaker` from the provided `data` pointer and `vtable`.
  28     ///
  29     /// The `data` pointer can be used to store arbitrary data as required
  30     /// by the executor. This could be e.g. a type-erased pointer to an `Arc`
  31     /// that is associated with the task.
  32     /// The value of this pointer will get passed to all functions that are part
  33     /// of the `vtable` as the first parameter.
  34     ///
  35     /// The `vtable` customizes the behavior of a `Waker` which gets created
  36     /// from a `RawWaker`. For each operation on the `Waker`, the associated
  37     /// function in the `vtable` of the underlying `RawWaker` will be called.
  38     #[inline]
  39     #[rustc_promotable]
  40     #[stable(feature = "futures_api", since = "1.36.0")]
  41     #[rustc_const_stable(feature = "futures_api", since = "1.36.0")]
  42     pub const fn new(data: *const (), vtable: &'static RawWakerVTable) -> RawWaker {
  43         RawWaker { data, vtable }
  44     }
  45 }
  46
  47 /// A virtual function pointer table (vtable) that specifies the behavior
  48 /// of a [`RawWaker`].
  49 ///
  50 /// The pointer passed to all functions inside the vtable is the `data` pointer
  51 /// from the enclosing [`RawWaker`] object.
  52 ///
  53 /// The functions inside this struct are only intended to be called on the `data`
  54 /// pointer of a properly constructed [`RawWaker`] object from inside the
  55 /// [`RawWaker`] implementation. Calling one of the contained functions using
  56 /// any other `data` pointer will cause undefined behavior.
  57 #[stable(feature = "futures_api", since = "1.36.0")]
  58 #[derive(PartialEq, Copy, Clone, Debug)]
  59 pub struct RawWakerVTable {
  60     /// This function will be called when the [`RawWaker`] gets cloned, e.g. when
  61     /// the [`Waker`] in which the [`RawWaker`] is stored gets cloned.
  62     ///
  63     /// The implementation of this function must retain all resources that are
  64     /// required for this additional instance of a [`RawWaker`] and associated
  65     /// task. Calling `wake` on the resulting [`RawWaker`] should result in a wakeup
  66     /// of the same task that would have been awoken by the original [`RawWaker`].
  67     clone: unsafe fn(*const ()) -> RawWaker,
  68
  69     /// This function will be called when `wake` is called on the [`Waker`].
  70     /// It must wake up the task associated with this [`RawWaker`].
  71     ///
  72     /// The implementation of this function must make sure to release any
  73     /// resources that are associated with this instance of a [`RawWaker`] and
  74     /// associated task.
  75     wake: unsafe fn(*const ()),
  76
  77     /// This function will be called when `wake_by_ref` is called on the [`Waker`].
  78     /// It must wake up the task associated with this [`RawWaker`].
  79     ///
  80     /// This function is similar to `wake`, but must not consume the provided data
  81     /// pointer.
  82     wake_by_ref: unsafe fn(*const ()),
  83
  84     /// This function gets called when a [`RawWaker`] gets dropped.
  85     ///
  86     /// The implementation of this function must make sure to release any
  87     /// resources that are associated with this instance of a [`RawWaker`] and
  88     /// associated task.
  89     drop: unsafe fn(*const ()),
  90 }
  91
  92 impl RawWakerVTable {
  93     /// Creates a new `RawWakerVTable` from the provided `clone`, `wake`,
  94     /// `wake_by_ref`, and `drop` functions.
  95     ///
  96     /// # `clone`
  97     ///
  98     /// This function will be called when the [`RawWaker`] gets cloned, e.g. when
  99     /// the [`Waker`] in which the [`RawWaker`] is stored gets cloned.
 100     ///
 101     /// The implementation of this function must retain all resources that are
 102     /// required for this additional instance of a [`RawWaker`] and associated
 103     /// task. Calling `wake` on the resulting [`RawWaker`] should result in a wakeup
 104     /// of the same task that would have been awoken by the original [`RawWaker`].
 105     ///
 106     /// # `wake`
 107     ///
 108     /// This function will be called when `wake` is called on the [`Waker`].
 109     /// It must wake up the task associated with this [`RawWaker`].
 110     ///
 111     /// The implementation of this function must make sure to release any
 112     /// resources that are associated with this instance of a [`RawWaker`] and
 113     /// associated task.
 114     ///
 115     /// # `wake_by_ref`
 116     ///
 117     /// This function will be called when `wake_by_ref` is called on the [`Waker`].
 118     /// It must wake up the task associated with this [`RawWaker`].
 119     ///
 120     /// This function is similar to `wake`, but must not consume the provided data
 121     /// pointer.
 122     ///
 123     /// # `drop`
 124     ///
 125     /// This function gets called when a [`RawWaker`] gets dropped.
 126     ///
 127     /// The implementation of this function must make sure to release any
 128     /// resources that are associated with this instance of a [`RawWaker`] and
 129     /// associated task.
 130     #[rustc_promotable]
 131     #[stable(feature = "futures_api", since = "1.36.0")]
 132     // `rustc_allow_const_fn_ptr` is a hack that should not be used anywhere else
 133     // without first consulting with T-Lang.
 134     //
 135     // FIXME: remove whenever we have a stable way to accept fn pointers from const fn
 136     // (see https://github.com/rust-rfcs/const-eval/issues/19#issuecomment-472799062)
 137     #[rustc_allow_const_fn_ptr]
 138     #[rustc_const_stable(feature = "futures_api", since = "1.36.0")]
 139     pub const fn new(
 140         clone: unsafe fn(*const ()) -> RawWaker,
 141         wake: unsafe fn(*const ()),
 142         wake_by_ref: unsafe fn(*const ()),
 143         drop: unsafe fn(*const ()),
 144     ) -> Self {
 145         Self { clone, wake, wake_by_ref, drop }
 146     }
 147 }
 148
 149 /// The `Context` of an asynchronous task.
 150 ///
 151 /// Currently, `Context` only serves to provide access to a `&Waker`
 152 /// which can be used to wake the current task.
 153 #[stable(feature = "futures_api", since = "1.36.0")]
 154 pub struct Context<'a> {
 155     waker: &'a Waker,
 156     // Ensure we future-proof against variance changes by forcing
 157     // the lifetime to be invariant (argument-position lifetimes
 158     // are contravariant while return-position lifetimes are
 159     // covariant).
 160     _marker: PhantomData<fn(&'a ()) -> &'a ()>,
 161 }
 162
 163 impl<'a> Context<'a> {
 164     /// Create a new `Context` from a `&Waker`.
 165     #[stable(feature = "futures_api", since = "1.36.0")]
 166     #[inline]
 167     pub fn from_waker(waker: &'a Waker) -> Self {
 168         Context { waker, _marker: PhantomData }
 169     }
 170
 171     /// Returns a reference to the `Waker` for the current task.
 172     #[stable(feature = "futures_api", since = "1.36.0")]
 173     #[inline]
 174     pub fn waker(&self) -> &'a Waker {
 175         &self.waker
 176     }
 177 }
 178
 179 #[stable(feature = "futures_api", since = "1.36.0")]
 180 impl fmt::Debug for Context<'_> {
 181     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 182         f.debug_struct("Context").field("waker", &self.waker).finish()
 183     }
 184 }
 185
 186 /// A `Waker` is a handle for waking up a task by notifying its executor that it
 187 /// is ready to be run.
 188 ///
 189 /// This handle encapsulates a [`RawWaker`] instance, which defines the
 190 /// executor-specific wakeup behavior.
 191 ///
 192 /// Implements [`Clone`], [`Send`], and [`Sync`].
 193 #[repr(transparent)]
 194 #[stable(feature = "futures_api", since = "1.36.0")]
 195 pub struct Waker {
 196     waker: RawWaker,
 197 }
 198
 199 #[stable(feature = "futures_api", since = "1.36.0")]
 200 impl Unpin for Waker {}
 201 #[stable(feature = "futures_api", since = "1.36.0")]
 202 unsafe impl Send for Waker {}
 203 #[stable(feature = "futures_api", since = "1.36.0")]
 204 unsafe impl Sync for Waker {}
 205
 206 impl Waker {
 207     /// Wake up the task associated with this `Waker`.
 208     #[inline]
 209     #[stable(feature = "futures_api", since = "1.36.0")]
 210     pub fn wake(self) {
 211         // The actual wakeup call is delegated through a virtual function call
 212         // to the implementation which is defined by the executor.
 213         let wake = self.waker.vtable.wake;
 214         let data = self.waker.data;
 215
 216         // Don't call `drop` -- the waker will be consumed by `wake`.
 217         crate::mem::forget(self);
 218
 219         // SAFETY: This is safe because `Waker::from_raw` is the only way
 220         // to initialize `wake` and `data` requiring the user to acknowledge
 221         // that the contract of `RawWaker` is upheld.
 222         unsafe { (wake)(data) };
 223     }
 224
 225     /// Wake up the task associated with this `Waker` without consuming the `Waker`.
 226     ///
 227     /// This is similar to `wake`, but may be slightly less efficient in the case
 228     /// where an owned `Waker` is available. This method should be preferred to
 229     /// calling `waker.clone().wake()`.
 230     #[inline]
 231     #[stable(feature = "futures_api", since = "1.36.0")]
 232     pub fn wake_by_ref(&self) {
 233         // The actual wakeup call is delegated through a virtual function call
 234         // to the implementation which is defined by the executor.
 235
 236         // SAFETY: see `wake`
 237         unsafe { (self.waker.vtable.wake_by_ref)(self.waker.data) }
 238     }
 239
 240     /// Returns `true` if this `Waker` and another `Waker` have awoken the same task.
 241     ///
 242     /// This function works on a best-effort basis, and may return false even
 243     /// when the `Waker`s would awaken the same task. However, if this function
 244     /// returns `true`, it is guaranteed that the `Waker`s will awaken the same task.
 245     ///
 246     /// This function is primarily used for optimization purposes.
 247     #[inline]
 248     #[stable(feature = "futures_api", since = "1.36.0")]
 249     pub fn will_wake(&self, other: &Waker) -> bool {
 250         self.waker == other.waker
 251     }
 252
 253     /// Creates a new `Waker` from [`RawWaker`].
 254     ///
 255     /// The behavior of the returned `Waker` is undefined if the contract defined
 256     /// in [`RawWaker`]'s and [`RawWakerVTable`]'s documentation is not upheld.
 257     /// Therefore this method is unsafe.
 258     #[inline]
 259     #[stable(feature = "futures_api", since = "1.36.0")]
 260     pub unsafe fn from_raw(waker: RawWaker) -> Waker {
 261         Waker { waker }
 262     }
 263 }
 264
 265 #[stable(feature = "futures_api", since = "1.36.0")]
 266 impl Clone for Waker {
 267     #[inline]
 268     fn clone(&self) -> Self {
 269         Waker {
 270             // SAFETY: This is safe because `Waker::from_raw` is the only way
 271             // to initialize `clone` and `data` requiring the user to acknowledge
 272             // that the contract of [`RawWaker`] is upheld.
 273             waker: unsafe { (self.waker.vtable.clone)(self.waker.data) },
 274         }
 275     }
 276 }
 277
 278 #[stable(feature = "futures_api", since = "1.36.0")]
 279 impl Drop for Waker {
 280     #[inline]
 281     fn drop(&mut self) {
 282         // SAFETY: This is safe because `Waker::from_raw` is the only way
 283         // to initialize `drop` and `data` requiring the user to acknowledge
 284         // that the contract of `RawWaker` is upheld.
 285         unsafe { (self.waker.vtable.drop)(self.waker.data) }
 286     }
 287 }
 288
 289 #[stable(feature = "futures_api", since = "1.36.0")]
 290 impl fmt::Debug for Waker {
 291     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 292         let vtable_ptr = self.waker.vtable as *const RawWakerVTable;
 293         f.debug_struct("Waker")
 294             .field("data", &self.waker.data)
 295             .field("vtable", &vtable_ptr)
 296             .finish()
 297     }
 298 }