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 use task::{Poll, LocalWaker};
20 /// A future represents an asychronous computation.
22 /// A future is a value that may not have finished computing yet. This kind of
23 /// "asynchronous value" makes it possible for a thread to continue doing useful
24 /// work while it waits for the value to become available.
26 /// # The `poll` method
28 /// The core method of future, `poll`, *attempts* to resolve the future into a
29 /// final value. This method does not block if the value is not ready. Instead,
30 /// the current task is scheduled to be woken up when it's possible to make
31 /// further progress by `poll`ing again. The wake up is performed using
32 /// `cx.waker()`, a handle for waking up the current task.
34 /// When using a future, you generally won't call `poll` directly, but instead
35 /// `await!` the value.
37 /// The result of the `Future`.
40 /// Attempt to resolve the future to a final value, registering
41 /// the current task for wakeup if the value is not yet available.
45 /// This function returns:
47 /// - [`Poll::Pending`] if the future is not ready yet
48 /// - [`Poll::Ready(val)`] with the result `val` of this future if it
49 /// finished successfully.
51 /// Once a future has finished, clients should not `poll` it again.
53 /// When a future is not ready yet, `poll` returns `Poll::Pending` and
54 /// stores a clone of the [`LocalWaker`] to be woken once the future can
55 /// make progress. For example, a future waiting for a socket to become
56 /// readable would call `.clone()` on the [`LocalWaker`] and store it.
57 /// When a signal arrives elsewhere indicating that the socket is readable,
58 /// `[LocalWaker::wake]` is called and the socket future's task is awoken.
59 /// Once a task has been woken up, it should attempt to `poll` the future
60 /// again, which may or may not produce a final value.
62 /// Note that on multiple calls to `poll`, only the most recent
63 /// [`LocalWaker`] passed to `poll` should be scheduled to receive a
66 /// # Runtime characteristics
68 /// Futures alone are *inert*; they must be *actively* `poll`ed to make
69 /// progress, meaning that each time the current task is woken up, it should
70 /// actively re-`poll` pending futures that it still has an interest in.
72 /// The `poll` function is not called repeatedly in a tight loop-- instead,
73 /// it should only be called when the future indicates that it is ready to
74 /// make progress (by calling `wake()`). If you're familiar with the
75 /// `poll(2)` or `select(2)` syscalls on Unix it's worth noting that futures
76 /// typically do *not* suffer the same problems of "all wakeups must poll
77 /// all events"; they are more like `epoll(4)`.
79 /// An implementation of `poll` should strive to return quickly, and must
80 /// *never* block. Returning quickly prevents unnecessarily clogging up
81 /// threads or event loops. If it is known ahead of time that a call to
82 /// `poll` may end up taking awhile, the work should be offloaded to a
83 /// thread pool (or something similar) to ensure that `poll` can return
86 /// # [`LocalWaker`], [`Waker`] and thread-safety
88 /// The `poll` function takes a [`LocalWaker`], an object which knows how to
89 /// awaken the current task. [`LocalWaker`] is not `Send` nor `Sync`, so in
90 /// order to make thread-safe futures the [`LocalWaker::into_waker`] method
91 /// should be used to convert the [`LocalWaker`] into a thread-safe version.
92 /// [`LocalWaker::wake`] implementations have the ability to be more
93 /// efficient, however, so when thread safety is not necessary,
94 /// [`LocalWaker`] should be preferred.
98 /// Once a future has completed (returned `Ready` from `poll`),
99 /// then any future calls to `poll` may panic, block forever, or otherwise
100 /// cause bad behavior. The `Future` trait itself provides no guarantees
101 /// about the behavior of `poll` after a future has completed.
103 /// [`Poll::Pending`]: ../task/enum.Poll.html#variant.Pending
104 /// [`Poll::Ready(val)`]: ../task/enum.Poll.html#variant.Ready
105 /// [`LocalWaker`]: ../task/struct.LocalWaker.html
106 /// [`LocalWaker::into_waker`]: ../task/struct.LocalWaker.html#method.into_waker
107 /// [`LocalWaker::wake`]: ../task/struct.LocalWaker.html#method.wake
108 /// [`Waker`]: ../task/struct.Waker.html
109 fn poll(self: Pin<&mut Self>, lw: &LocalWaker) -> Poll<Self::Output>;
112 impl<'a, F: ?Sized + Future + Unpin> Future for &'a mut F {
113 type Output = F::Output;
115 fn poll(mut self: Pin<&mut Self>, lw: &LocalWaker) -> Poll<Self::Output> {
116 F::poll(Pin::new(&mut **self), lw)
120 impl<P> Future for Pin<P>
125 type Output = <<P as ops::Deref>::Target as Future>::Output;
127 fn poll(self: Pin<&mut Self>, lw: &LocalWaker) -> Poll<Self::Output> {
128 Pin::get_mut(self).as_mut().poll(lw)