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