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.

Recipe

Quick-reference recipe card - copy-paste ready.

#[tokio::main]
async fn main() {
    let handle = tokio::spawn(async { 42 });
    let answer = handle.await.unwrap();
    println!("{answer}");
}

When to reach for this: Background work, per-connection handlers, parallel I/O, and structured task groups.

Working Example

use tokio::task::JoinSet;
 
async fn fetch_id(id: u32) -> u32 {
    tokio::time::sleep(std::time::Duration::from_millis(10)).await;
    id * 10
}
 
#[tokio::main]
async fn main() {
    let mut set = JoinSet::new();
    for id in 1..=5 {
        set.spawn(fetch_id(id));
    }
 
    while let Some(res) = set.join_next().await {
        println!("{}", res.unwrap());
    }
}

What this demonstrates:

• JoinSet manages dynamic spawned tasks.
• join_next yields results as tasks complete.
• Set is empty when all tasks finish.

Deep Dive

How It Works

• Task: Boxed future scheduled on Tokio executor.
• JoinHandle: Owned handle; await returns Result<T, JoinError>.
• abort: Cancels task at next await point.
• JoinSet / JoinMap: Collections for many handles without manual Vec.

Spawn Variants

Rust Notes

// Named task for tokio-console / tracing
let handle = tokio::task::Builder::new()
    .name("worker")
    .spawn(async { /* ... */ })
    .unwrap();

• Always await or abort handles to avoid leaked tasks.
• JoinError is is_panic() or is_cancelled().
• Parent dropping without awaiting does not cancel child unless configured.

Gotchas

• Fire-and-forget spawn - Errors silently lost. Fix: Await handle, use JoinSet, or attach tracing error handler.
• Non-Send future in spawn - Compile error on multi-thread runtime. Fix: spawn_local + LocalSet or remove Rc/mutex guards across await.
• Blocking inside spawned task - Starves workers. Fix: spawn_blocking for sync sections.
• Unbounded JoinSet growth - Spawning faster than completing. Fix: Semaphore or bounded worker pool.
• Panic in task - await returns Err(JoinError). Fix: Match error; consider catch_unwind for isolation.

Alternatives

FAQs

Related

• Tokio Basics - first spawn
• Combining Futures - join macros
• Cancellation & Timeouts - abort
• Graceful Shutdown - draining tasks
• Tracing & Instrumentation - named tasks

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.