Skip to content
Tutorials Center
My learning

Topics

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.

Rust
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

Rust A hand-written future and a minimal executor

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.

Rust ready, poll_fn and the noop waker

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

Rust
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, .await it or poll it.
  • Wake before returning Pending. If a future returns Pending without arranging a wake-up, the executor may never poll it again and the task hangs. Countdown above calls wake_by_ref itself.
  • Do not poll after Ready. The result is unspecified for hand-written futures; async blocks panic on this.
  • Pin is needed because async state machines may point into themselves. Use pin! (stable macro) for stack pinning or Box::pin for 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, spawn and channels for async code come from crates; mixing two runtimes in one program usually needs care.
  • async fn in traits is stable (since 1.75), as are async closures (since 1.85).
  • Send futures: a future is Send only if everything held across an .await is Send; holding an Rc or a MutexGuard across an await is the usual cause of errors in spawned tasks.