Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 38 ยท Async, Tokio and Tower

The Tokio Runtime and Tasks

Learn how #[tokio::main], tokio::spawn, JoinHandle, spawn_blocking and channels work behind an Axum server, with runnable standard-library stand-ins for worker pools and message passing.

A future does nothing on its own. Something must poll it, wake it and decide which thread runs it. In an Axum application that something is the Tokio runtime. When you write #[tokio::main], you are asking Tokio to build a scheduler with a pool of worker threads, an I/O driver (epoll, kqueue or IOCP) and a timer wheel, and then to run your main future on it.

This lesson explains the pieces you will meet daily: the runtime flavors, tokio::spawn, JoinHandle, blocking work, and channels. Tokio is not available on this site's runner, so every runnable example uses std::thread and std::sync::mpsc to model the same ideas honestly: the API names differ, the shapes are the same.

#[tokio::main] unpacked

Rust
// Real code: read-only, needs tokio and axum.
use axum::{routing::get, Router};

#[tokio::main]
async fn main() {
    let app = Router::new().route("/", get(|| async { "hello" }));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

The macro rewrites main into roughly this:

Rust
fn main() {
    tokio::runtime::Builder::new_multi_thread()
        .enable_all()
        .build()
        .unwrap()
        .block_on(async { /* your body */ })
}

block_on is exactly the loop you wrote in the previous lesson, only with a real scheduler behind it. Two flavors exist: multi_thread (the default, one worker per CPU core, tasks can migrate) and current_thread (everything on one thread, handy for tests and tiny tools). Control the worker count with #[tokio::main(worker_threads = 4)].

Tasks and spawn

A task is a future that has been handed to the runtime. tokio::spawn(fut) schedules it and immediately returns a JoinHandle. The task runs concurrently with the code that spawned it, and you can .await the handle to get its result. Axum itself spawns one task per connection, which is why a slow client cannot stall the others.

Requirements for spawn: the future must be Send + 'static. 'static means it cannot borrow local variables, so you move owned data (or an Arc clone) into it.

Rust spawn and join (stand-in with threads)

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 results print in spawn order even though banana finished first, because we join in order. With real Tokio you would write let (a, b) = tokio::join!(fetch_a(), fetch_b()); to run futures concurrently inside one task, or JoinSet for a dynamic number of tasks.

Panics and cancellation

A panic inside a spawned task does not take down the runtime. The JoinHandle returns Err(JoinError), and the thread pool keeps going. Dropping a JoinHandle does not cancel the task (it detaches); call handle.abort() to cancel. Cancellation happens at the next .await, which is one more reason to keep critical cleanup in Drop implementations rather than after an await point.

Blocking work

Some work cannot be async: password hashing with Argon2, image resizing, a synchronous library. Run it inside tokio::task::spawn_blocking, which moves the closure to a separate pool of threads reserved for blocking, so worker threads stay free to poll futures.

Rust
// Real code: read-only.
async fn register(Json(input): Json<NewUser>) -> Result<StatusCode, AppError> {
    let hash = tokio::task::spawn_blocking(move || hash_password(&input.password))
        .await??; // first ? is the JoinError, second is your own error
    // store the hash ...
    Ok(StatusCode::CREATED)
}

The stand-in below shows why it matters: a tiny pool of two "workers" with a long job in the way. Heavy work belongs on a different pool.

Rust Keep workers free: a blocking pool (stand-in)

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.

Channels

Tasks talk by passing messages instead of sharing memory. Tokio ships four channel types:

Channel Shape Typical Axum use
mpsc many senders, one receiver work queues, background jobs
oneshot one value, one time reply to a request sent to a worker
broadcast many receivers each see every message chat rooms, SSE fan-out
watch latest value only config reload, shutdown flags

The std::sync::mpsc stand-in above has the same send/recv semantics as tokio::sync::mpsc; the Tokio version just awaits instead of blocking.

Prefer a channel plus a dedicated owner task over a shared Mutex when state changes often. It removes lock contention and makes the ordering of changes explicit. For simple counters or caches an Arc<Mutex<_>> is fine, as the state lesson showed.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does #[tokio::main] do?

    The macro wraps your body in a runtime builder call followed by block_on. Main itself stays an ordinary synchronous function.
  2. 2. Why must a spawned future be 'static?

    A spawned task may run after the spawning scope ends, so it cannot borrow locals. Move owned values or Arcs into it.
  3. 3. Where should Argon2 password hashing run in an Axum handler?

    Hashing is CPU-bound and blocks the worker thread. spawn_blocking moves it to a pool made for blocking work.
  4. 4. What happens when you drop a Tokio JoinHandle?

    Dropping a JoinHandle detaches the task. Use abort() to cancel it.

Summary

  • #[tokio::main] builds a runtime and block_ons your main future.
  • tokio::spawn creates a concurrent task and returns a JoinHandle; the future must be Send + 'static.
  • Panics are contained in the task; dropping a handle detaches, abort() cancels.
  • CPU-heavy or blocking code goes to spawn_blocking.
  • Channels (mpsc, oneshot, broadcast, watch) are the way tasks communicate.

Next: Tower Services and Layers