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.
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.
11 #![unstable(feature = "futures_api",
12 reason = "futures in libcore are unstable",
18 /// A `Waker` is a handle for waking up a task by notifying its executor that it
19 /// is ready to be run.
21 /// This handle contains a trait object pointing to an instance of the `UnsafeWake`
22 /// trait, allowing notifications to get routed through it.
25 inner: NonNull<UnsafeWake>,
28 unsafe impl Send for Waker {}
29 unsafe impl Sync for Waker {}
32 /// Constructs a new `Waker` directly.
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.
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.
42 pub unsafe fn new(inner: NonNull<UnsafeWake>) -> Self {
43 Waker { inner: inner }
46 /// Wake up the task associated with this `Waker`.
49 unsafe { self.inner.as_ref().wake() }
52 /// Returns whether or not this `Waker` and `other` awaken the same task.
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
59 /// This function is primarily used for optimization purposes.
61 pub fn will_wake(&self, other: &Waker) -> bool {
62 self.inner == other.inner
66 impl Clone for Waker {
68 fn clone(&self) -> Self {
70 self.inner.as_ref().clone_raw()
75 impl fmt::Debug for Waker {
76 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
77 f.debug_struct("Waker")
86 self.inner.as_ref().drop_raw()
91 /// A `LocalWaker` is a handle for waking up a task by notifying its executor that it
92 /// is ready to be run.
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
98 pub struct LocalWaker {
99 inner: NonNull<UnsafeWake>,
102 impl !Send for LocalWaker {}
103 impl !Sync for LocalWaker {}
106 /// Constructs a new `LocalWaker` directly.
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.
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.
116 /// For this function to be used safely, it must be sound to call `inner.wake_local()`
117 /// on the current thread.
119 pub unsafe fn new(inner: NonNull<UnsafeWake>) -> Self {
120 LocalWaker { inner: inner }
123 /// Wake up the task associated with this `LocalWaker`.
126 unsafe { self.inner.as_ref().wake_local() }
129 /// Returns whether or not this `LocalWaker` and `other` `LocalWaker` awaken the same task.
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
136 /// This function is primarily used for optimization purposes.
138 pub fn will_wake(&self, other: &LocalWaker) -> bool {
139 self.inner == other.inner
142 /// Returns whether or not this `LocalWaker` and `other` `Waker` awaken the same task.
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
149 /// This function is primarily used for optimization purposes.
151 pub fn will_wake_nonlocal(&self, other: &Waker) -> bool {
152 self.inner == other.inner
156 impl From<LocalWaker> for Waker {
158 fn from(local_waker: LocalWaker) -> Self {
159 Waker { inner: local_waker.inner }
163 impl Clone for LocalWaker {
165 fn clone(&self) -> Self {
167 LocalWaker { inner: self.inner.as_ref().clone_raw().inner }
172 impl fmt::Debug for LocalWaker {
173 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
174 f.debug_struct("Waker")
179 impl Drop for LocalWaker {
183 self.inner.as_ref().drop_raw()
188 /// An unsafe trait for implementing custom memory management for a `Waker` or `LocalWaker`.
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
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`.
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`.
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.
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;
214 /// Drops this instance of `UnsafeWake`, deallocating resources
215 /// associated with it.
218 /// This method is intended to have a signature such as:
220 /// ```ignore (not-a-doctest)
221 /// fn drop_raw(self: *mut Self);
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.
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);
236 /// Indicates that the associated task is ready to make progress and should
239 /// Executors generally maintain a queue of "ready" tasks; `wake` should place
240 /// the associated task onto this queue.
244 /// Implementations should avoid panicking, but clients should also be prepared
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);
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`.
259 /// Executors generally maintain a queue of "ready" tasks; `wake_local` should place
260 /// the associated task onto this queue.
264 /// Implementations should avoid panicking, but clients should also be prepared
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) {