Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Concepts

Async Rust

Reference for async Rust: async fn and blocks, the Future trait, poll, Waker, Pin, why the standard library ships no executor, and how to write a tiny block_on yourself.

An async fn returns a future: a value that represents work that has not finished yet. Nothing runs until something polls the future. .await inside another async context polls a future and, if it is not ready, yields control back to whoever is driving the whole chain. The thing that drives futures is an executor (or runtime).

The standard library defines the pieces (Future, Poll, Context, Waker, Pin, async/await syntax) but deliberately ships no executor and no async I/O, so you choose one from a crate such as Tokio or smol. Our runner has no crates, so the examples below build a minimal executor by hand.

Rust
async fn add(a: i32, b: i32) -> i32 { a + b }
// add(1, 2) is a Future<Output = i32>; it has not run yet.

Try it

Rust A hand-written block_on

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 Futures are lazy

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 A future that returns Pending once

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.

The moving parts

Piece Role
async fn / async {} compiles to a state machine that implements Future
Future::poll(Pin<&mut Self>, &mut Context) -> Poll<Output> makes progress; returns Ready(v) or Pending
.await polls the inner future; on Pending the whole outer future returns Pending
Waker handle the future uses to tell the executor "poll me again"
Pin guarantees the state machine does not move, because it may hold self-references
Executor owns top-level futures and calls poll when woken
Reactor waits for I/O or timers and calls wakers (part of a runtime crate)

Usage notes

  • A future that returns Pending must have arranged a wake-up. Otherwise the executor never polls it again and the task hangs.
  • Do not block in async code. thread::sleep or a blocking read stops the executor thread; use the runtime's async equivalents or a blocking-task pool.
  • Dropping a future cancels it at its current .await, running destructors of everything it holds. Design code to tolerate cancellation.
  • async blocks capture variables like closures; add move to take ownership. Borrowing across .await makes the future !Send only if the borrowed type is not Send.
  • Recursion in async fn needs boxing (Box::pin) because the state machine would otherwise have infinite size.
  • Async traits: async fn in traits is stable (Rust 1.75), but using it with dyn Trait still needs a boxing helper. Async closures are stable as of Rust 1.85.
  • Waker::noop() (stable since Rust 1.85) is handy in tests and tiny demos.
  • Running futures concurrently (join, select, spawning tasks) comes from an executor crate; the standard library only provides the building blocks.
  • Choose async for many mostly-waiting tasks, like network servers. For a handful of CPU-bound jobs, threads are simpler.