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