Rust async/await

Also Known As

TL;DR

Explanation

Rust's async/await lets you write asynchronous code that reads like sequential code while compiling down to efficient state machines. An `async fn` or `async` block returns a value implementing the `Future` trait. A future is lazy: it does nothing until polled. The `.await` operator suspends the current future until the awaited future is ready, yielding control back to the executor so other tasks can make progress on the same thread.

Unlike threads, futures are zero-cost abstractions with no inherent runtime. Rust's standard library defines the `Future` trait and the language provides syntax, but it deliberately ships no executor. You must bring a runtime such as Tokio or async-std to actually drive futures to completion by repeatedly calling `poll`. The runtime also supplies async I/O primitives, timers, and task spawning.

A key mental model: awaiting does not spawn concurrency by itself. `let a = fetch().await; let b = fetch().await;` runs sequentially. To run futures concurrently you combine them with `join!`, `select!`, or spawn separate tasks. Because the compiler transforms async functions into state machines that capture locals across await points, borrowed references held across `.await` must satisfy lifetime and `Send` requirements, which is why some types like `MutexGuard` from `std::sync` cannot be held across awaits in multithreaded runtimes.

Error handling uses the normal `Result` and `?` operator inside async functions. Cancellation happens by dropping a future, so any cleanup must be drop-safe rather than relying on code after an await that may never run. Pinning (`Pin`) appears because self-referential state machines must not move in memory once polled; most users rely on `Box::pin` or runtime helpers rather than manipulating `Pin` directly. Mastering async/await means understanding laziness, the missing runtime, concurrent combinators, and the `Send`/lifetime constraints the borrow checker enforces across suspension points.

Common Misconception

Why It Matters

Common Mistakes

• Calling an async fn and forgetting to .await or spawn it, so the future never executes.
• Awaiting futures sequentially when they could run concurrently with join! or tokio::spawn.
• Holding a std::sync::MutexGuard across an .await, causing Send errors or deadlocks under a multithreaded executor.
• Doing CPU-heavy blocking work inside an async task and starving the executor instead of using spawn_blocking.
• Assuming code after an .await always runs, ignoring that dropping a future cancels it mid-flight.

Avoid When

• The workload is purely CPU-bound with no I/O, where threads or rayon are simpler and faster.
• A small synchronous CLI tool where adding a runtime is unnecessary complexity.
• You only need a single blocking network call and the extra async machinery adds no value.

When To Use

• Handling many concurrent I/O-bound connections such as HTTP servers or database clients.
• Building network services where blocking a thread per request would not scale.
• Composing multiple independent I/O operations to run concurrently with join! or select!.

Code Examples

use std::sync::Mutex;
use std::time::Duration;

async fn fetch(id: u32) -> u32 { id * 2 }

async fn run(state: &Mutex<u32>) {
    // Sequential awaits: these run one after another, not concurrently.
    let a = fetch(1).await;
    let b = fetch(2).await;

    // Holding a std::sync guard across .await -> not Send, can deadlock.
    let mut g = state.lock().unwrap();
    tokio::time::sleep(Duration::from_millis(10)).await;
    *g += a + b;
}

fn main() {
    let state = Mutex::new(0);
    // No runtime: this future is never polled, so run() never executes.
    let _ = run(&state);
}

use tokio::sync::Mutex;
use tokio::join;
use std::time::Duration;

async fn fetch(id: u32) -> u32 { id * 2 }

async fn run(state: &Mutex<u32>) {
    // Run independent futures concurrently.
    let (a, b) = join!(fetch(1), fetch(2));

    // Async-aware lock can be held across .await safely.
    let mut g = state.lock().await;
    tokio::time::sleep(Duration::from_millis(10)).await;
    *g += a + b;
}

#[tokio::main]
async fn main() {
    let state = Mutex::new(0);
    run(&state).await; // future is actually driven to completion
    println!("{}", *state.lock().await);
}

References

• https://rust-lang.github.io/async-book/
• https://doc.rust-lang.org/std/future/trait.Future.html
• https://tokio.rs/tokio/tutorial
• https://doc.rust-lang.org/reference/expressions/await-expr.html

Tags

🧠 Logic Engine