Async Rust with tokio

Why async?

A web server for a food delivery app may hold 10,000 open connections. Most of the time, each one is waiting: for the database, for a payment gateway, for the next request. A thread per connection would need 10,000 threads, each with its own memory. Async programming lets a handful of threads juggle all these waiting tasks, switching to whichever one is ready.

Futures and await

An async fn does not run when you call it. It returns a Future: a value that represents work that will finish later. Futures in Rust are lazy; nothing happens until something awaits them. Writing .await inside another async function says "pause here until this future is done, and let other tasks run meanwhile".

async fn fetch_price(item: &str) -> u32 {
    // imagine a network call here
    if item == "chai" { 15 } else { 40 }
}

async fn total() -> u32 {
    let a = fetch_price("chai").await;
    let b = fetch_price("samosa").await;
    a + b
}

A runtime runs the futures

The standard library defines what a Future is, but it does not include a runtime to run them. The most popular runtime is tokio. A runtime keeps a set of tasks, polls the ones that are ready to make progress, and uses the operating system to learn when sockets and timers are ready.

[dependencies]
tokio = { version = "1", features = ["full"] }

use tokio::time::{sleep, Duration};

async fn fetch(name: &str, ms: u64) -> String {
    sleep(Duration::from_millis(ms)).await;      // a pretend network wait
    format!("{name} done")
}

#[tokio::main]
async fn main() {
    // one after another: about 300 ms
    let a = fetch("orders", 100).await;
    let b = fetch("payments", 200).await;
    println!("{a}, {b}");

    // at the same time: about 200 ms
    let (c, d) = tokio::join!(fetch("orders", 100), fetch("payments", 200));
    println!("{c}, {d}");
}

Spawning tasks

let handle = tokio::spawn(async {
    fetch("report", 50).await
});
let report = handle.await.unwrap();   // JoinHandle is a future too

Spawned tasks may run on any of the runtime's worker threads, so what they capture must be Send and 'static, just like with threads. Use move and Arc in the same way.

Never block the runtime

Async works only if tasks give control back at each .await. If a task does slow work without awaiting, such as std::thread::sleep, a long CPU calculation, or a blocking file or database call, it holds a worker thread hostage and every other task on it stops. Use tokio's async versions (tokio::time::sleep, tokio::fs) and move heavy CPU work to tokio::task::spawn_blocking.

Threads or async?

Common mistakes

• Calling an async fn and forgetting .await: nothing happens, and the compiler warns "unused implementer of Future that must be used".
• Using std::thread::sleep inside async code. Use tokio::time::sleep(...).await.
• Awaiting in a loop one by one when the calls are independent. Use join! or spawn several tasks.
• Holding a std Mutex guard across an .await. Keep the guard in a small block, or use tokio::sync::Mutex when you must hold it across awaits.