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