FerrousPath

Level 3 · Systems· Lesson 2 of 11 · 35 min

Async and await

Futures as state machines, executors, tasks, cancellation, and how to write concurrent I/O with Tokio.

Why async

A thread per connection works until you have tens of thousands of connections: each thread costs stack memory and context switches. Async lets one thread juggle many tasks that are mostly waiting — for the network, a timer, a disk. It is a tool for I/O-bound concurrency. For CPU-bound work, threads or Rayon remain the right choice.

Futures are lazy state machines

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

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

An async fn compiles to an anonymous type implementing Future. Each .await is a point where the function may pause; the compiler transforms the body into an enum with one variant per pause point, holding the local variables alive across it. There is no hidden heap allocation and no separate stack per task.

Three consequences:

  1. Futures do nothing until polled. Calling an async function returns a value; you must .await it or hand it to an executor.
  2. Rust has no built-in runtime. The standard library defines Future; an executor — Tokio, smol, embassy on microcontrollers — decides when to poll.
  3. A Pending future must arrange to be woken. The Context carries a Waker; when the socket becomes readable the reactor calls wake(), and the executor polls that task again.

Level 4 builds an executor from scratch. Here we use Tokio.

Tasks and join!

// crate: tokio
use std::time::{Duration, Instant};
use tokio::time::sleep;

async fn fetch(name: &str, ms: u64) -> String {
    sleep(Duration::from_millis(ms)).await; // yields to the executor
    format!("{name} done after {ms} ms")
}

#[tokio::main]
async fn main() {
    let start = Instant::now();

    // Sequential: 300 ms.
    let a = fetch("a", 100).await;
    let b = fetch("b", 200).await;
    println!("{a}; {b}; elapsed {:?}", start.elapsed());

    // Concurrent on one task: ~200 ms.
    let start = Instant::now();
    let (a, b) = tokio::join!(fetch("a", 100), fetch("b", 200));
    println!("{a}; {b}; elapsed {:?}", start.elapsed());

    // Spawned tasks may run in parallel on the worker pool.
    let start = Instant::now();
    let handles: Vec<_> = (1..=5u64)
        .map(|i| tokio::spawn(async move { fetch("task", i * 40).await }))
        .collect();
    for h in handles {
        println!("{}", h.await.unwrap());
    }
    println!("elapsed {:?}", start.elapsed());
}
  • .await runs one future to completion before the next line.
  • join! polls several futures concurrently within the current task.
  • tokio::spawn creates an independent task. Like thread::spawn, it needs a Send + 'static future.

select!, timeouts and cancellation

// crate: tokio
use std::time::Duration;
use tokio::sync::mpsc;
use tokio::time::{sleep, timeout};

async fn slow() -> u32 {
    sleep(Duration::from_secs(5)).await;
    42
}

#[tokio::main]
async fn main() {
    // A timeout is just "race the future against a timer and drop the loser".
    match timeout(Duration::from_millis(100), slow()).await {
        Ok(v) => println!("got {v}"),
        Err(_) => println!("timed out; `slow` was dropped mid-sleep"),
    }

    let (tx, mut rx) = mpsc::channel::<u32>(8);
    tokio::spawn(async move {
        for i in 0..3 {
            sleep(Duration::from_millis(30)).await;
            if tx.send(i).await.is_err() {
                break;
            }
        }
    });

    let deadline = sleep(Duration::from_millis(200));
    tokio::pin!(deadline);
    loop {
        tokio::select! {
            Some(v) = rx.recv() => println!("received {v}"),
            _ = &mut deadline => { println!("deadline"); break; }
            else => { println!("channel closed"); break; }
        }
    }
}

Cancellation is dropping. When select! picks one branch, the other futures are dropped where they stand. A future can stop at any .await and never resume. Code that holds a half-finished invariant across an await — “I removed the item from the queue but have not yet written it” — is not cancel-safe. Check the documentation of anything you use inside select!.

The rules of async Rust

  • Never block the executor. No std::thread::sleep, no blocking file or network calls, no long computation in a task. Use async equivalents, or tokio::task::spawn_blocking for unavoidable blocking and CPU-heavy work.
  • Do not hold a std::sync::Mutex guard across an .await. The task may be suspended while holding the lock. Either release it first, or use tokio::sync::Mutex, whose guard may be held across awaits. For short critical sections with no await inside, the standard mutex is faster and correct.
  • Spawned futures must be Send on a multi-threaded runtime. Holding an Rc or a non-Send guard across an await makes the whole future non-Send, and the error message points at the await.
  • Bound your concurrency. Unbounded channels and unlimited spawning convert load into memory exhaustion. Prefer bounded channels and Semaphore.

Async traits and closures

async fn in traits has been stable since Rust 1.75, and async closures (async |x| …) since 1.85:

// crate: tokio
trait Store {
    async fn get(&self, key: &str) -> Option<String>;
}

struct Memory;

impl Store for Memory {
    async fn get(&self, key: &str) -> Option<String> {
        (key == "answer").then(|| "42".to_string())
    }
}

async fn lookup(store: &impl Store, key: &str) -> String {
    store.get(key).await.unwrap_or_else(|| "missing".into())
}

#[tokio::main]
async fn main() {
    println!("{} {}", lookup(&Memory, "answer").await, lookup(&Memory, "x").await);
}

A trait with async fn is not yet usable as dyn Trait directly, because each implementation returns a different future type. For dynamic dispatch, return Pin<Box<dyn Future<Output = T> + Send + '_>> explicitly or use the async-trait crate.

Streams

A Stream is the async counterpart of Iterator: it yields a sequence of values, each of which may require waiting. The trait lives in futures / tokio-stream and is used with while let Some(item) = stream.next().await.

Exercises

  1. Write an async function that fetches three “URLs” (simulated with sleep) concurrently and returns the results in order. Then limit it to two at a time with tokio::sync::Semaphore.
  2. Build a TCP echo server with tokio::net::TcpListener: accept in a loop, spawn a task per connection, and copy bytes back.
  3. Add graceful shutdown: on tokio::signal::ctrl_c(), stop accepting and wait for in-flight connections using a JoinSet.
  4. Explain why let g = std_mutex.lock().unwrap(); other().await; makes a future non-Send, and give two fixes.

Check your understanding

Pick an answer to see the explanation.

  1. 1.What does calling an async fn do?

  2. 2.Why must you not call a blocking function such as std::thread::sleep inside an async task?

  3. 3.What happens to a future that is dropped before it completes?

Key terms in this lesson

Finished the lesson and the exercises?