src/libcore/task/wake.rs

   1 #![unstable(feature = "futures_api",
   2             reason = "futures in libcore are unstable",
   3             issue = "50547")]
   4
   5 use fmt;
   6 use marker::Unpin;
   7
   8 /// A `RawWaker` allows the implementor of a task executor to create a [`Waker`]
   9 /// which provides customized wakeup behavior.
  10 ///
  11 /// [vtable]: https://en.wikipedia.org/wiki/Virtual_method_table
  12 ///
  13 /// It consists of a data pointer and a [virtual function pointer table (vtable)][vtable] that
  14 /// customizes the behavior of the `RawWaker`.
  15 #[derive(PartialEq, Debug)]
  16 pub struct RawWaker {
  17     /// A data pointer, which can be used to store arbitrary data as required
  18     /// by the executor. This could be e.g. a type-erased pointer to an `Arc`
  19     /// that is associated with the task.
  20     /// The value of this field gets passed to all functions that are part of
  21     /// the vtable as the first parameter.
  22     data: *const (),
  23     /// Virtual function pointer table that customizes the behavior of this waker.
  24     vtable: &'static RawWakerVTable,
  25 }
  26
  27 impl RawWaker {
  28     /// Creates a new `RawWaker` from the provided `data` pointer and `vtable`.
  29     ///
  30     /// The `data` pointer can be used to store arbitrary data as required
  31     /// by the executor. This could be e.g. a type-erased pointer to an `Arc`
  32     /// that is associated with the task.
  33     /// The value of this poiner will get passed to all functions that are part
  34     /// of the `vtable` as the first parameter.
  35     ///
  36     /// The `vtable` customizes the behavior of a `Waker` which gets created
  37     /// from a `RawWaker`. For each operation on the `Waker`, the associated
  38     /// function in the `vtable` of the underlying `RawWaker` will be called.
  39     pub const fn new(data: *const (), vtable: &'static RawWakerVTable) -> RawWaker {
  40         RawWaker {
  41             data,
  42             vtable,
  43         }
  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 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 #[derive(PartialEq, Copy, Clone, Debug)]
  58 pub struct RawWakerVTable {
  59     /// This function will be called when the [`RawWaker`] gets cloned, e.g. when
  60     /// the [`Waker`] in which the [`RawWaker`] is stored gets cloned.
  61     ///
  62     /// The implementation of this function must retain all resources that are
  63     /// required for this additional instance of a [`RawWaker`] and associated
  64     /// task. Calling `wake` on the resulting [`RawWaker`] should result in a wakeup
  65     /// of the same task that would have been awoken by the original [`RawWaker`].
  66     pub clone: unsafe fn(*const ()) -> RawWaker,
  67
  68     /// This function will be called when `wake` is called on the [`Waker`].
  69     /// It must wake up the task associated with this [`RawWaker`].
  70     ///
  71     /// The implemention of this function must not consume the provided data
  72     /// pointer.
  73     pub wake: unsafe fn(*const ()),
  74
  75     /// This function gets called when a [`RawWaker`] gets dropped.
  76     ///
  77     /// The implementation of this function must make sure to release any
  78     /// resources that are associated with this instance of a [`RawWaker`] and
  79     /// associated task.
  80     pub drop: unsafe fn(*const ()),
  81 }
  82
  83 /// A `Waker` is a handle for waking up a task by notifying its executor that it
  84 /// is ready to be run.
  85 ///
  86 /// This handle encapsulates a [`RawWaker`] instance, which defines the
  87 /// executor-specific wakeup behavior.
  88 ///
  89 /// Implements [`Clone`], [`Send`], and [`Sync`].
  90 #[repr(transparent)]
  91 pub struct Waker {
  92     waker: RawWaker,
  93 }
  94
  95 impl Unpin for Waker {}
  96 unsafe impl Send for Waker {}
  97 unsafe impl Sync for Waker {}
  98
  99 impl Waker {
 100     /// Wake up the task associated with this `Waker`.
 101     pub fn wake(&self) {
 102         // The actual wakeup call is delegated through a virtual function call
 103         // to the implementation which is defined by the executor.
 104
 105         // SAFETY: This is safe because `Waker::new_unchecked` is the only way
 106         // to initialize `wake` and `data` requiring the user to acknowledge
 107         // that the contract of `RawWaker` is upheld.
 108         unsafe { (self.waker.vtable.wake)(self.waker.data) }
 109     }
 110
 111     /// Returns whether or not this `Waker` and other `Waker` have awaken the same task.
 112     ///
 113     /// This function works on a best-effort basis, and may return false even
 114     /// when the `Waker`s would awaken the same task. However, if this function
 115     /// returns `true`, it is guaranteed that the `Waker`s will awaken the same task.
 116     ///
 117     /// This function is primarily used for optimization purposes.
 118     pub fn will_wake(&self, other: &Waker) -> bool {
 119         self.waker == other.waker
 120     }
 121
 122     /// Creates a new `Waker` from [`RawWaker`].
 123     ///
 124     /// The behavior of the returned `Waker` is undefined if the contract defined
 125     /// in [`RawWaker`]'s and [`RawWakerVTable`]'s documentation is not upheld.
 126     /// Therefore this method is unsafe.
 127     pub unsafe fn new_unchecked(waker: RawWaker) -> Waker {
 128         Waker {
 129             waker,
 130         }
 131     }
 132 }
 133
 134 impl Clone for Waker {
 135     fn clone(&self) -> Self {
 136         Waker {
 137             // SAFETY: This is safe because `Waker::new_unchecked` is the only way
 138             // to initialize `clone` and `data` requiring the user to acknowledge
 139             // that the contract of [`RawWaker`] is upheld.
 140             waker: unsafe { (self.waker.vtable.clone)(self.waker.data) },
 141         }
 142     }
 143 }
 144
 145 impl Drop for Waker {
 146     fn drop(&mut self) {
 147         // SAFETY: This is safe because `Waker::new_unchecked` is the only way
 148         // to initialize `drop` and `data` requiring the user to acknowledge
 149         // that the contract of `RawWaker` is upheld.
 150         unsafe { (self.waker.vtable.drop)(self.waker.data) }
 151     }
 152 }
 153
 154 impl fmt::Debug for Waker {
 155     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 156         let vtable_ptr = self.waker.vtable as *const RawWakerVTable;
 157         f.debug_struct("Waker")
 158             .field("data", &self.waker.data)
 159             .field("vtable", &vtable_ptr)
 160             .finish()
 161     }
 162 }