Async/Await State Machines
async/await is one of Rust's hairier features. An async fn doesn't run code when called — it builds a state machine that implements the Future trait. We'll crack open what the compiler emits: the state-machine enum, the poll function, and the executor wiring that drags it all forward.
What async fn Actually Returns
async fn fetch_data(url: &str) -> String { let response = make_request(url).await; let body = read_body(response).await; body}Roughly speaking, the compiler rewrites that into:
// What the compiler generates (conceptual):struct FetchDataFuture<'a> { state: State<'a>,}
enum State<'a> { // State 0: Haven't started yet (rustc calls this "Unresumed") Start { url: &'a str },
// State 1: Waiting for make_request to complete WaitingForRequest { url: &'a str, request_future: MakeRequestFuture<'a>, },
// State 2: Waiting for read_body to complete WaitingForBody { body_future: ReadBodyFuture, },
// State 3: Completed (rustc calls this "Returned"; it also adds a // "Panicked" state for a future whose poll panicked) Done,}
impl<'a> Future for FetchDataFuture<'a> { type Output = String;
fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<String> { loop { match self.state { State::Start { url } => { let fut = make_request(url); self.state = State::WaitingForRequest { url, request_future: fut }; } State::WaitingForRequest { request_future, .. } => { match request_future.poll(cx) { Poll::Ready(response) => { let fut = read_body(response); self.state = State::WaitingForBody { body_future: fut }; } Poll::Pending => return Poll::Pending, } } State::WaitingForBody { body_future } => { match body_future.poll(cx) { Poll::Ready(body) => { self.state = State::Done; return Poll::Ready(body); } Poll::Pending => return Poll::Pending, } } State::Done => panic!("polled after completion"), } } }}The State Machine in Assembly
The generated poll function compiles to a state dispatch. The listing is schematic: rdi_inner, rsi_inner and offset are placeholders, not real x86, and returning the Poll in eax is a simplification. A Poll<String> is too big for registers, so real code writes it through a hidden return pointer, with the layout depending on T.
; poll function for FetchDataFuture; rdi = pointer to the future (self), rsi = context pointerpoll_fetch_data: ; Load current state mov eax, DWORD PTR [rdi] ; State discriminant
cmp eax, 0 je .state_start cmp eax, 1 je .state_waiting_request cmp eax, 2 je .state_waiting_body ; State 3 (Done) would be unreachable
.state_start: ; Transition: create the request future ; Store it in our state struct mov DWORD PTR [rdi], 1 ; Update state to WaitingForRequest ; ... initialize request_future fields ... ; Fall through to poll it immediately
.state_waiting_request: ; Poll the inner request future lea rdi_inner, [rdi+offset] ; Pointer to embedded request_future mov rsi_inner, rsi ; Pass context through call poll_make_request
cmp eax, 0 ; Poll::Ready? jne .return_pending
; Request completed: extract response, create body future mov DWORD PTR [rdi], 2 ; Update state to WaitingForBody ; ... initialize body_future with the response ... ; Fall through to poll it
.state_waiting_body: lea rdi_inner, [rdi+offset] mov rsi_inner, rsi call poll_read_body
cmp eax, 0 ; Poll::Ready? jne .return_pending
; Body received: return Poll::Ready(body) mov DWORD PTR [rdi], 3 ; State = Done ; ... move body to return position ... xor eax, eax ; Return Poll::Ready ret
.return_pending: mov eax, 1 ; Return Poll::Pending retThe Future State Struct Layout
The state-machine struct has to hang onto every local that survives an .await:
async fn example() -> i32 { let a = compute_a().await; // a must survive across the second await let b = compute_b(a).await; a + b}The generated struct looks like:
ExampleFuture: Offset 0: [state discriminant (4 bytes)] Offset 4: [padding (4 bytes)]
- State 0 (Start): no extra fields --
- State 1 (WaitingForA): -- Offset 8: [compute_a_future (N bytes)]
- State 2 (WaitingForB): -- Offset 8: [a: i32 (4 bytes)] <- preserved across await Offset 12: [padding (4 bytes)] Offset 16: [compute_b_future (M bytes)]
Total size: max(state variant sizes) + discriminanta lives in the struct because it's still needed after the second .await. Anything that doesn't cross an await boundary can stay in registers during poll and never bloats the struct.
Comparing to Manual State Machines
Nothing stops you from writing the state machine by hand:
enum ManualState { Start, WaitingA { future_a: FutureA }, WaitingB { a: i32, future_b: FutureB }, Done,}
struct ManualFuture { state: ManualState,}
impl Future for ManualFuture { type Output = i32;
fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<i32> { // ... match on state, poll inner futures, transition states ... }}The compiler-generated version comes out in much the same shape. It does carry a few extra states of its own (not started, returned and panicked), so polling a finished future panics cleanly instead of misbehaving. async/await is sugar for this pattern — you're just not paying for it in keystrokes.
The runner's Rust 1.40 compiles in the 2015 edition, which has no async fn, but Future, Poll and Context are all in std. That's enough to hand-write the state machine for example() and drive it with a ten-line block_on. Each inner future returns Pending once before it's ready, the way a real one would while waiting on I/O.
How the Executor Drives Futures
An executor like Tokio is, at its core, a loop that polls futures repeatedly:
// Simplified executor loop (conceptual):fn run_executor(mut future: Pin<Box<dyn Future<Output = ()>>>) { let waker = create_waker(); let mut cx = Context::from_waker(&waker);
loop { match future.as_mut().poll(&mut cx) { Poll::Ready(()) => break, // Done! Poll::Pending => wait_for_wakeup(), // Sleep until something happens } }}In assembly, that boils down to a loop calling the future's poll through a vtable (we're behind dyn Future). Pin<Box<dyn Future>> is a fat pointer, two words: the data pointer and the vtable pointer. The vtable lives in the pointer, not in the future's own memory:
; rbx = data pointer, r13 = vtable pointer (the two halves of the Box)executor_loop: ; Poll the future mov rdi, rbx ; self = the pinned future mov rsi, r12 ; cx = the context call QWORD PTR [r13+POLL_OFFSET] ; Call poll through vtable
test eax, eax ; Poll::Ready (0) or Pending (1)? jne .wait_for_wakeup
; Future completed ret
.wait_for_wakeup: ; Block until the waker is invoked (epoll, io_uring, etc.) call park_thread jmp executor_loop ; Poll againPut that loop together with FetchDataFuture from the top of the lesson and one run looks like this. The notes mark the state transitions; watch url disappear from the struct once the request future has finished with it. Where each future returns Pending is illustrative, since that depends on the network.
Every arrow into F is a fresh call to poll. Nothing is suspended on a stack between them. The only memory of where it was is the state discriminant and whichever fields that state keeps.
The Size of Async State Machines
Every .await point has the potential to grow the generated future:
async fn small() -> i32 { 42 // No await: future is tiny (just the state byte)}
async fn medium() -> String { let s = async_read().await; // One await: stores the inner future s}
async fn large() -> Vec<u8> { let a = step1().await; // Each await may add fields let b = step2(a).await; let c = step3(a, b).await; // a and b must be preserved c}You can check future sizes. impl Future can't be named in a turbofish, so measure a value instead:
let fut = large(); // Builds the state machine; nothing runs yetprintln!("{}", std::mem::size_of_val(&fut)); // Its size in bytesSprawling async functions with lots of locals living across await points produce sprawling state machines. Reason enough to keep async functions tight and avoid stashing large values across an .await.
Pin and Self-Referential Structs
Pin enters the picture because the state machine can hold self-references:
async fn self_referential() { let data = vec![1, 2, 3]; let reference = &data; // reference points into data some_async_op().await; // Both data and reference must be preserved println!("{:?}", reference); // reference must still be valid}After the .await, the future struct holds both data (a Vec) and reference (a pointer into data). Move that struct around in memory and reference becomes a dangling pointer aimed at wherever data used to live. Pin blocks the move once polling starts.
In assembly, Pin adds nothing. It's a compile-time constraint, same family as lifetimes. The codegen is identical with or without it.
Async Overhead: What You Pay
| Aspect | Cost |
|---|---|
| Creating a future | Allocating the state struct (stack or heap) |
| Each poll call | Function call + state dispatch (a few comparisons) |
| State transitions | Writing the new discriminant + moving data |
| Pin | Zero runtime cost |
| Waker/Context | One pointer passed through |
| Executor overhead | One vtable call per poll + parking/unparking |
For I/O-bound work — network, file system — the polling overhead is rounding error next to the actual latency. For CPU-bound work, the polling cost is real, which is why heavy crunching belongs on threads or behind spawn_blocking.
Key Takeaways
-
async fngenerates a state-machine enum. Each.awaitbecomes a state. Locals that cross await boundaries live in the enum's variants. -
pollis a state dispatch. It matches on the current state, polls the inner future, and bumps the state on completion. -
The generated code looks like a hand-written state machine.
async/awaitis sugar for the same pattern, plus a couple of bookkeeping states (returned, panicked) that you'd probably skip by hand. -
Pinhas zero runtime cost. A compile-time constraint that stops self-referential futures from moving. -
Future size grows with state. Anything living across
.awaitends up in the struct. Trim cross-await state and the future shrinks.