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