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