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