The Rust Async Model

Async/await in Rust looks similar to async/await in JavaScript or C#, but the mechanism underneath is fundamentally different, and that difference explains most of the surprising behavior newcomers hit: futures that "do nothing" until awaited, a compile error mentioning Pin, or confusion about why async fn main needs an attribute macro at all. Rust's async model is built from one trait, Future, and a deliberate choice to ship no runtime in the standard library.

This page is the conceptual anchor for the rest of the async-futures section. The other pages here cover specific mechanics: the Future trait's poll method, executors, pinning, streams, and cancellation. This one ties them together into a single mental model: futures as lazy state machines, executors as the thing that drives them, and pinning as a structural consequence of how the compiler builds those state machines.

Summary

• async fn and async blocks compile to anonymous types implementing the Future trait, a state machine that makes progress only when something calls poll on it.
• Insight: This design lets Rust run huge numbers of concurrent operations on a small thread pool with zero per-task heap allocation by default, at the cost of needing an external runtime to actually execute anything.
• Key Concepts: Future, poll, executor, waker, state machine, Pin.
• When to Use: Understanding this model matters whenever you debug a stuck task, choose a runtime, write a custom Future, or hit a Send/Pin compiler error you don't immediately recognize.
• Limitations/Trade-offs: The lazy, no-runtime design pushes real complexity, scheduling, I/O readiness, timers, out to third-party crates, so "async Rust" always really means "async Rust plus a runtime."
• Related Topics: the Future trait's poll contract, executors and runtimes, pinning and Unpin, cooperative task scheduling.

Foundations

The single most important fact about Rust futures is that they are lazy. Creating a value with an async block or calling an async fn does no work at all; it just builds a value. Work only happens when that value is polled, and polling is not something application code typically does directly, an executor does it.

This is a deliberate departure from JavaScript's promises, which begin executing the moment they are created. A Rust future is closer to an unstarted iterator: let fut = fetch_data(); allocates a state machine and does nothing else, exactly as let iter = vec.iter(); produces an iterator that has not yet touched an element.

Every async fn and async block is syntax sugar. The compiler transforms the function body into an anonymous struct that implements the Future trait, with the body's local variables becoming the struct's fields and each .await point becoming a possible pause state. Conceptually:

// async fn fetch() -> u32 { let x = step_one().await; step_two(x).await }
// compiles to roughly an enum like:
enum FetchState {
    Start,
    WaitingOnStepOne { /* captured locals */ },
    WaitingOnStepTwo { x: u32 },
    Done,
}

This state machine has one method that matters: poll, which either returns Poll::Ready(value) when the work is complete, or Poll::Pending when it needs to wait on something, an incoming network byte, a timer, another future. async/await is just a convenient way to write that state machine by hand without actually writing an enum and a match statement yourself.

Mechanics & Interactions

A Future cannot make itself run faster by wishing; it needs something outside itself calling poll repeatedly until it returns Poll::Ready. That something is an executor, and the Rust standard library deliberately does not provide one.

This split is intentional and mirrors a broader pattern in the language: the standard library defines the trait (the contract), and the ecosystem provides implementations tuned for different environments. Tokio, async-std, smol, and embedded runtimes like Embassy all implement the same Future contract differently, one optimized for servers with thread pools, another for microcontrollers with no heap at all. A library that only uses async fn and never spawns a runtime itself can run under any of them.

Polling on its own would be wasteful if the executor just called poll in a tight loop, so a second mechanism completes the picture: the waker. When a future returns Poll::Pending, it is handed a Waker as part of the polling context, and it is responsible for calling that waker later, typically from an I/O callback or a timer, to tell the executor "poll me again, I might be ready now." This waker handoff is what lets an executor park a task efficiently instead of spinning, and it is the same mechanism whether the future is waiting on a TCP socket or a five-second timer.

use std::future::Future;
use std::pin::Pin;
use std::task::{Context, Poll};
 
