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.
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
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.
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
Pendingmust have arranged a wake-up. Otherwise the executor never polls it again and the task hangs. - Do not block in async code.
thread::sleepor 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. asyncblocks capture variables like closures; addmoveto take ownership. Borrowing across.awaitmakes the future!Sendonly if the borrowed type is notSend.- Recursion in
async fnneeds boxing (Box::pin) because the state machine would otherwise have infinite size. - Async traits:
async fnin traits is stable (Rust 1.75), but using it withdyn Traitstill 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.