Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 38 ยท Async, Tokio and Tower

Async, Await and Futures

Understand what async fn, await and Future really are in Rust, why Axum handlers are futures, and build a tiny executor with the standard library to see polling and wakers work.

Every Axum handler is an async fn. That one keyword changes what the function is: calling it no longer runs the body. It returns a future, a value that describes work that can be paused and resumed later. Axum (through Tokio) is the thing that drives those futures to completion, thousands at a time, on a handful of threads.

This lesson takes the mystery out of that machinery. You will see what the Future trait looks like, what .await compiles down to, why a handler that blocks is dangerous, and you will build a miniature executor using nothing but the standard library. The real Axum and Tokio are not installed on this site, so the runnable examples are clearly labelled stand-ins that demonstrate the same ideas.

What an async fn returns

A normal function runs to the end when called. An async fn returns immediately with a state machine that the compiler writes for you. Nothing happens until somebody polls it.

Rust
// Real Axum handler: read-only, needs the axum and tokio crates.
async fn health() -> &'static str {
    "ok"
}

The type of health() is an anonymous type that implements Future<Output = &'static str>. Axum stores your handler, and when a request arrives it calls it and polls the resulting future until it yields Ready("ok").

The trait itself is small:

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

poll answers one of two things: Poll::Ready(value) (done) or Poll::Pending (not yet, wake me later). The Context carries a waker. A future that returns Pending must arrange for waker.wake() to be called when progress is possible, otherwise nobody will poll it again.

What .await does

Inside an async function, .await means: poll this inner future; if it is Pending, return Pending from me as well and give the thread back; when I am polled again, resume right here. That is cooperative multitasking. A task only gives up the thread at an .await that actually has to wait.

This is why one thread can serve many connections. While handler A waits for the database, the thread polls handler B. It also explains the golden rule: never block inside async code. A std::thread::sleep or a heavy loop with no .await keeps the thread hostage, and every other task scheduled on it stalls.

Build a tiny executor

The best way to understand polling is to write the loop yourself. A future that is ready after a few polls, plus a block_on that polls until done:

Rust A hand-made executor (stand-in for Tokio)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

A real runtime does not spin in a loop like this one. It parks the thread until the waker fires, which is the whole point of wakers: the I/O system calls wake() when a socket becomes readable.

async blocks and chaining

Because async fn compiles to a future, you can compose futures. .await inside another async function simply polls the inner one. Run several awaits in a row and you get sequential behaviour; the order of output below shows that nothing runs until block_on polls it.

Rust Futures are lazy until polled

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

The line "future created" prints before either load_* line. That laziness is also why forgetting .await is a bug: the future is built and then dropped without ever running (the compiler warns with unused_must_use).

Send, 'static and handlers

Tokio's default runtime moves tasks between worker threads, so a handler future must be Send. The usual cause of a confusing "future is not Send" error is holding a non-Send value (such as std::rc::Rc or a std::sync::MutexGuard) across an .await. The fix is to end its scope before awaiting.

Rust
// Real code: read-only.
async fn bad(state: std::sync::Arc<std::sync::Mutex<Vec<u32>>>) {
    let mut guard = state.lock().unwrap();
    guard.push(1);
    some_async_call().await; // guard is still alive here: error in a spawned task
}

async fn good(state: std::sync::Arc<std::sync::Mutex<Vec<u32>>>) {
    {
        let mut guard = state.lock().unwrap();
        guard.push(1);
    } // guard dropped here
    some_async_call().await;
}

The next lesson, the Tokio runtime and tasks, shows how many futures run at once.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

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

    An async fn returns a state machine implementing Future. Its body only runs when an executor polls it.
  2. 2. What must a future do when it returns Poll::Pending?

    The runtime will not poll the future again until the waker is woken, so the future (or whatever it waits on) must call wake().
  3. 3. Why is std::thread::sleep inside an async handler a problem?

    Sleeping does not yield to the executor. Use tokio::time::sleep(...).await, which pauses only the task.
  4. 4. What happens if you call an async function and never .await the result?

    Futures are lazy. Without an await or spawn, the body is never polled.

Summary

  • async fn returns a lazy Future; the executor polls it.
  • poll returns Ready or Pending; a pending future must register a waker.
  • .await suspends the current task, not the thread; blocking calls break that deal.
  • Handler futures must be Send; do not hold non-Send guards across an .await.
  • The examples here are standard-library stand-ins for what Tokio does for you.

Next: The Tokio Runtime and Tasks