Skip to content
Tutorials Center
My learning

Topics

Lesson 85 of 132 ยท Async Rust

Tokio and the Async Ecosystem

Tour Tokio and the async Rust ecosystem: tokio::main, spawn, JoinSet, select!, channels, async I/O, why futures must be Send, blocking pitfalls, and runtime choices.

In the last lessons you wrote futures, wakers and a tiny executor yourself. Real programs rarely do that. They use a runtime, a library that bundles an executor with everything async code needs to talk to the outside world: timers, sockets, files, channels and a way to run blocking work. In Rust, the most widely used runtime by far is Tokio. Web frameworks such as Axum, HTTP clients such as reqwest, database drivers such as sqlx and the gRPC library tonic are all built on it.

Tokio is a crate, so it cannot run in our editor, which compiles one file with the standard library only. This lesson is therefore a guided tour: the Tokio code is shown in clearly labelled read-only blocks, and every idea that can be demonstrated with the standard library gets a runnable stand-in. You will see why tokio::spawn demands Send futures (with the real compiler error), why blocking inside async code is the number one performance bug, and how to choose between runtimes. If the vocabulary of tasks and wakers is unfamiliar, start with async/await basics and async patterns with a mini runtime.

What a runtime provides

A runtime is more than an executor. Tokio has five main parts:

  • Scheduler. Runs tasks. The default multi-thread scheduler has a pool of worker threads (one per CPU core) that steal work from each other. A current-thread flavor runs everything on one thread.
  • Reactor (I/O driver). Asks the operating system (epoll, kqueue, IOCP) which sockets are ready and wakes the tasks waiting on them. This is what makes socket.read().await cheap: no thread sits blocked in read.
  • Timers. tokio::time::sleep, timeout and interval, driven by one shared timer wheel instead of a thread per timer.
  • Blocking pool. Extra threads for work that cannot be async, such as heavy computation or an old synchronous library.
  • Synchronization tools. Async-aware channels (mpsc, oneshot, broadcast, watch), Mutex, Semaphore, Notify.

Your futures talk to the reactor and the timers through the same Waker you met earlier. A socket future returns Pending after registering its waker with the reactor; when the OS says the socket is readable, the reactor calls wake(), and the scheduler polls your task again.

Your first Tokio program (read-only)

Add Tokio to Cargo.toml. The full feature turns on everything; real applications often pick only what they need (rt-multi-thread, macros, time, net, sync).

TOML
# Cargo.toml  (read-only: needs Cargo and crates.io)
[dependencies]
tokio = { version = "1", features = ["full"] }
Rust
// src/main.rs  (read-only: needs the tokio crate)
use std::time::Duration;

#[tokio::main]
async fn main() {
    println!("start");
    tokio::time::sleep(Duration::from_millis(100)).await;
    println!("100 ms later");
}

Rust does not allow async fn main, because nothing could run it. #[tokio::main] is a macro that rewrites your main into an ordinary one that builds a runtime and calls block_on on your body, exactly like the block_on function in our examples:

Rust
// What #[tokio::main] roughly expands to (read-only)
fn main() {
    tokio::runtime::Builder::new_multi_thread()
        .enable_all()
        .build()
        .unwrap()
        .block_on(async {
            println!("start");
            tokio::time::sleep(std::time::Duration::from_millis(100)).await;
            println!("100 ms later");
        })
}

Use #[tokio::main(flavor = "current_thread")] for a single-threaded runtime, and #[tokio::test] to write async tests.

Spawning tasks and joining them (read-only)

tokio::spawn is the same idea as our Spawner::spawn. It hands a future to the scheduler and returns a JoinHandle. Awaiting the handle gives a Result, because a task that panicked reports the panic as an error instead of crashing the others.

Rust
// read-only: needs the tokio crate
#[tokio::main]
async fn main() {
    let handle = tokio::spawn(async {
        // runs concurrently with main, possibly on another worker thread
        (1..=10).sum::<u32>()
    });

    let total = handle.await.unwrap(); // Err(JoinError) if the task panicked
    println!("total = {total}");
}

For many tasks, tokio::task::JoinSet collects them and yields results in completion order. Dropping a JoinSet aborts every task still inside it, which makes cleanup automatic:

Rust
// read-only: needs the tokio crate
use tokio::task::JoinSet;

#[tokio::main]
async fn main() {
    let mut set = JoinSet::new();
    for id in 0..5 {
        set.spawn(async move { id * 10 });
    }
    let mut results = Vec::new();
    while let Some(done) = set.join_next().await {
        results.push(done.unwrap()); // arrival order is not guaranteed
    }
    results.sort();
    println!("{results:?}");
}

You can cancel a spawned task with handle.abort(). That drops its future at the next .await, as described in async patterns.

join!, select! and timeouts (read-only)

Two macros combine futures inside one task, without spawning:

  • tokio::join!(a, b, c) runs the futures concurrently and waits for all of them.
  • tokio::select! { ... } waits for the first branch to complete and drops the others.
Rust
// read-only: needs the tokio crate
use std::time::Duration;
use tokio::{sync::mpsc, time};

