Tokio - The Async Runtime Everyone Actually Uses

I've been using Tokio since the 0.1 days when async Rust was still experimental as hell. Back then, you had to pick between Tokio and async-std, and honestly, most of us went with Tokio because it had more ecosystem support. Now async-std is officially dead as of March 2025, so that choice got easier.

The core problem Tokio solves is that traditional threading is expensive. Java threads eat about a meg of memory each, so you hit limits around 30,000 threads on decent hardware. With Tokio, tasks are cheap - maybe 2KB each - so you can spawn hundreds of thousands without your server keeling over.

How Tokio Actually Works

The work-stealing scheduler sounds fancy but really just means your CPU cores stay busy. Each core gets its own task queue, and when one runs out of work, it steals from the others. Pretty clever, and it mostly works well in practice.

Under the hood, Tokio uses epoll on Linux, kqueue on macOS, and IOCP on Windows to efficiently wait for I/O events. This means one thread can monitor thousands of network connections without blocking. The reactor pattern isn't new - nginx has been doing this forever - but Tokio makes it accessible in Rust.

Real Performance in Production

Discord's blog post about switching from Go to Rust is worth reading for actual performance numbers, not marketing fluff. They were hitting Go's garbage collector limits with their message volume, and Tokio helped them handle millions of concurrent WebSocket connections.

I've personally seen Tokio handle 100K+ concurrent connections on a single server with 16GB RAM. The limiting factors are usually file descriptors (bump your ulimits) and network bandwidth, not Tokio's scheduler.

The Learning Curve Is Real

Here's what the docs don't tell you: async Rust has a steep learning curve. If you're coming from blocking I/O, you'll spend hours debugging why your code hangs. Async stack traces are garbage, and error messages often don't make sense until you understand the borrow checker's relationship with futures.

The `Send + Sync` requirements for spawned tasks will bite you. You'll try to share a `Rc>` across tasks and get compiler errors that look like hieroglyphics. Use `Arc>` or channels instead.

Ecosystem Lock-in (But It's Good)

Once you pick Tokio, you're pretty much locked into its ecosystem. Axum, Hyper, Tonic, Tower - they all assume Tokio. This isn't necessarily bad since the ecosystem is mature, but switching async runtimes later is a pain in the ass.

The good news is that Tokio's ecosystem actually works together. Unlike JavaScript where every HTTP client has different interfaces, Tokio crates generally play nice with each other.

Adding Tokio to Your Project

Add tokio to your Cargo.toml like every other dependency. Don't overthink it:

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

The "full" feature flag includes everything. Yes, it increases compile time. Yes, your binary gets bigger. No, you probably don't need all of it, but figuring out which features you actually need is more annoying than just using "full" until you have a reason to optimize.

For production, you might want to be more specific:

[dependencies]
tokio = { version = "1.47", features = ["net", "rt-multi-thread", "macros"] }

Your First Tokio Program (That Will Crash)

Here's the echo server everyone copies from the docs:

use tokio::net::TcpListener;
use tokio::io::{AsyncReadExt, AsyncWriteExt};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let listener = TcpListener::bind("127.0.0.1:8080").await?;

    loop {
        let (mut socket, _) = listener.accept().await?;
        
        tokio::spawn(async move {
            let mut buf = [0; 1024];
            // This will crash in production - no error handling
            loop {
                let n = socket.read(&mut buf).await.unwrap_or(0);
                if n == 0 { return; }
                socket.write_all(&buf[0..n]).await.unwrap(); // This unwrap will kill your task
            }
        });
    }
}

This example is fine for understanding concepts, but it'll crash the first time someone sends malformed data or the network hiccups. In production, handle your fucking errors.

Runtime Configuration (Matters More Than You Think)

Multi-threaded runtime is the default and what you want 99% of the time:

#[tokio::main] // Multi-threaded, good for most things
async fn main() {}

Single-threaded runtime for debugging or specific constraints:

#[tokio::main(flavor = "current_thread")] // Single-threaded
async fn main() {}

You can also build the runtime manually if you need more control:

let rt = tokio::runtime::Builder::new_multi_thread()
    .worker_threads(4) // Explicit thread count
    .enable_all()
    .build()?;

The Ecosystem You'll End Up Using

Axum - Web framework that doesn't suck. Built by the Tokio team, so it actually integrates properly. Check out the Axum examples.

Hyper - HTTP client and server. Fast but the API is weird. Most frameworks wrap it. See the Hyper guides.

Tonic - gRPC implementation. Actually works, which is rare for gRPC implementations. The Tonic tutorial is decent.

Tracing - Logging for async code. Your println! statements won't help you debug async problems. Read the tracing book.

Production Gotchas

File descriptor limits: Your OS probably limits you to 1024 file descriptors. With thousands of connections, you'll hit this fast. Bump your ulimits or your server will start rejecting connections.

Task memory: Tasks are cheap (~2KB each) but spawning a million of them still uses 2GB of RAM just for task overhead. Don't go crazy.

Blocking calls: Never call `std::thread::sleep` in async code. Use `tokio::time::sleep`. Same goes for any blocking I/O - use `spawn_blocking` or your entire runtime will freeze.

Error handling: Panics in spawned tasks don't crash your program, they just kill that task silently. You'll spend hours debugging "why is my task not running" when it's actually panicking. Use `JoinHandle` to detect task failures.