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     #[must_use]
  43     pub const fn new(data: *const (), vtable: &'static RawWakerVTable) -> RawWaker {
  44         RawWaker { data, vtable }
  45     }
  46
  47     /// Get the `data` pointer used to create this `RawWaker`.
  48     #[inline]
  49     #[must_use]
  50     #[unstable(feature = "waker_getters", issue = "87021")]
  51     pub fn data(&self) -> *const () {
  52         self.data
  53     }
  54
  55     /// Get the `vtable` pointer used to create this `RawWaker`.
  56     #[inline]
  57     #[must_use]
  58     #[unstable(feature = "waker_getters", issue = "87021")]
  59     pub fn vtable(&self) -> &'static RawWakerVTable {
  60         self.vtable
  61     }
  62 }
  63
  64 /// A virtual function pointer table (vtable) that specifies the behavior
  65 /// of a [`RawWaker`].
  66 ///
  67 /// The pointer passed to all functions inside the vtable is the `data` pointer
  68 /// from the enclosing [`RawWaker`] object.
  69 ///
  70 /// The functions inside this struct are only intended to be called on the `data`
  71 /// pointer of a properly constructed [`RawWaker`] object from inside the
  72 /// [`RawWaker`] implementation. Calling one of the contained functions using
  73 /// any other `data` pointer will cause undefined behavior.
  74 #[stable(feature = "futures_api", since = "1.36.0")]
  75 #[derive(PartialEq, Copy, Clone, Debug)]
  76 pub struct RawWakerVTable {
  77     /// This function will be called when the [`RawWaker`] gets cloned, e.g. when
  78     /// the [`Waker`] in which the [`RawWaker`] is stored gets cloned.
  79     ///
  80     /// The implementation of this function must retain all resources that are
  81     /// required for this additional instance of a [`RawWaker`] and associated
  82     /// task. Calling `wake` on the resulting [`RawWaker`] should result in a wakeup
  83     /// of the same task that would have been awoken by the original [`RawWaker`].
  84     clone: unsafe fn(*const ()) -> RawWaker,
  85
  86     /// This function will be called when `wake` is called on the [`Waker`].
  87     /// It must wake up the task associated with this [`RawWaker`].
  88     ///
  89     /// The implementation of this function must make sure to release any
  90     /// resources that are associated with this instance of a [`RawWaker`] and
  91     /// associated task.
  92     wake: unsafe fn(*const ()),
  93
  94     /// This function will be called when `wake_by_ref` is called on the [`Waker`].
  95     /// It must wake up the task associated with this [`RawWaker`].
  96     ///
  97     /// This function is similar to `wake`, but must not consume the provided data
  98     /// pointer.
  99     wake_by_ref: unsafe fn(*const ()),
 100
 101     /// This function gets called when a [`RawWaker`] gets dropped.
 102     ///
 103     /// The implementation of this function must make sure to release any
 104     /// resources that are associated with this instance of a [`RawWaker`] and
 105     /// associated task.
 106     drop: unsafe fn(*const ()),
 107 }
 108
 109 impl RawWakerVTable {
 110     /// Creates a new `RawWakerVTable` from the provided `clone`, `wake`,
 111     /// `wake_by_ref`, and `drop` functions.
 112     ///
 113     /// # `clone`
 114     ///
 115     /// This function will be called when the [`RawWaker`] gets cloned, e.g. when
 116     /// the [`Waker`] in which the [`RawWaker`] is stored gets cloned.
 117     ///
 118     /// The implementation of this function must retain all resources that are
 119     /// required for this additional instance of a [`RawWaker`] and associated
 120     /// task. Calling `wake` on the resulting [`RawWaker`] should result in a wakeup
 121     /// of the same task that would have been awoken by the original [`RawWaker`].
 122     ///
 123     /// # `wake`
 124     ///
 125     /// This function will be called when `wake` is called on the [`Waker`].
 126     /// It must wake up the task associated with this [`RawWaker`].
 127     ///
 128     /// The implementation of this function must make sure to release any
 129     /// resources that are associated with this instance of a [`RawWaker`] and
 130     /// associated task.
 131     ///
 132     /// # `wake_by_ref`
 133     ///
 134     /// This function will be called when `wake_by_ref` is called on the [`Waker`].
 135     /// It must wake up the task associated with this [`RawWaker`].
 136     ///
 137     /// This function is similar to `wake`, but must not consume the provided data
 138     /// pointer.
 139     ///
 140     /// # `drop`
 141     ///
 142     /// This function gets called when a [`RawWaker`] gets dropped.
 143     ///
 144     /// The implementation of this function must make sure to release any
 145     /// resources that are associated with this instance of a [`RawWaker`] and
 146     /// associated task.
 147     #[rustc_promotable]
 148     #[stable(feature = "futures_api", since = "1.36.0")]
 149     #[rustc_const_stable(feature = "futures_api", since = "1.36.0")]
 150     pub const fn new(
 151         clone: unsafe fn(*const ()) -> RawWaker,
 152         wake: unsafe fn(*const ()),
 153         wake_by_ref: unsafe fn(*const ()),
 154         drop: unsafe fn(*const ()),
 155     ) -> Self {
 156         Self { clone, wake, wake_by_ref, drop }
 157     }
 158 }
 159
 160 /// The `Context` of an asynchronous task.
 161 ///
 162 /// Currently, `Context` only serves to provide access to a `&Waker`
 163 /// which can be used to wake the current task.
 164 #[stable(feature = "futures_api", since = "1.36.0")]
 165 pub struct Context<'a> {
 166     waker: &'a Waker,
 167     // Ensure we future-proof against variance changes by forcing
 168     // the lifetime to be invariant (argument-position lifetimes
 169     // are contravariant while return-position lifetimes are
 170     // covariant).
 171     _marker: PhantomData<fn(&'a ()) -> &'a ()>,
 172 }
 173
 174 impl<'a> Context<'a> {
 175     /// Create a new `Context` from a `&Waker`.
 176     #[stable(feature = "futures_api", since = "1.36.0")]
 177     #[must_use]
 178     #[inline]
 179     pub fn from_waker(waker: &'a Waker) -> Self {
 180         Context { waker, _marker: PhantomData }
 181     }
 182
 183     /// Returns a reference to the `Waker` for the current task.
 184     #[stable(feature = "futures_api", since = "1.36.0")]
 185     #[must_use]
 186     #[inline]
 187     pub fn waker(&self) -> &'a Waker {
 188         &self.waker
 189     }
 190 }
 191
 192 #[stable(feature = "futures_api", since = "1.36.0")]
 193 impl fmt::Debug for Context<'_> {
 194     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 195         f.debug_struct("Context").field("waker", &self.waker).finish()
 196     }
 197 }
 198
 199 /// A `Waker` is a handle for waking up a task by notifying its executor that it
 200 /// is ready to be run.
 201 ///
 202 /// This handle encapsulates a [`RawWaker`] instance, which defines the
 203 /// executor-specific wakeup behavior.
 204 ///
 205 /// Implements [`Clone`], [`Send`], and [`Sync`].
 206 #[repr(transparent)]
 207 #[stable(feature = "futures_api", since = "1.36.0")]
 208 pub struct Waker {
 209     waker: RawWaker,
 210 }
 211
 212 #[stable(feature = "futures_api", since = "1.36.0")]
 213 impl Unpin for Waker {}
 214 #[stable(feature = "futures_api", since = "1.36.0")]
 215 unsafe impl Send for Waker {}
 216 #[stable(feature = "futures_api", since = "1.36.0")]
 217 unsafe impl Sync for Waker {}
 218
 219 impl Waker {
 220     /// Wake up the task associated with this `Waker`.
 221     ///
 222     /// As long as the runtime keeps running and the task is not finished, it is
 223     /// guaranteed that each invocation of `wake` (or `wake_by_ref`) will be followed
 224     /// by at least one `poll` of the task to which this `Waker` belongs. This makes
 225     /// it possible to temporarily yield to other tasks while running potentially
 226     /// unbounded processing loops.
 227     ///
 228     /// Note that the above implies that multiple wake-ups may be coalesced into a
 229     /// single `poll` invocation by the runtime.
 230     ///
 231     /// Also note that yielding to competing tasks is not guaranteed: it is the
 232     /// executor’s choice which task to run and the executor may choose to run the
 233     /// current task again.
 234     #[inline]
 235     #[stable(feature = "futures_api", since = "1.36.0")]
 236     pub fn wake(self) {
 237         // The actual wakeup call is delegated through a virtual function call
 238         // to the implementation which is defined by the executor.
 239         let wake = self.waker.vtable.wake;
 240         let data = self.waker.data;
 241
 242         // Don't call `drop` -- the waker will be consumed by `wake`.
 243         crate::mem::forget(self);
 244
 245         // SAFETY: This is safe because `Waker::from_raw` is the only way
 246         // to initialize `wake` and `data` requiring the user to acknowledge
 247         // that the contract of `RawWaker` is upheld.
 248         unsafe { (wake)(data) };
 249     }
 250
 251     /// Wake up the task associated with this `Waker` without consuming the `Waker`.
 252     ///
 253     /// This is similar to `wake`, but may be slightly less efficient in the case
 254     /// where an owned `Waker` is available. This method should be preferred to
 255     /// calling `waker.clone().wake()`.
 256     #[inline]
 257     #[stable(feature = "futures_api", since = "1.36.0")]
 258     pub fn wake_by_ref(&self) {
 259         // The actual wakeup call is delegated through a virtual function call
 260         // to the implementation which is defined by the executor.
 261
 262         // SAFETY: see `wake`
 263         unsafe { (self.waker.vtable.wake_by_ref)(self.waker.data) }
 264     }
 265
 266     /// Returns `true` if this `Waker` and another `Waker` have awoken the same task.
 267     ///
 268     /// This function works on a best-effort basis, and may return false even
 269     /// when the `Waker`s would awaken the same task. However, if this function
 270     /// returns `true`, it is guaranteed that the `Waker`s will awaken the same task.
 271     ///
 272     /// This function is primarily used for optimization purposes.
 273     #[inline]
 274     #[must_use]
 275     #[stable(feature = "futures_api", since = "1.36.0")]
 276     pub fn will_wake(&self, other: &Waker) -> bool {
 277         self.waker == other.waker
 278     }
 279
 280     /// Creates a new `Waker` from [`RawWaker`].
 281     ///
 282     /// The behavior of the returned `Waker` is undefined if the contract defined
 283     /// in [`RawWaker`]'s and [`RawWakerVTable`]'s documentation is not upheld.
 284     /// Therefore this method is unsafe.
 285     #[inline]
 286     #[must_use]
 287     #[stable(feature = "futures_api", since = "1.36.0")]
 288     pub unsafe fn from_raw(waker: RawWaker) -> Waker {
 289         Waker { waker }
 290     }
 291
 292     /// Get a reference to the underlying [`RawWaker`].
 293     #[inline]
 294     #[must_use]
 295     #[unstable(feature = "waker_getters", issue = "87021")]
 296     pub fn as_raw(&self) -> &RawWaker {
 297         &self.waker
 298     }
 299 }
 300
 301 #[stable(feature = "futures_api", since = "1.36.0")]
 302 impl Clone for Waker {
 303     #[inline]
 304     fn clone(&self) -> Self {
 305         Waker {
 306             // SAFETY: This is safe because `Waker::from_raw` is the only way
 307             // to initialize `clone` and `data` requiring the user to acknowledge
 308             // that the contract of [`RawWaker`] is upheld.
 309             waker: unsafe { (self.waker.vtable.clone)(self.waker.data) },
 310         }
 311     }
 312 }
 313
 314 #[stable(feature = "futures_api", since = "1.36.0")]
 315 impl Drop for Waker {
 316     #[inline]
 317     fn drop(&mut self) {
 318         // SAFETY: This is safe because `Waker::from_raw` is the only way
 319         // to initialize `drop` and `data` requiring the user to acknowledge
 320         // that the contract of `RawWaker` is upheld.
 321         unsafe { (self.waker.vtable.drop)(self.waker.data) }
 322     }
 323 }
 324
 325 #[stable(feature = "futures_api", since = "1.36.0")]
 326 impl fmt::Debug for Waker {
 327     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 328         let vtable_ptr = self.waker.vtable as *const RawWakerVTable;
 329         f.debug_struct("Waker")
 330             .field("data", &self.waker.data)
 331             .field("vtable", &vtable_ptr)
 332             .finish()
 333     }
 334 }