struct Ready(bool);
impl Future for Ready {
    type Output = ();
    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
        if self.0 { Poll::Ready(()) } else {
            cx.waker().wake_by_ref(); // ask to be polled again
            Poll::Pending
        }
    }
}

The poll signature above hides a detail that trips up nearly everyone the first time they see it: self: Pin<&mut Self> instead of the ordinary &mut self. This is where pinning enters the picture, and it is a direct structural consequence of the state machine transformation described in Foundations.

Consider an async block that borrows one of its own local variables across an .await, something like let buf = [0u8; 64]; let n = reader.read(&mut buf).await; followed by later code that reads buf again. The compiler's generated state machine has to store both buf and a reference to buf as fields of the same struct, which makes the struct self-referential: one field points into another field of the same value. Ordinary Rust values can be moved freely (a memcpy under the hood), but moving a self-referential struct invalidates the internal pointer, since it would now point at the old memory location instead of the new one. Pin<P> is a pointer wrapper that promises the compiler "the value behind this pointer will never move again," which is exactly the guarantee a self-referential state machine needs to be sound.

Advanced Considerations & Applications

Most application code never writes Pin explicitly, because .await pins futures on the stack automatically, and this is by design: pinning is a mechanism the language needs, not an API most users are meant to interact with directly. It surfaces in three recurring situations: implementing a Future by hand, storing a future inside a struct field (which requires Pin<Box<dyn Future<...>>> since a struct field cannot be pinned to the stack the way a local variable can), and reading a !Unpin compiler error, which usually means a future got moved after something already started polling it.

The Unpin auto trait is the escape hatch that keeps pinning from being painful for the common case. Almost all ordinary Rust types are Unpin, meaning moving them after pinning is fine, since they hold no self-references. Only generated async state machines, and hand-written self-referential types, are typically !Unpin, and only those actually need the discipline Pin enforces.

Runtimes build meaningfully different scheduling and I/O models on top of the same Future contract, and the choice has real operational consequences, not just API differences.

The lazy, poll-based design has direct consequences for cancellation, which is worth naming explicitly because it differs from thread-based cancellation. Dropping a future at any await point simply stops polling it, there is no signal delivered to "interrupt" work in progress the way a thread might receive a signal. This makes cancellation cheap and structural (drop the future, its Drop impl runs, resources are freed), but it also means cancellation safety, whether a partially completed operation leaves data in a consistent state, is something the future's author has to design for explicitly rather than something the runtime guarantees automatically.

Common Misconceptions

• "Calling an async function starts the work immediately." It builds a lazy Future value and does nothing else; work begins only once something polls it, typically by awaiting it or spawning it on an executor.
• "Rust's standard library includes an async runtime." It defines the Future trait and the polling contract, but ships no executor at all; every real async program depends on a runtime crate like Tokio.
• "Pin means the same thing as immutable." Pin only prevents a value's memory address from changing; the value can still be mutated in place through Pin::as_mut or safe methods that don't move it.
• "You always need to think about Pin when writing async code." .await pins values on the stack automatically for you; Pin becomes visible mainly when implementing Future manually or storing a future inside another struct.
• "async/await is a special runtime feature, not 'real' code." It is ordinary syntax sugar around a state machine implementing an ordinary trait; there is no hidden runtime magic beyond the poll/Waker protocol itself.
• "Dropping a future cancels it the same way killing a thread does." Dropping simply stops polling and runs Drop; there is no interrupt signal, so any partial side effects already performed before the drop point are not automatically undone.

FAQs

Related

• The Future Trait - the poll contract in full detail, with a hand-written Future example.
• Executors & Runtimes - what drives polling, and how Tokio's flavors differ.
• Pinning & Unpin - the Pin API and self-referential futures in depth.
• Async Basics - hands-on async/await examples building on this model.
• Streams - the async equivalent of an iterator, built on the same polling model.

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.