#[tokio::main]
async fn main() {
    let (tx, mut rx) = mpsc::channel::<String>(8);
    tokio::spawn(async move {
        tx.send("hello".to_string()).await.unwrap();
    });

    loop {
        tokio::select! {
            Some(msg) = rx.recv() => println!("message: {msg}"),
            _ = time::sleep(Duration::from_secs(1)) => {
                println!("nothing for a second, giving up");
                break;
            }
        }
    }

    // A timeout wraps any future: Err(Elapsed) if it takes too long.
    let slow = time::sleep(Duration::from_secs(5));
    match time::timeout(Duration::from_millis(50), slow).await {
        Ok(()) => println!("finished in time"),
        Err(_) => println!("timed out"),
    }
}

The select! here is the macro form of the hand-written select from the previous lesson. Everything we said about cancellation applies: the losing branch is dropped. Branch futures must therefore be cancel safe. rx.recv() is cancel safe (a message is never lost if another branch wins); a hand-written "read half a frame, then await" function is not.

Async I/O (read-only)

Network and file I/O live in tokio::net, tokio::fs and tokio::io. The traits AsyncRead and AsyncWrite mirror the blocking Read and Write traits you will meet in Read, Write and BufRead, and the extension traits AsyncReadExt and AsyncWriteExt give you read, write_all and friends. A complete echo server, one task per connection:

Rust
// read-only: needs the tokio crate
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpListener;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let listener = TcpListener::bind("127.0.0.1:7878").await?;
    loop {
        let (mut socket, _addr) = listener.accept().await?;
        tokio::spawn(async move {
            let mut buf = [0u8; 1024];
            loop {
                let n = match socket.read(&mut buf).await {
                    Ok(0) | Err(_) => return, // connection closed or failed
                    Ok(n) => n,
                };
                if socket.write_all(&buf[..n]).await.is_err() {
                    return;
                }
            }
        });
    }
}

Thousands of idle connections cost thousands of small futures and no threads waiting. The same program written with blocking std::net needs a thread per connection (see networking with std::net), which is simpler to write and perfectly fine for dozens of clients, but costly for tens of thousands.

Why spawned futures must be Send

On the default multi-thread runtime, a task can start on one worker thread, suspend at an .await, and be resumed by a different worker thread. Everything the future keeps alive across that .await therefore moves between threads. So tokio::spawn requires F: Future + Send + 'static: the future and everything it holds across an await point must be Send, and it must not borrow from the caller's stack ('static).

Our editor cannot run Tokio, but it can show the same rule. Below, a stand-in runtime has worker threads and a queue; the key line is the bound on spawn. Tasks yield between chunks of work, so one task may be resumed by a different worker than the one that began it. Results come back through a channel, and main collects them in order, so the output is stable. Which worker runs which task is not.

Rust A multi-threaded executor with a Send bound

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.

Now break the rule. Rc is not Send, because its reference count is not atomic. If an Rc is alive across an .await, the future holds it while it may move to another thread, and the compiler refuses. For brevity, the spawn below only checks the bounds a real runtime would require:

Rust An Rc held across an await (fails on purpose)

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 error is error: future cannot be sent between threads safely, with future created by async block is not Send. A note then says `future is not `Send` as this value is used across an await`, pointing at `local` (`has type `Rc<i32>` which is not `Send) and at the .await (await occurs here, with local maybe used later), and a last note names the Send bound on spawn. The compiler shows the exact variable and the exact await that are responsible. Fix it by making sure the non-Send value is gone before the await, or by using a Send type such as Arc:

Rust Fixing it: drop the Rc before the await

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 first version failed because local lived across the .await. In the second, the Rc is dropped at the closing brace of the inner block, before the suspension point, so it is not part of the future's saved state.

A common cause of this error is a std::sync::MutexGuard kept across an .await: it is also not Send. The fix is the same: scope the lock in a block, or use tokio::sync::Mutex when you really must hold a lock while awaiting. As a rule of thumb, prefer std::sync::Mutex for short critical sections that never await, and tokio::sync::Mutex only when the guard must cross an .await.

If you do not need multi-threading, a current_thread runtime plus tokio::task::LocalSet lets you spawn !Send futures with spawn_local.

The number one pitfall: blocking in async code

Tasks switch only at .await. A task that computes for 200 ms, sleeps with std::thread::sleep, or calls a blocking database driver without awaiting, holds its worker thread the whole time. With a multi-thread runtime a few such tasks occupy all workers, and every other task, including those that just want to answer a health check, waits. On a current-thread runtime a single blocking task freezes the entire program.

Here is the effect in miniature. A tiny round-robin executor polls each task once per round. The ticker is polite and yields after each tick. The greedy task does three steps in a row; in the first scenario it never awaits, in the second it yields between steps. The comparison of the two outputs is the whole lesson.

Rust Blocking work starves the other tasks

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.

In the blocking version, the ticker gets one tick, then waits while the greedy task runs all three steps without interruption. In the polite version, the two tasks alternate. A real blocking call (a long loop, thread::sleep, a synchronous file read) behaves like the first version, only for much longer.

The remedy in Tokio is tokio::task::spawn_blocking, which runs a closure on a separate pool of threads and gives you a future for its result:

Rust
// read-only: needs the tokio crate
let digest = tokio::task::spawn_blocking(move || expensive_hash(&data)).await?;

You can build that yourself with a thread, a shared slot and a waker. The stand-in below does exactly that: a thread runs the closure, stores the result and wakes the task that is waiting. Notice that, unlike an async block, the closure starts running immediately when spawn_blocking is called, not when it is first awaited.

Rust A spawn_blocking 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.

If the work is CPU-heavy and long-lived, prefer a dedicated thread pool (or the Rayon crate) over spawn_blocking, whose pool is meant for blocking I/O and occasional short computations.

The wider ecosystem

Most async crates sit on top of the same small set of traits (Future, and in the futures crate Stream), but many also depend on a specific runtime's I/O types, so check which runtime a library expects.

Crate What it is for Typical use
tokio Runtime: scheduler, I/O, timers, sync Servers, clients, almost everything
futures Combinators, Stream, join_all, executors Runtime-neutral helpers
hyper Fast HTTP/1 and HTTP/2 implementation Under Axum and reqwest
axum Web framework (routers, extractors) REST APIs
reqwest HTTP client Calling other services
tonic gRPC Service-to-service calls
sqlx Async SQL with compile-time checked queries Postgres, MySQL, SQLite
tracing Structured, span-aware logging Debugging async programs
tower Middleware abstractions (retry, timeout, limits) Under Axum and tonic

A complete web service in Axum is short, because the runtime, HTTP and routing are all provided:

Rust
// read-only: needs tokio and axum (Cargo.toml: tokio = { version = "1", features = ["full"] }, axum = "0.8")
use axum::{routing::get, Router};

async fn hello() -> &'static str {
    "Hello from Rust"
}

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

