async fn and await

A teammate hands you a function marked async and says "try it and print the value." You call it from main, run the program, and nothing happens. No file is opened, no request goes out, exit code 0. Nothing is broken: calling an async fn never runs its body. It builds a value that describes the work and returns that value.

async fn load_config(path: &str) -> String {
    println!("opening {path}");        // not printed yet
    let raw = read_toml(path).await;   // not executed yet
    raw.trim().to_string()
}

fn main() {
    let pending = load_config("app.toml");
    println!("program continues");     // the only line that runs
}

pending is not a String. It is an opaque compiler-generated type implementing Future<Output = String> — a state machine with one variant per suspension point, holding your arguments and locals as fields.

pub trait Future {
    type Output;
    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>;
}

pub enum Poll<T> {
    Ready(T),
    Pending,
}

The executor's whole job fits in a loop you could write yourself:

let mut fut = Box::pin(load_config("app.toml"));
let result = loop {
    match fut.as_mut().poll(&mut cx) {
        Poll::Ready(v) => break v,
        Poll::Pending  => { /* park this task; someone will call us back */ }
    }
};

Everything async in this roadmap terminates in that loop — block_on, tokio::spawn, select!, timeout are all ways of deciding when to call poll and what to do with Pending. Notice what the call site did not do: no thread was created, no lock was taken, no syscall was issued. Constructing a future is pure bookkeeping.

Advancing the machine is what poll does: Pending means "not yet, ask again later," Ready(v) means the output exists and the machine is finished. An executor — for us, the Tokio runtime — owns the loop: call poll, park the task on Pending, re-poll when a waker fires. A future is a recipe; poll is the stove. Until someone polls it, load_config has done nothing beyond moving its arguments into a struct. That also means async fn costs nothing at call time — no thread, no allocation you can see, no syscall.

This laziness produces the most common "my code silently did nothing" bug:

let config = load_config("app.toml");   // no error: binding counts as a use
println!("{config}");                   // E0308: expected String, found opaque type

rustc diagnoses both shapes. A bare statement — load_config("app.toml"); — gets warning: unused Future that must be used, because the Future trait is annotated #[must_use] with the note futures do nothing unless you .await or poll them. Formatting the value gets error[E0308]: mismatched types with a help line pointing at .await. The nastier variant is let _ = load_config("app.toml");: the underscore explicitly discards the value, the warning disappears, and the work never runs — no warning, no error, no config.

The design reason matters in interviews. Futures must be cheap to create and inert before execution, because you assemble them inside select! branches and join! arguments where some other code decides what actually runs. If constructing a future already fired the request, every cancelled race would have hit the network. Laziness is also what makes futures freely movable and storable before they start: a Vec of futures is just a list of plans.

Two things drive a future: .await inside an async context, and tokio::spawn onto a runtime. The Tokio Runtime covers the second option; the next chapter takes apart what .await does at the suspension point. Recall from Send and Sync Marker Traits that whatever the state machine carries decides whether it can move between threads — that inventory starts here.

Interview setup question: "What does an async fn return, and when does its body first execute?" Answer: an opaque impl Future<Output = T>; the body first executes when an executor polls it — at an .await, or after the runtime polls a task you spawned.

Ask ten engineers what .await means and you hear "it waits." Waiting implies a blocked thread; .await blocks nothing. It means: poll the inner future on this task until it returns Ready; if it returns Pending, suspend this function right here and hand Pending upward.

async fn fetch_page(url: &str) -> Page {
    let html = get(url).await;      // suspension point 1
    parse(&html).await              // suspension point 2
}

The sequence:

1. The runtime polls fetch_page. It runs to get(url), which registers interest in the socket with the reactor and returns Pending.
2. Control returns to the executor with Pending. The thread is free for other tasks — url, the inner future, and every local still live are parked inside the state machine, not on a stack frame.
3. When the socket becomes readable, the reactor invokes the waker stored in the Context, and the scheduler re-queues this task.
4. The runtime polls fetch_page again. Execution resumes immediately after the first .await, with html bound to the response. The second .await repeats the cycle.
5. parse returns Ready(page); the outer future returns Ready, and the .await expression evaluates to page.

The Context/Waker pair is how a future says "call me back" without polling in a loop and without the reactor knowing anything about your type. They meet at exactly one point: the waker.

Two consequences interviews probe constantly:

Sequential .await is sequential. fetch_page costs get_time + parse_time. If you want both at once you need two futures polled together — that is join! and select! for Concurrent Futures, not more .awaits.

.await only exists in async context. Writing fut.await in a plain fn or inside std::thread::spawn gives error[E0728]: cannot await outside of an async function. The compiler's suggestion — make the enclosing function async — pushes the suspension point up the call chain, which is exactly how async spreads through a codebase. That pressure is deliberate: each async fn marks a place where the runtime may move execution elsewhere, so every caller must opt in.

There is also a compile-time consequence you will meet again: a &str held across an await lives inside the future, so the future now borrows from its own state. That self-borrow is what makes some futures un-Send — see Send and Sync Marker Traits — and what makes them address-sensitive once polling starts, which is the whole story of Pin and Unpin Explained.

To keep the model sharp, here is what .await does not do: it does not create a thread, it does not poll in a busy loop, and it does not automatically overlap with anything. Awaiting inside an async fn simply nests futures — fetch_page's state machine holds get's state machine, and one poll call drives both, so an awaited operation's latency is added to your own. Getting parallelism means a second task (spawn) or a second branch (join!/select!), never .await alone. The Waker itself is Clone + Send + Sync: futures hand a fresh copy to the reactor on every poll (stored in the Context), so a task can be moved between workers between suspensions and still be wakeable — which is why the runtime is free to schedule your task on any thread.

Finally, .await is a cancellation point in disguise: if the future containing it is dropped while suspended, execution never resumes after that .await. Nothing is interrupted mid-poll; the state machine is simply dropped. Timeouts, Cancellation, and Async I/O turns that fact into a design tool.

The bugs below all compile (or nearly compile) and all end in work that never ran or a task that never started. Recognizing them on sight is worth interview points.

1. Futures collected but never drained. You batch a request:

let mut futures: Vec<_> = urls.iter().map(|u| fetch(u)).collect();
// 20 futures exist; zero requests have been made
for f in futures {
    f.await;              // works, but runs sequentially: sum of all latencies
}

The collect built 20 plans and executed nothing — fetch(u) only captured u. .await inside the loop is correct but serial; futures::future::join_all(futures).await polls them concurrently and collapses the wall time. Forgetting the drain (or awaiting only futures[0]) compiles with a must_use warning at best and silently does nothing at worst. A future in a variable is work not done.

2. async blocks capture by reference unless you say move.

let name = String::from("orders");
let report = async { println!("{name}"); };   // borrows `name`
drop(name);                                  // error: `name` does not live long enough
report.await;

The block holds &name in its state machine, so it cannot outlive the local. Wrap it as async move { ... } and ownership transfers into the future — required whenever the future escapes the scope (returning it, storing it, spawning it). The mirror-image mistake: async move steals a variable you still need, and the next line gets "use of moved value." Decide the capture policy explicitly; do not let it default.

3. A non-Send value held across an await.

tokio::spawn(async {
    let guard = pool.lock().unwrap();          // std::sync::MutexGuard
    let rows = query(&guard).await;            // guard lives across the await
    println!("{rows}");
});

The compiler answers error[E0277]: future cannot be sent between threads safely, with the note future is not Send as this value is used across an await. The state machine stores the guard as a field, so the future's type carries a !Send part. Fixes, in order of preference: extract what you need and drop the guard before the await, switch to tokio::sync::Mutex whose guard is Send, or run the blocking work with spawn_blocking on this thread. The full decision tree lives in Send and Sync Marker Traits.

One more silent case: tokio::spawn(fetch(u)) without keeping the JoinHandle does not cancel the task — it detaches, and the result (or panic) becomes unobservable. Dropping the handle is a deliberate act, not an error, but you should know you made it. The Tokio Runtime covers handle semantics, task lifetimes, and why a forgotten spawn in main can vanish before it runs.

A review checklist that catches all four failure modes in about a minute:

1. Find every async fn call that is not followed by .await and not consumed by join!/select!/spawn — each one is work that never runs.
2. Find every async/async move block and ask who owns the captured data, and whether the block can outlive it.
3. Find every .await inside a lock() scope or a & of a local owned by the caller of spawn.
4. Find every JoinHandle you did not name — decide whether detach was intended.

Run that checklist on any diff that adds an async function and the silent classes of bug in this chapter do not reach review, let alone production.