pub trait Future { typeOutput; // Required method fnpoll(self:Pin<&mut Self>, cx: &mutContext<'_>) ->Poll<Self::Output>;}Expand description
A future represents an asynchronous computation, commonly obtained by use ofasync.
A future is a value that might not have finished computing yet. This kind of“asynchronous value” makes it possible for a thread to continue doing usefulwork while it waits for the value to become available.
§Thepoll method
The core method of future,poll,attempts to resolve the future into afinal 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 makefurther progress bypolling again. Thecontext passed to thepollmethod can provide aWaker, which is a handle for waking up the currenttask.
When using a future, you generally won’t callpoll directly, but instead.await the value.
Required Associated Types§
Required Methods§
1.36.0 ·Sourcefnpoll(self:Pin<&mut Self>, cx: &mutContext<'_>) ->Poll<Self::Output>
fnpoll(self:Pin<&mut Self>, cx: &mutContext<'_>) ->Poll<Self::Output>
Attempts to resolve the future to a final value, registeringthe current task for wakeup if the value is not yet available.
§Return value
This function returns:
Poll::Pendingif the future is not ready yetPoll::Ready(val)with the resultvalof this future if itfinished successfully.
Once a future has finished, clients should notpoll it again.
When a future is not ready yet,poll returnsPoll::Pending andstores a clone of theWaker copied from the currentContext.ThisWaker is then woken once the future can make progress.For example, a future waiting for a socket to becomereadable would call.clone() on theWaker 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 topoll the futureagain, which may or may not produce a final value.
Note that on multiple calls topoll, only theWaker from theContext passed to the most recent call should be scheduled toreceive a wakeup.
§Runtime characteristics
Futures alone areinert; they must beactivelypolled for theunderlying computation to make progress, meaning that each time thecurrent task is woken up, it should actively re-poll pending futuresthat it still has an interest in.
Having said that, some Futures may represent a value that is beingcomputed in a different task. In this case, the future’s underlyingcomputation is simply acting as a conduit for a value being computedby that other task, which will proceed independently of the Future.Futures of this kind are typically obtained when spawning a new task into anasync runtime.
Thepoll function should not be called repeatedly in a tight loop –instead, it should only be called when the future indicates that it isready to make progress (by callingwake()). If you’re familiar with thepoll(2) orselect(2) syscalls on Unix it’s worth noting that futurestypically donot suffer the same problems of “all wakeups must pollall events”; they are more likeepoll(4).
An implementation ofpoll should strive to return quickly, and shouldnot block. Returning quickly prevents unnecessarily clogging upthreads or event loops. If it is known ahead of time that a call topoll may end up taking a while, the work should be offloaded to athread pool (or something similar) to ensure thatpoll can returnquickly.
§Panics
Once a future has completed (returnedReady frompoll), calling itspoll method again may panic, block forever, or cause other kinds ofproblems; theFuture trait places no requirements on the effects ofsuch a call. However, as thepoll method is not markedunsafe,Rust’s usual rules apply: calls must never cause undefined behavior(memory corruption, incorrect use ofunsafe functions, or the like),regardless of the future’s state.