Tokio Highlights Summary

Every highlight bullet from the 11 pages in this section, gathered on one page and grouped by the page it came from.

Tokio's Runtime Model

• Tokio is one implementation of Future's missing half: the executor, reactor, and timer that Rust's std does not provide.
• Tasks are cooperatively scheduled - a task that never yields at an await point can starve every other task on its worker thread.
• The multi-thread runtime work-steals ready tasks across a fixed pool of OS threads, not one thread per task.
• The I/O driver is a libuv-style reactor: OS readiness events wake exactly the tasks waiting on them.
• spawn_blocking exists because the reactor model breaks down the moment a task calls a blocking syscall.

Tokio Basics

• Use Rust 1.97.0 (edition 2024) and Tokio 1.x with the "full" feature
• The #[tokio::main] attribute installs a multi-thread runtime and drives main
• tokio::spawn schedules independent work on the runtime
• tokio::time::sleep yields the worker thread to other tasks
• Tokio provides async networking primitives like TcpListener and TcpStream
• tokio::sync::mpsc channels apply backpressure and close when senders drop

Tasks & JoinHandles

• Tokio tasks are lightweight units of async work scheduled on the runtime
• JoinHandle lets you await results, abort execution, and track task completion
• Use tokio::spawn for Send tasks on the runtime
• Use spawn_blocking for blocking closures on the blocking pool
• Always await or abort handles to avoid leaked tasks
• Dropping a JoinHandle does not cancel the associated task

Async I/O

• Tokio wraps OS async I/O for sockets and files
• Use AsyncRead/AsyncWrite traits for efficient network and file code
• BufReader/BufWriter batch small reads/writes to reduce syscalls
• Avoid std::fs in async handlers; use tokio::fs or spawn_blocking
• Flush BufWriter before closing to prevent data loss
• Use tokio::net::lookup_host for async DNS resolution

Channels in Tokio

• Tokio provides mpsc, oneshot, broadcast, and watch async channels
• mpsc channels are for work queues and support backpressure
• oneshot channels send a single reply between two tasks
• broadcast channels fan out messages to multiple receivers
• watch channels signal the latest value to multiple receivers
• Adapt mpsc::Receiver to a Stream for iterator-style processing
• Avoid blocking in channel callbacks to prevent starving the runtime

select! & Concurrency

• tokio::select! multiplexes async branches, completing when the first one finishes
• The first ready branch wins, and other branches are disabled for that iteration
• Losing branches are dropped at await points, which is called cancellation
• Use else to handle cases where all select branches are disabled
• Avoid non-cancel-safe reads in a loop; partial reads can be lost on cancel
• Do not hold a Mutex across a select! statement; acquire the lock inside the branch

Timers & Intervals

• Enable the time feature for production services
• Use tokio::time::sleep instead of std::thread::sleep in async code
• Configure MissedTickBehavior::Skip to prevent interval catch-up storms
• Use tokio::time::Instant for async tests with time pausing
• Layer timeouts for robust handling of network requests
• Do not use Tokio timers for hard real-time guarantees

Shared State in Async

• Use Arc to share databases, caches, and config in async services
• Use tokio::sync::Mutex for mutable state in async applications
• Implement an actor task for state ownership and channel-based communication
• Avoid std::sync::Mutex across await points; use tokio::sync::Mutex
• Shard state or use actors to prevent a "God object" Arc<Mutex<App>>
• Use bounded mpsc channels with backpressure to prevent unbounded memory growth

Tracing & Instrumentation

• Use the tracing crate for structured, async-aware spans and events
• Pair tracing with Tokio for production visibility into tasks and I/O
• Use #[instrument] or .instrument() to attach spans across .await points
• Avoid println! in production; use tracing events with request IDs
• Initialize the tracing subscriber once in main to prevent panics
• Propagate the traceparent header for distributed traces

Graceful Shutdown

• Drain in-flight requests and close pools when shutting down
• Combine signal handlers, CancellationToken, and server graceful APIs
• Use CancellationToken to propagate shutdown to accept loops
• Kubernetes sends SIGTERM before SIGKILL; honor the drain window
• Align drain timeout with Kubernetes terminationGracePeriodSeconds
• Pass CancellationToken to all background task loops

Tokio Best Practices

• Use multi_thread for API servers, current_thread for tests
• Set worker_threads from profiling, not guesses
• Spawn per-connection; do not block the accept loop
• Await or abort every JoinHandle to track background work
• Size mpsc channels for burst backpressure, not infinite queues
• Implement graceful shutdown (SIGTERM + drain timeout)