src/libcore/task/wake.rs

   1 // Copyright 2018 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 #![unstable(feature = "futures_api",
  12             reason = "futures in libcore are unstable",
  13             issue = "50547")]
  14
  15 use fmt;
  16 use ptr::NonNull;
  17
  18 /// A `Waker` is a handle for waking up a task by notifying its executor that it
  19 /// is ready to be run.
  20 ///
  21 /// This handle contains a trait object pointing to an instance of the `UnsafeWake`
  22 /// trait, allowing notifications to get routed through it.
  23 #[repr(transparent)]
  24 pub struct Waker {
  25     inner: NonNull<UnsafeWake>,
  26 }
  27
  28 unsafe impl Send for Waker {}
  29 unsafe impl Sync for Waker {}
  30
  31 impl Waker {
  32     /// Constructs a new `Waker` directly.
  33     ///
  34     /// Note that most code will not need to call this. Implementers of the
  35     /// `UnsafeWake` trait will typically provide a wrapper that calls this
  36     /// but you otherwise shouldn't call it directly.
  37     ///
  38     /// If you're working with the standard library then it's recommended to
  39     /// use the `Waker::from` function instead which works with the safe
  40     /// `Arc` type and the safe `Wake` trait.
  41     #[inline]
  42     pub unsafe fn new(inner: NonNull<UnsafeWake>) -> Self {
  43         Waker { inner: inner }
  44     }
  45
  46     /// Wake up the task associated with this `Waker`.
  47     #[inline]
  48     pub fn wake(&self) {
  49         unsafe { self.inner.as_ref().wake() }
  50     }
  51
  52     /// Returns whether or not this `Waker` and `other` awaken the same task.
  53     ///
  54     /// This function works on a best-effort basis, and may return false even
  55     /// when the `Waker`s would awaken the same task. However, if this function
  56     /// returns true, it is guaranteed that the `Waker`s will awaken the same
  57     /// task.
  58     ///
  59     /// This function is primarily used for optimization purposes.
  60     #[inline]
  61     pub fn will_wake(&self, other: &Waker) -> bool {
  62         self.inner == other.inner
  63     }
  64 }
  65
  66 impl Clone for Waker {
  67     #[inline]
  68     fn clone(&self) -> Self {
  69         unsafe {
  70             self.inner.as_ref().clone_raw()
  71         }
  72     }
  73 }
  74
  75 impl fmt::Debug for Waker {
  76     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
  77         f.debug_struct("Waker")
  78             .finish()
  79     }
  80 }
  81
  82 impl Drop for Waker {
  83     #[inline]
  84     fn drop(&mut self) {
  85         unsafe {
  86             self.inner.as_ref().drop_raw()
  87         }
  88     }
  89 }
  90
  91 /// A `LocalWaker` is a handle for waking up a task by notifying its executor that it
  92 /// is ready to be run.
  93 ///
  94 /// This is similar to the `Waker` type, but cannot be sent across threads.
  95 /// Task executors can use this type to implement more optimized singlethreaded wakeup
  96 /// behavior.
  97 #[repr(transparent)]
  98 pub struct LocalWaker {
  99     inner: NonNull<UnsafeWake>,
 100 }
 101
 102 impl !Send for LocalWaker {}
 103 impl !Sync for LocalWaker {}
 104
 105 impl LocalWaker {
 106     /// Constructs a new `LocalWaker` directly.
 107     ///
 108     /// Note that most code will not need to call this. Implementers of the
 109     /// `UnsafeWake` trait will typically provide a wrapper that calls this
 110     /// but you otherwise shouldn't call it directly.
 111     ///
 112     /// If you're working with the standard library then it's recommended to
 113     /// use the `LocalWaker::from` function instead which works with the safe
 114     /// `Rc` type and the safe `LocalWake` trait.
 115     ///
 116     /// For this function to be used safely, it must be sound to call `inner.wake_local()`
 117     /// on the current thread.
 118     #[inline]
 119     pub unsafe fn new(inner: NonNull<UnsafeWake>) -> Self {
 120         LocalWaker { inner: inner }
 121     }
 122
 123     /// Wake up the task associated with this `LocalWaker`.
 124     #[inline]
 125     pub fn wake(&self) {
 126         unsafe { self.inner.as_ref().wake_local() }
 127     }
 128
 129     /// Returns whether or not this `LocalWaker` and `other` `LocalWaker` awaken the same task.
 130     ///
 131     /// This function works on a best-effort basis, and may return false even
 132     /// when the `LocalWaker`s would awaken the same task. However, if this function
 133     /// returns true, it is guaranteed that the `LocalWaker`s will awaken the same
 134     /// task.
 135     ///
 136     /// This function is primarily used for optimization purposes.
 137     #[inline]
 138     pub fn will_wake(&self, other: &LocalWaker) -> bool {
 139         self.inner == other.inner
 140     }
 141
 142     /// Returns whether or not this `LocalWaker` and `other` `Waker` awaken the same task.
 143     ///
 144     /// This function works on a best-effort basis, and may return false even
 145     /// when the `Waker`s would awaken the same task. However, if this function
 146     /// returns true, it is guaranteed that the `LocalWaker`s will awaken the same
 147     /// task.
 148     ///
 149     /// This function is primarily used for optimization purposes.
 150     #[inline]
 151     pub fn will_wake_nonlocal(&self, other: &Waker) -> bool {
 152         self.inner == other.inner
 153     }
 154 }
 155
 156 impl From<LocalWaker> for Waker {
 157     #[inline]
 158     fn from(local_waker: LocalWaker) -> Self {
 159         Waker { inner: local_waker.inner }
 160     }
 161 }
 162
 163 impl Clone for LocalWaker {
 164     #[inline]
 165     fn clone(&self) -> Self {
 166         unsafe {
 167             LocalWaker { inner: self.inner.as_ref().clone_raw().inner }
 168         }
 169     }
 170 }
 171
 172 impl fmt::Debug for LocalWaker {
 173     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 174         f.debug_struct("Waker")
 175             .finish()
 176     }
 177 }
 178
 179 impl Drop for LocalWaker {
 180     #[inline]
 181     fn drop(&mut self) {
 182         unsafe {
 183             self.inner.as_ref().drop_raw()
 184         }
 185     }
 186 }
 187
 188 /// An unsafe trait for implementing custom memory management for a `Waker` or `LocalWaker`.
 189 ///
 190 /// A `Waker` conceptually is a cloneable trait object for `Wake`, and is
 191 /// most often essentially just `Arc<dyn Wake>`. However, in some contexts
 192 /// (particularly `no_std`), it's desirable to avoid `Arc` in favor of some
 193 /// custom memory management strategy. This trait is designed to allow for such
 194 /// customization.
 195 ///
 196 /// When using `std`, a default implementation of the `UnsafeWake` trait is provided for
 197 /// `Arc<T>` where `T: Wake` and `Rc<T>` where `T: LocalWake`.
 198 ///
 199 /// Although the methods on `UnsafeWake` take pointers rather than references,
 200 pub unsafe trait UnsafeWake: Send + Sync {
 201     /// Creates a clone of this `UnsafeWake` and stores it behind a `Waker`.
 202     ///
 203     /// This function will create a new uniquely owned handle that under the
 204     /// hood references the same notification instance. In other words calls
 205     /// to `wake` on the returned handle should be equivalent to calls to
 206     /// `wake` on this handle.
 207     ///
 208     /// # Unsafety
 209     ///
 210     /// This function is unsafe to call because it's asserting the `UnsafeWake`
 211     /// value is in a consistent state, i.e. hasn't been dropped.
 212     unsafe fn clone_raw(&self) -> Waker;
 213
 214     /// Drops this instance of `UnsafeWake`, deallocating resources
 215     /// associated with it.
 216     ///
 217     /// FIXME(cramertj)
 218     /// This method is intended to have a signature such as:
 219     ///
 220     /// ```ignore (not-a-doctest)
 221     /// fn drop_raw(self: *mut Self);
 222     /// ```
 223     ///
 224     /// Unfortunately in Rust today that signature is not object safe.
 225     /// Nevertheless it's recommended to implement this function *as if* that
 226     /// were its signature. As such it is not safe to call on an invalid
 227     /// pointer, nor is the validity of the pointer guaranteed after this
 228     /// function returns.
 229     ///
 230     /// # Unsafety
 231     ///
 232     /// This function is unsafe to call because it's asserting the `UnsafeWake`
 233     /// value is in a consistent state, i.e. hasn't been dropped.
 234     unsafe fn drop_raw(&self);
 235
 236     /// Indicates that the associated task is ready to make progress and should
 237     /// be `poll`ed.
 238     ///
 239     /// Executors generally maintain a queue of "ready" tasks; `wake` should place
 240     /// the associated task onto this queue.
 241     ///
 242     /// # Panics
 243     ///
 244     /// Implementations should avoid panicking, but clients should also be prepared
 245     /// for panics.
 246     ///
 247     /// # Unsafety
 248     ///
 249     /// This function is unsafe to call because it's asserting the `UnsafeWake`
 250     /// value is in a consistent state, i.e. hasn't been dropped.
 251     unsafe fn wake(&self);
 252
 253     /// Indicates that the associated task is ready to make progress and should
 254     /// be `poll`ed. This function is the same as `wake`, but can only be called
 255     /// from the thread that this `UnsafeWake` is "local" to. This allows for
 256     /// implementors to provide specialized wakeup behavior specific to the current
 257     /// thread. This function is called by `LocalWaker::wake`.
 258     ///
 259     /// Executors generally maintain a queue of "ready" tasks; `wake_local` should place
 260     /// the associated task onto this queue.
 261     ///
 262     /// # Panics
 263     ///
 264     /// Implementations should avoid panicking, but clients should also be prepared
 265     /// for panics.
 266     ///
 267     /// # Unsafety
 268     ///
 269     /// This function is unsafe to call because it's asserting the `UnsafeWake`
 270     /// value is in a consistent state, i.e. hasn't been dropped, and that the
 271     /// `UnsafeWake` hasn't moved from the thread on which it was created.
 272     unsafe fn wake_local(&self) {
 273         self.wake()
 274     }
 275 }