]>
Commit | Line | Data |
---|---|---|
48663c56 | 1 | #![stable(feature = "futures_api", since = "1.36.0")] |
94b46f34 | 2 | |
48663c56 XL |
3 | use crate::marker::Unpin; |
4 | use crate::ops; | |
5 | use crate::pin::Pin; | |
6 | use crate::task::{Context, Poll}; | |
94b46f34 | 7 | |
a1dfa0c6 | 8 | /// A future represents an asynchronous computation. |
94b46f34 XL |
9 | /// |
10 | /// A future is a value that may not have finished computing yet. This kind of | |
11 | /// "asynchronous value" makes it possible for a thread to continue doing useful | |
12 | /// work while it waits for the value to become available. | |
13 | /// | |
14 | /// # The `poll` method | |
15 | /// | |
16 | /// The core method of future, `poll`, *attempts* to resolve the future into a | |
17 | /// final value. This method does not block if the value is not ready. Instead, | |
18 | /// the current task is scheduled to be woken up when it's possible to make | |
48663c56 | 19 | /// further progress by `poll`ing again. The `context` passed to the `poll` |
416331ca | 20 | /// method can provide a [`Waker`], which is a handle for waking up the current |
48663c56 | 21 | /// task. |
94b46f34 XL |
22 | /// |
23 | /// When using a future, you generally won't call `poll` directly, but instead | |
dc9dc135 | 24 | /// `.await` the value. |
416331ca XL |
25 | /// |
26 | /// [`Waker`]: ../task/struct.Waker.html | |
48663c56 XL |
27 | #[must_use = "futures do nothing unless you `.await` or poll them"] |
28 | #[stable(feature = "futures_api", since = "1.36.0")] | |
416331ca | 29 | #[lang = "future_trait"] |
f035d41b | 30 | #[rustc_on_unimplemented(label = "`{Self}` is not a future", message = "`{Self}` is not a future")] |
94b46f34 | 31 | pub trait Future { |
9fa01778 | 32 | /// The type of value produced on completion. |
48663c56 | 33 | #[stable(feature = "futures_api", since = "1.36.0")] |
94b46f34 XL |
34 | type Output; |
35 | ||
36 | /// Attempt to resolve the future to a final value, registering | |
37 | /// the current task for wakeup if the value is not yet available. | |
38 | /// | |
39 | /// # Return value | |
40 | /// | |
41 | /// This function returns: | |
42 | /// | |
8faf50e0 XL |
43 | /// - [`Poll::Pending`] if the future is not ready yet |
44 | /// - [`Poll::Ready(val)`] with the result `val` of this future if it | |
45 | /// finished successfully. | |
94b46f34 XL |
46 | /// |
47 | /// Once a future has finished, clients should not `poll` it again. | |
48 | /// | |
0bf4aa26 | 49 | /// When a future is not ready yet, `poll` returns `Poll::Pending` and |
532ac7d7 XL |
50 | /// stores a clone of the [`Waker`] copied from the current [`Context`]. |
51 | /// This [`Waker`] is then woken once the future can make progress. | |
52 | /// For example, a future waiting for a socket to become | |
9fa01778 | 53 | /// readable would call `.clone()` on the [`Waker`] and store it. |
0bf4aa26 | 54 | /// When a signal arrives elsewhere indicating that the socket is readable, |
48663c56 | 55 | /// [`Waker::wake`] is called and the socket future's task is awoken. |
0bf4aa26 XL |
56 | /// Once a task has been woken up, it should attempt to `poll` the future |
57 | /// again, which may or may not produce a final value. | |
94b46f34 | 58 | /// |
48663c56 XL |
59 | /// Note that on multiple calls to `poll`, only the [`Waker`] from the |
60 | /// [`Context`] passed to the most recent call should be scheduled to | |
61 | /// receive a wakeup. | |
94b46f34 XL |
62 | /// |
63 | /// # Runtime characteristics | |
64 | /// | |
65 | /// Futures alone are *inert*; they must be *actively* `poll`ed to make | |
66 | /// progress, meaning that each time the current task is woken up, it should | |
67 | /// actively re-`poll` pending futures that it still has an interest in. | |
68 | /// | |
9fa01778 | 69 | /// The `poll` function is not called repeatedly in a tight loop -- instead, |
0bf4aa26 XL |
70 | /// it should only be called when the future indicates that it is ready to |
71 | /// make progress (by calling `wake()`). If you're familiar with the | |
94b46f34 XL |
72 | /// `poll(2)` or `select(2)` syscalls on Unix it's worth noting that futures |
73 | /// typically do *not* suffer the same problems of "all wakeups must poll | |
74 | /// all events"; they are more like `epoll(4)`. | |
75 | /// | |
9fa01778 XL |
76 | /// An implementation of `poll` should strive to return quickly, and should |
77 | /// not block. Returning quickly prevents unnecessarily clogging up | |
94b46f34 XL |
78 | /// threads or event loops. If it is known ahead of time that a call to |
79 | /// `poll` may end up taking awhile, the work should be offloaded to a | |
80 | /// thread pool (or something similar) to ensure that `poll` can return | |
81 | /// quickly. | |
82 | /// | |
83 | /// # Panics | |
84 | /// | |
48663c56 XL |
85 | /// Once a future has completed (returned `Ready` from `poll`), calling its |
86 | /// `poll` method again may panic, block forever, or cause other kinds of | |
87 | /// problems; the `Future` trait places no requirements on the effects of | |
88 | /// such a call. However, as the `poll` method is not marked `unsafe`, | |
89 | /// Rust's usual rules apply: calls must never cause undefined behavior | |
90 | /// (memory corruption, incorrect use of `unsafe` functions, or the like), | |
91 | /// regardless of the future's state. | |
8faf50e0 XL |
92 | /// |
93 | /// [`Poll::Pending`]: ../task/enum.Poll.html#variant.Pending | |
94 | /// [`Poll::Ready(val)`]: ../task/enum.Poll.html#variant.Ready | |
532ac7d7 | 95 | /// [`Context`]: ../task/struct.Context.html |
0bf4aa26 | 96 | /// [`Waker`]: ../task/struct.Waker.html |
9fa01778 | 97 | /// [`Waker::wake`]: ../task/struct.Waker.html#method.wake |
48663c56 | 98 | #[stable(feature = "futures_api", since = "1.36.0")] |
532ac7d7 | 99 | fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>; |
94b46f34 XL |
100 | } |
101 | ||
48663c56 | 102 | #[stable(feature = "futures_api", since = "1.36.0")] |
9fa01778 | 103 | impl<F: ?Sized + Future + Unpin> Future for &mut F { |
94b46f34 XL |
104 | type Output = F::Output; |
105 | ||
532ac7d7 XL |
106 | fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> { |
107 | F::poll(Pin::new(&mut **self), cx) | |
94b46f34 XL |
108 | } |
109 | } | |
110 | ||
48663c56 | 111 | #[stable(feature = "futures_api", since = "1.36.0")] |
0bf4aa26 XL |
112 | impl<P> Future for Pin<P> |
113 | where | |
416331ca | 114 | P: Unpin + ops::DerefMut<Target: Future>, |
0bf4aa26 XL |
115 | { |
116 | type Output = <<P as ops::Deref>::Target as Future>::Output; | |
94b46f34 | 117 | |
532ac7d7 XL |
118 | fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> { |
119 | Pin::get_mut(self).as_mut().poll(cx) | |
94b46f34 XL |
120 | } |
121 | } |