And an HTTP request with reqwest:

Rust
// read-only: needs tokio and reqwest
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let body = reqwest::get("https://example.com").await?.text().await?;
    println!("received {} bytes", body.len());
    Ok(())
}

Choosing a runtime

  • Tokio is the default choice: biggest ecosystem, best tooling (tokio-console, tracing), actively developed. Pick it unless you have a reason not to.
  • smol is a small, simple runtime made of tiny crates; good for applications that value compile time and a small footprint. The async-std project, which mirrored the standard library's API, has been discontinued in favour of smol.
  • Embassy is an async runtime for microcontrollers with no operating system (see embedded and WebAssembly).
  • io_uring runtimes (glommio, monoio, tokio-uring) use a different kernel interface for very high-throughput I/O on Linux, with different buffer ownership rules.

Libraries should ideally avoid choosing a runtime for the user: depend on std::future::Future and futures traits where possible, and expose runtime-specific code behind a Cargo feature.

When to use async, and when not

Use async when you have many tasks that mostly wait: network servers, proxies, clients that call several APIs at once, anything with tens of thousands of connections. Use plain threads when you have a handful of concurrent jobs, CPU-bound work, or code that depends on blocking libraries. Many programs mix both: an async server that offloads CPU-heavy steps to a thread pool. Async adds real complexity (Send bounds, cancellation, pinning, coloured functions), so do not reach for it just because it is fashionable.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why can you not write async fn main in plain Rust?

    An async function only creates a future. Something must poll it. #[tokio::main] rewrites main into a normal function that builds a runtime and calls block_on.
  2. 2. What does tokio::spawn require of the future you pass it on the multi-thread runtime?

    A task may be resumed on a different worker thread after any .await, so everything it keeps across that point must be Send. 'static means it cannot borrow from the caller's stack.
  3. 3. Which of these is the usual cause of the error 'future cannot be sent between threads safely'?

    The value is stored in the future's state while the task is suspended. If that value is not Send, the whole future is not Send. Drop it before the await or use a Send type.
  4. 4. What is the problem with calling std::thread::sleep inside an async task?

    Tasks only switch at .await. A blocking call holds the thread the executor needs for other tasks. Use tokio::time::sleep for waiting and spawn_blocking for blocking work.
  5. 5. What does dropping a future that is a branch of select! do?

    select! drops the branches that did not win. Cancellation in async Rust is dropping, so branch futures should be cancel safe.

Summary

  • Tokio is a runtime: a work-stealing scheduler, an I/O reactor, timers, a blocking pool and async-aware synchronization tools. #[tokio::main] builds one and calls block_on for you.
  • tokio::spawn runs a task and returns a JoinHandle; JoinSet manages many tasks, join! waits for all futures in one task and select! takes the first, cancelling the rest.
  • Spawned futures must be Send + 'static on the multi-thread runtime. Non-Send values (Rc, std MutexGuard) must not live across an .await.
  • Never block inside a task: use tokio::time::sleep to wait and spawn_blocking (or a thread pool) for blocking and CPU-heavy work.
  • Axum, reqwest, hyper, tonic, sqlx and tracing form the core of the server-side ecosystem. Alternatives are smol, Embassy and io_uring runtimes.
  • Choose async for many mostly-waiting tasks and threads for CPU-bound or few concurrent jobs.

Next: Time, Duration and Instant