Rust Reference ยท Standard Library Modules
The std::future and std::task modules
Reference for Rust std::future and std::task: the Future trait, Poll, Context, Waker, the Wake trait, ready, poll_fn and IntoFuture, with a tiny executor.
Rust's async support has a deliberately small standard library part. std::future defines the Future trait, which models a value that will be ready later. std::task defines Poll, Context and Waker, the pieces an executor and a future use to coordinate. The standard library contains no executor, timer or I/O reactor; those come from runtimes such as Tokio. This page covers what the language gives you.
A future does nothing until polled. poll returns Poll::Ready(value) if it is done, or Poll::Pending after arranging for the Waker in the Context to be called when progress is possible. An async fn compiles to a state machine that implements Future, and .await polls the inner future in a loop.
use std::future::Future; use std::pin::Pin; use std::task::{Context, Poll}; trait Sketch { type Output; fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>; }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.
Syntax
pub trait Future { type Output; fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>; } pub enum Poll<T> { Ready(T), Pending }
| Item | Description |
|---|---|
Future |
The trait behind async. Takes Pin<&mut Self> so the future may hold self-references. |
IntoFuture |
What .await calls first; lets types (like builders) be awaited directly. |
ready(v), pending() |
A future ready immediately, or one that never finishes. |
poll_fn(f) |
A future from FnMut(&mut Context) -> Poll<T> (stable since 1.64). |
Poll<T> |
Ready(T) / Pending; methods is_ready, is_pending, map. |
Context |
Carries the Waker (cx.waker()). |
Waker |
Handle to wake a task: wake, wake_by_ref, clone, will_wake; Waker::noop() (stable since 1.85). |
Wake |
Safe trait: implement wake on an Arc<T> and convert with Waker::from. |
RawWaker, RawWakerVTable |
The unsafe, allocation-free way to build a Waker. |
ready!(expr) |
Macro: returns Pending early if expr is pending, otherwise yields the value. |
Usage notes
- Futures are lazy. Creating one does no work; spawn it,
.awaitit or poll it. - Wake before returning
Pending. If a future returnsPendingwithout arranging a wake-up, the executor may never poll it again and the task hangs.Countdownabove callswake_by_refitself. - Do not poll after
Ready. The result is unspecified for hand-written futures;asyncblocks panic on this. Pinis needed becauseasyncstate machines may point into themselves. Usepin!(stable macro) for stack pinning orBox::pinfor the heap.- No blocking in
poll. Long computation or blocking I/O stalls the executor thread; hand it to a thread pool. - A runtime is separate. Timers, sockets,
spawnand channels for async code come from crates; mixing two runtimes in one program usually needs care. async fnin traits is stable (since 1.75), as areasyncclosures (since 1.85).Sendfutures: a future isSendonly if everything held across an.awaitisSend; holding anRcor aMutexGuardacross an await is the usual cause of errors in spawned tasks.