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