Spawning Tasks

24 min read

In JavaScript you never “spawn” anything — every async operation runs on the one event loop, and “concurrency” is just interleaving on a single thread. Rust’s Tokio gives you tokio::spawn, which hands a future to the runtime as an independent task that can run in parallel on a thread pool. This page is about spawning those tasks, awaiting their results through a JoinHandle, how tasks differ from OS threads, and when to reach for spawn_blocking.

Quick Overview

A task is Tokio’s unit of concurrency: a future that the runtime owns and drives independently, like a green thread. tokio::spawn starts one immediately and returns a JoinHandle<T> you can .await to get its result. Tasks are far cheaper than OS threads and, on a multi-thread runtime, can run truly in parallel — but CPU-heavy or blocking synchronous work must go to spawn_blocking so it does not stall the async workers.

Note: This page assumes you already have a runtime wired up. If #[tokio::main] and the laziness of futures are new to you, read tokio-setup.md and promises-vs-futures.md first.

TypeScript/JavaScript Example

In Node.js there is no spawning. You start async operations and they run concurrently on the single event loop; you compose their results with Promise.all or by awaiting them. “Background work” is just a promise you do not await yet:

1
// A "background task" in Node is just an un-awaited promise.
2
async function fetchUser(id: number): Promise<string> {
3
  // Stand-in for a DB/network call.
4
  await new Promise((resolve) => setTimeout(resolve, 50));
5
  return `user-${id}`;
6
}
7

8
async function main(): Promise<void> {
9
  // Kick off five fetches "concurrently". They interleave on ONE thread —
10
  // the event loop. There is no parallelism here; CPU work would block them all.
11
  const promises = [1, 2, 3, 4, 5].map((id) => fetchUser(id));
12

13
  console.log("all fetches kicked off, event loop continues");
14

15
  // Promise.all gathers the results.
16
  const users = await Promise.all(promises);
17
  console.log(users);
18
}
19

20
main();

There is one important limitation hiding here: because Node runs your JavaScript on a single thread, a CPU-bound function (say, hashing a megabyte synchronously) blocks the entire event loop — every other “concurrent” promise stalls until it returns. Node’s answer is worker_threads, a separate, heavier mechanism. Keep that distinction in mind; Rust splits the same problem into tokio::spawn (concurrency) and spawn_blocking (offloading blocking work).

Rust Equivalent

tokio::spawn takes a future and hands it to the runtime as a task. It returns a JoinHandle<T> — roughly the analogue of the Promise you would have gotten back from an async call, except the work is now an independently scheduled task:

1
use tokio::task::JoinHandle;
2

3
#[tokio::main]
4
async fn main() {
5
    // spawn returns a JoinHandle<u64> immediately; the task starts running
6
    // concurrently right away (unlike a bare future, which is lazy).
7
    let handle: JoinHandle<u64> = tokio::spawn(async {
8
        // pretend this is a network call or heavy async work
9
        let mut total = 0u64;
10
        for i in 1..=100 {
11
            total += i;
12
        }
13
        total
14
    });
15

16
    // Do other work here while the task runs...
17
    println!("task spawned, main continues");
18

19
    // .await on the handle yields the task's output, wrapped in Result.
20
    let sum = handle.await.expect("the task panicked");
21
    println!("sum = {sum}");
22
}

Real output:

1
task spawned, main continues
2
sum = 5050

The shape mirrors const p = fetchUser(1); const u = await p; in JavaScript — but with two differences that matter: spawning a task makes it eligible to run on any worker thread (real parallelism), and handle.await returns a Result, because the task could have panicked. We will unpack both below.

To fetch many things concurrently, spawn in a loop and collect the handles:

1
use std::time::Duration;
2
use tokio::time::sleep;
3

4
async fn fetch_user(id: u32) -> String {
5
    sleep(Duration::from_millis(50)).await; // stands in for a DB/network call
6
    format!("user-{id}")
7
}
8

9
#[tokio::main]
10
async fn main() {
11
    let mut handles = Vec::new();
12
    for id in 1..=5 {
13
        // Each spawned task runs concurrently. The loop does not block.
14
        handles.push(tokio::spawn(fetch_user(id)));
15
    }
16

17
    // Await each handle to collect the results.
18
    let mut users = Vec::new();
19
    for handle in handles {
20
        users.push(handle.await.unwrap());
21
    }
22

23
    println!("{users:?}");
24
}

Real output:

1
["user-1", "user-2", "user-3", "user-4", "user-5"]

This is the rough equivalent of the Promise.all example above — five 50 ms sleeps overlap, so the whole thing finishes in about 50 ms.

Tip: For “fetch a fixed set of things and await all of them,” join!/try_join! are often cleaner than spawning, because they run the futures concurrently without requiring Send + 'static. Reach for spawn when you need tasks to outlive the current scope, run on other threads, or be cancellable independently.

Detailed Explanation

What `tokio::spawn` returns and when the task starts

tokio::spawn(future) does two things synchronously: it registers the future with the current runtime as a task, and it returns a JoinHandle<T> where T is the future’s output type. Crucially, the task is now scheduled and will make progress on its own, even before you await the handle.

This is a subtle but important contrast with a bare future. A plain async { ... } block does nothing until something polls it (see promises-vs-futures.md). Once you spawn it, the runtime is the thing polling it — so a spawned task behaves much more like an eager JavaScript promise. You can think of tokio::spawn as the operation that converts a lazy future into an actively-running task.

Awaiting the handle yields a `Result`

handle.await produces a Result<T, JoinError>, not just T. The Err case exists because a task is isolated: if its future panics, the runtime catches the panic and reports it back through the handle instead of unwinding your whole program.

1
#[tokio::main]
2
async fn main() {
3
    let handle = tokio::spawn(async {
4
        panic!("something broke inside the task");
5
    });
6

7
    match handle.await {
8
        Ok(()) => println!("task finished cleanly"),
9
        Err(join_err) => {
10
            // The runtime catches the panic; the rest of the program survives.
11
            println!("task failed: is_panic = {}", join_err.is_panic());
12
        }
13
    }
14

15
    println!("main is still alive");
16
}

Real output:

1
thread 'tokio-rt-worker' panicked at src/main.rs:4:9:
2
something broke inside the task
3
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
4
task failed: is_panic = true
5
main is still alive

Note the panic message is still printed (Rust’s default panic hook runs), but main keeps going because the panic was contained in the task. In JavaScript, an unhandled rejection in one promise does not crash unrelated promises either — but the mechanism is different: here a thread genuinely panicked and the runtime turned that into a JoinError.

The `'static` and `Send` bounds

The signature of tokio::spawn is, simplified:

1
pub fn spawn<F>(future: F) -> JoinHandle<F::Output>
2
where
3
    F: Future + Send + 'static,
4
    F::Output: Send + 'static,

Two bounds drive almost every error you will hit:

'static: a spawned task may outlive the function that created it, so it cannot borrow local variables. You must move owned data in (with async move) or share it via Arc.
Send: on a multi-thread runtime, a task can be moved between worker threads, so its future (and every value held across an .await) must be safe to send across threads.

These are the compile-time price of real parallelism. JavaScript needs neither because everything lives on one thread and the closure captures by reference into the same heap. Both bounds are shown as real compiler errors under Common Pitfalls.

Detaching: dropping the handle does not cancel the task

Unlike some task systems, dropping a JoinHandle does not stop the task — it simply detaches it, and the task runs to completion in the background. You just lose the ability to await its result.

1
use tokio::sync::oneshot;
2

3
#[tokio::main]
4
async fn main() {
5
    let (tx, rx) = oneshot::channel();
6

7
    // We spawn and immediately drop the JoinHandle (the `_` discards it).
8
    let _ = tokio::spawn(async move {
9
        // This still runs to completion despite no handle being held.
10
        let _ = tx.send("background work finished");
11
    });
12

13
    // Prove the task ran by receiving its message.
14
    let msg = rx.await.expect("sender dropped");
15
    println!("{msg}");
16
}

Real output:

1
background work finished

Warning: Detached tasks are the Rust equivalent of “fire and forget” promises. They keep running, but they are not awaited at shutdown — if main (or the runtime) ends first, in-flight detached tasks are dropped mid-flight. Keep handles (or use a JoinSet) when you need to wait for completion.

Cancelling with `abort`

To actually stop a task, call abort() on its handle. The task is cancelled at its next .await point, and awaiting the handle then returns a JoinError for which is_cancelled() is true:

1
use std::time::Duration;
2
use tokio::time::sleep;
3

4
#[tokio::main]
5
async fn main() {
6
    let handle = tokio::spawn(async {
7
        sleep(Duration::from_secs(60)).await; // long-running
8
        "done"
9
    });
10

11
    // Decide we no longer need the result and cancel the task.
12
    handle.abort();
13

14
    match handle.await {
15
        Ok(value) => println!("completed: {value}"),
16
        Err(e) if e.is_cancelled() => println!("task was cancelled"),
17
        Err(e) => println!("task failed: {e}"),
18
    }
19
}

Real output:

1
task was cancelled

JavaScript has no built-in promise cancellation (you reach for AbortController); Tokio bakes cancellation into the handle. Cancellation semantics in depth — what “cancel at an await point” really means — live in concurrency.md.

`spawn_blocking`: the escape hatch for synchronous work

Async tasks are cooperative: a task only yields control at an .await. If a task runs a long synchronous computation or calls a blocking API (a CPU-bound loop, std::thread::sleep, a synchronous file or database call), it never yields, and it starves every other task sharing that worker thread. This is the same failure mode as blocking Node’s event loop — but Tokio gives you a first-class fix.

tokio::task::spawn_blocking moves a synchronous closure onto a separate, dedicated thread pool reserved for blocking work, so the async workers stay free:

1
use tokio::task;
2

3
// A CPU-bound, synchronous function. It blocks the thread it runs on.
4
fn fibonacci(n: u64) -> u64 {
5
    if n < 2 { n } else { fibonacci(n - 1) + fibonacci(n - 2) }
6
}
7

8
#[tokio::main]
9
async fn main() {
10
    // spawn_blocking moves this work to a dedicated blocking-thread pool,
11
    // so it does NOT stall the async worker threads.
12
    let handle = task::spawn_blocking(|| {
13
        // Heavy synchronous computation lives here.
14
        fibonacci(35)
15
    });
16

17
    // Meanwhile, async work on the runtime keeps making progress.
18
    println!("computing fib(35) on a blocking thread...");
19

20
    let result = handle.await.unwrap();
21
    println!("fib(35) = {result}");
22
}

Real output:

1
computing fib(35) on a blocking thread...
2
fib(35) = 9227465

spawn_blocking returns a JoinHandle<T> just like spawn, so you .await it the same way. The closure is FnOnce and runs once on a blocking thread. This is the analogue of offloading work to a Node worker_thread, but with far less ceremony.

Note: spawn_blocking is for blocking work (CPU-bound loops, synchronous I/O), not for parallelizing async work. For genuine CPU-bound parallelism across cores, a thread pool like rayon is often the better tool — see async-vs-sync.md.

Tasks vs OS Threads

It is worth being precise, because “task” and “thread” are casually conflated. Rust gives you both: std::thread::spawn for OS threads and tokio::spawn for async tasks.

An OS thread:

1
use std::thread;
2

3
fn main() {
4
    // An OS thread: ~megabytes of stack, scheduled by the kernel.
5
    let handle = thread::spawn(|| {
6
        let mut sum = 0u64;
7
        for i in 1..=100 { sum += i; }
8
        sum
9
    });
10

11
    // join() blocks the current thread until the spawned one finishes.
12
    let result = handle.join().expect("thread panicked");
13
    println!("sum = {result}");
14
}

Real output:

1
sum = 5050

The APIs look almost identical (spawn → handle → join/await), but the machinery underneath is very different:

Aspect	OS thread (`std::thread::spawn`)	Async task (`tokio::spawn`)
Created by	The operating system kernel	The Tokio runtime (in user space)
Stack	Large, fixed (often ~2–8 MB)	Tiny; grows from the heap as the state machine needs
Cost to create	Relatively expensive (syscall)	Very cheap (an allocation + queue push)
How many feasible	Thousands	Hundreds of thousands to millions
Scheduling	Pre-emptive, by the kernel	Cooperative, at `.await` points, by Tokio
Blocking is fine?	Yes — that is what threads are for	No — blocks the worker; use `spawn_blocking`
Get the result	`handle.join()` (blocks)	`handle.await` (yields)
Best for	CPU-bound work, blocking calls	I/O-bound concurrency at scale

The mental model: a task is a lightweight, cooperatively-scheduled job that the runtime multiplexes onto a small pool of OS threads. You can have a million tasks running on, say, eight threads. You cannot have a million OS threads — you would exhaust memory on stacks alone. This is exactly why network servers (which juggle huge numbers of mostly-idle connections) are built on tasks, not threads.

Tip: Choosing between async tasks, OS threads, and spawn_blocking is the central decision of async-vs-sync.md. The short version: I/O-bound and high-concurrency → tasks; CPU-bound → threads / rayon / spawn_blocking.

Key Differences

Concept	JavaScript / Node.js	Rust + Tokio
Unit of concurrency	A promise on the single event loop	A task on a (possibly multi-thread) runtime
Parallelism	None for JS code (one thread); `worker_threads` for parallel	Real parallelism across worker threads by default
Starting work	Calling an async fn (eager)	`tokio::spawn` (a bare future is lazy until spawned/awaited)
Handle to the result	The returned `Promise`	`JoinHandle<T>`
Result type	`T` (or a rejection)	`Result<T, JoinError>`
A panic / throw in one job	Unhandled rejection; isolated	Caught by runtime → `JoinError`; rest of program survives
Cancellation	Manual via `AbortController`	`handle.abort()` (cancels at next `.await`)
Offloading blocking/CPU work	`worker_threads`	`tokio::task::spawn_blocking` (or threads / `rayon`)
Capturing outside data	Closure captures by reference, same heap	Must be `Send + 'static`: `async move`, `Arc`, owned data

The two rows that trip up TypeScript developers most are “Result type” and “capturing outside data.” A JoinHandle is not a transparent Promise<T>; you must handle the JoinError. And you cannot casually close over a local let the way a JS arrow function does — the 'static/Send bounds force you to move or share ownership.

Note: “Concurrency” and “parallelism” are not the same thing, and Tokio gives you both depending on the scheduler. The distinction (and why a single-thread runtime is still concurrent) is covered in concurrency.md.

Common Pitfalls

Pitfall 1: Borrowing a local into a spawned task (missing `move`)

A spawned task is 'static, so it cannot borrow main’s local variables — the task might outlive the stack frame they live in:

1
#[tokio::main]
2
async fn main() {
3
    let name = String::from("Ada");
4

5
    let handle = tokio::spawn(async {
6
        // does not compile (error[E0373]): borrows `name`, but the task
7
        // may outlive main's stack frame.
8
        println!("hello, {name}");
9
    });
10

11
    handle.await.unwrap();
12
}

Real compiler output:

1
error[E0373]: async block may outlive the current function, but it borrows `name`, which is owned by the current function
2
 --> src/main.rs:5:31
3
  |
4
5 |     let handle = tokio::spawn(async {
5
  |                               ^^^^^ may outlive borrowed value `name`
6
6 |         // does not compile (error[E0373]): borrows `name`, but the task
7
7 |         println!("hello, {name}");
8
  |                           ---- `name` is borrowed here
9
  |
10
  = note: async blocks are not executed immediately and must either take a reference or ownership of outside variables they use
11
help: to force the async block to take ownership of `name` (and any other referenced variables), use the `move` keyword
12
  |
13
5 |     let handle = tokio::spawn(async move {
14
  |                                     ++++

Fix: the compiler tells you exactly what to do — add move so the task takes ownership: tokio::spawn(async move { println!("hello, {name}"); }). To share data across several tasks instead of moving it into one, wrap it in Arc and clone the Arc per task (see arc-mutex-pattern.md).

Pitfall 2: Holding a non-`Send` value across an `.await` in a spawned task

A spawned future must be Send. If you hold a non-Send type — Rc, RefCell, a MutexGuard from std::sync — across an .await, the future becomes non-Send and spawn rejects it:

1
use std::rc::Rc;
2
use std::time::Duration;
3
use tokio::time::sleep;
4

5
#[tokio::main]
6
async fn main() {
7
    let handle = tokio::spawn(async {
8
        // does not compile: Rc is not Send; held across .await.
9
        let data = Rc::new(vec![1, 2, 3]);
10
        sleep(Duration::from_millis(10)).await;
11
        println!("{:?}", data);
12
    });
13

14
    handle.await.unwrap();
15
}

Real compiler output (trimmed):

1
error: future cannot be sent between threads safely
2
   --> src/main.rs:7:18
3
    |
4
  7 |       let handle = tokio::spawn(async {
5
    |  __________________^
6
    | |______^ future created by async block is not `Send`
7
    |
8
    = help: within `{async block@src/main.rs:7:31: 7:36}`, the trait `Send` is not implemented for `Rc<Vec<i32>>`
9
note: future is not `Send` as this value is used across an await
10
   --> src/main.rs:10:42
11
    |
12
  9 |         let data = Rc::new(vec![1, 2, 3]);
13
    |             ---- has type `Rc<Vec<i32>>` which is not `Send`
14
 10 |         sleep(Duration::from_millis(10)).await;
15
    |                                          ^^^^^ await occurs here, with `data` maybe used later
16
note: required by a bound in `tokio::spawn`

Fix: use a Send equivalent — Arc instead of Rc, the async-aware tokio::sync::Mutex instead of std::sync::Mutex if a guard must cross an .await (see sync-primitives.md). Or restructure so the non-Send value is dropped before the .await. (TypeScript has no analogue to this error class — single-threaded JS never asks whether a value is thread-safe.)

Pitfall 3: Blocking the runtime with synchronous work

This one compiles and runs, so the compiler will not save you. A spawned task that runs a long synchronous loop or calls std::thread::sleep does not yield — it pins a worker thread and starves other tasks:

1
// Conceptual anti-pattern (compiles, but misbehaves):
2
// std::thread::sleep blocks the WHOLE worker thread, not just this task.
3
tokio::spawn(async {
4
    std::thread::sleep(std::time::Duration::from_secs(5)); // blocks the worker!
5
    // ... other tasks on this thread cannot run for 5 seconds.
6
});

Fix: for async waiting, use tokio::time::sleep(...).await (yields the worker). For genuinely blocking or CPU-bound code, use tokio::task::spawn_blocking. This is the same lesson as “never block the Node event loop,” but Tokio gives you spawn_blocking as a clean offload. (Tokio can detect some long blocking stalls and log a warning, but it cannot fix them for you.)

Pitfall 4: Spawning a future and forgetting it does nothing without a runtime, or expecting `T` instead of `Result<T, _>`

Two smaller traps:

Calling tokio::spawn outside any runtime panics at runtime (there is no reactor running...) — covered in tokio-setup.md.
handle.await gives a Result, so let x: u64 = handle.await; fails to compile (you get Result<u64, JoinError>). Use handle.await? (if your function returns a compatible error) or handle.await.unwrap() / .expect(...) while prototyping.

Best Practices

Reach for `join!` before `spawn` when awaiting a fixed set

If you simply want to run a known set of futures concurrently and wait for all of them, tokio::join! is lighter than spawning: it runs them on the current task with no Send + 'static requirement and no extra task allocation. Use spawn when a task must outlive the current scope, run on another thread, or be cancelled independently.

Use a `JoinSet` for dynamic groups of tasks

When you spawn a variable number of tasks and want to collect results as they finish, tokio::task::JoinSet is cleaner than a Vec<JoinHandle<_>>. It owns the handles, hands you results in completion order, and can abort the whole group at once:

1
use tokio::task::JoinSet;
2

3
async fn work(id: u32) -> u32 {
4
    id * id
5
}
6

7
#[tokio::main]
8
async fn main() {
9
    let mut set = JoinSet::new();
10
    for id in 1..=5 {
11
        set.spawn(work(id));
12
    }
13

14
    let mut total = 0;
15
    // join_next yields results as tasks finish, in completion order.
16
    while let Some(res) = set.join_next().await {
17
        total += res.expect("task panicked");
18
    }
19
    println!("total = {total}");
20
}

Real output:

1
total = 55

Dropping a JoinSet aborts all its tasks, which makes it a good fit for structured, scoped concurrency.

Always decide what a `JoinError` means

Do not reflexively .unwrap() every handle in production. Decide deliberately: propagate with ?, retry, log and continue, or treat a panicked worker as fatal. The Result<T, JoinError> is there so you make that choice explicitly.

Share state with `Arc`, not by capturing references

Because tasks are 'static, share read-only data with Arc<T> (clone the Arc into each task) and shared mutable state with Arc<Mutex<T>> / Arc<RwLock<T>>. See arc-mutex-pattern.md for the full pattern and sync-primitives.md for choosing std vs Tokio locks.

Keep `spawn_blocking` closures genuinely blocking-only

Put only synchronous, blocking code inside spawn_blocking. Do not call .await inside it (it is not an async context) and do not use it to “parallelize” async work — that is what spawn and join! are for. Bound the blocking pool with max_blocking_threads if you offload a lot.

Name long-lived tasks for observability

The unstable tokio::task::Builder can name tasks (under tokio_unstable), and the tracing crate is the idiomatic way to instrument tasks in production. Even without that, prefer holding handles (or a JoinSet) for important background work so failures surface instead of vanishing into a detached task.

Real-World Example

A production-flavored pattern: a small concurrent crawler. We spawn one task per URL, cap how many run at once with a Semaphore (like a connection-pool limit), fetch the body asynchronously, and offload the CPU-bound checksum to spawn_blocking. Each task returns its result through a JoinHandle.

1
use std::sync::Arc;
2
use std::time::Duration;
3
use tokio::sync::Semaphore;
4
use tokio::task::JoinHandle;
5
use tokio::time::sleep;
6

7
/// Simulates fetching a URL (I/O-bound, async).
8
async fn fetch(url: &str) -> String {
9
    sleep(Duration::from_millis(20)).await;
10
    format!("<html>{url}</html>")
11
}
12

13
/// Simulates parsing/hashing the body (CPU-bound, synchronous).
14
fn checksum(body: &str) -> u64 {
15
    body.bytes().fold(0u64, |acc, b| acc.wrapping_mul(31).wrapping_add(b as u64))
16
}
17

18
#[tokio::main]
19
async fn main() {
20
    let urls = vec![
21
        "https://a.example", "https://b.example",
22
        "https://c.example", "https://d.example",
23
    ];
24

25
    // Limit how many fetches run at once (like a connection-pool cap).
26
    let limit = Arc::new(Semaphore::new(2));
27

28
    let mut handles: Vec<JoinHandle<(String, u64)>> = Vec::new();
29
    for url in urls {
30
        let limit = Arc::clone(&limit);
31
        let url = url.to_string();
32
        handles.push(tokio::spawn(async move {
33
            // Hold a permit for the duration of the fetch.
34
            let _permit = limit.acquire().await.expect("semaphore closed");
35
            let body = fetch(&url).await;
36

37
            // Offload the CPU-bound hashing to the blocking pool.
38
            let hash = tokio::task::spawn_blocking(move || checksum(&body))
39
                .await
40
                .expect("blocking task panicked");
41

42
            (url, hash)
43
        }));
44
    }
45

46
    let mut results = Vec::new();
47
    for handle in handles {
48
        results.push(handle.await.expect("worker panicked"));
49
    }
50
    results.sort();
51

52
    for (url, hash) in results {
53
        println!("{url} -> {hash}");
54
    }
55
}

Real output:

1
https://a.example -> 5843935939460435433
2
https://b.example -> 6847466025596709832
3
https://c.example -> 7850996111732984231
4
https://d.example -> 8854526197869258630

This one example exercises every idea on the page: independent tasks via spawn, shared state via Arc, bounded concurrency via a Semaphore, CPU offload via spawn_blocking, and result collection via JoinHandle. The Semaphore is covered in sync-primitives.md.

Note: In a real crawler you would use reqwest for HTTP and propagate errors with Result and ? rather than expect. Error handling inside async is covered in async-await.md.

Exercises

Exercise 1: Spawn and sum

Difficulty: Easy

Objective: Spawn a batch of tasks, collect their results through JoinHandles, and combine them.

Instructions:

In an async main, spawn one task per n in 1..=10; each task should compute n * n.
Push each JoinHandle into a Vec.
Await every handle, summing the results, and print the total.
Remember you will need async move to capture n by value.

Solution

1
#[tokio::main]
2
async fn main() {
3
    let mut handles = Vec::new();
4
    for n in 1..=10u64 {
5
        handles.push(tokio::spawn(async move { n * n }));
6
    }
7

8
    let mut total = 0u64;
9
    for handle in handles {
10
        total += handle.await.expect("task panicked");
11
    }
12

13
    println!("sum of squares 1..=10 = {total}");
14
}

Output:

1
sum of squares 1..=10 = 385

async move is required because the task is 'static and must own n (Pitfall 1). handle.await returns Result<u64, JoinError>, so we .expect(...) to get the u64.

Exercise 2: Offload CPU work with `spawn_blocking`

Difficulty: Medium

Objective: Move a synchronous, CPU-bound computation off the async workers and await its result.

Instructions:

Write a synchronous fn count_primes(n: u64) -> u64 that counts primes below n (a deliberately naive loop is fine).
In async main, run count_primes(10_000) via tokio::task::spawn_blocking.
Print a message before awaiting (to show the runtime is free), then await the handle and print the count.

Solution

1
use tokio::task;
2

3
/// Synchronous, CPU-bound: count primes up to n (a stand-in for heavy work).
4
fn count_primes(n: u64) -> u64 {
5
    (2..n).filter(|&x| (2..x).all(|d| x % d != 0)).count() as u64
6
}
7

8
#[tokio::main]
9
async fn main() {
10
    let handle = task::spawn_blocking(|| count_primes(10_000));
11

12
    println!("counting primes on the blocking pool...");
13
    let primes = handle.await.expect("blocking task panicked");
14
    println!("primes below 10000 = {primes}");
15
}

Output:

1
counting primes on the blocking pool...
2
primes below 10000 = 1229

Running this loop inside a plain tokio::spawn would pin an async worker for the whole computation. spawn_blocking puts it on the dedicated blocking pool so the async workers stay responsive.

Exercise 3: Bounded batch with a deadline

Difficulty: Medium–Hard

Objective: Spawn a group of tasks into a JoinSet, collect whatever finishes within a time budget, and cancel the rest.

Instructions:

Write async fn process(id: u32) -> String that sleeps 200 ms for even ids and 20 ms for odd ones, then returns format!("job-{id}").
Spawn process(1..=4) into a tokio::task::JoinSet.
Use tokio::select! with a 100 ms sleep deadline: drain join_next() until either all tasks finish or the deadline fires.
On deadline, call abort_all() and drain the set. Print the jobs that completed within budget (sorted).

Solution

1
use std::time::Duration;
2
use tokio::task::JoinSet;
3
use tokio::time::sleep;
4

5
async fn process(id: u32) -> String {
6
    // Tasks 2 and 4 are "slow"; the rest are quick.
7
    let delay = if id % 2 == 0 { 200 } else { 20 };
8
    sleep(Duration::from_millis(delay)).await;
9
    format!("job-{id}")
10
}
11

12
#[tokio::main]
13
async fn main() {
14
    let mut set = JoinSet::new();
15
    for id in 1..=4 {
16
        set.spawn(process(id));
17
    }
18

19
    // Give the whole batch a 100 ms budget; cancel whatever is left.
20
    let mut done = Vec::new();
21
    let deadline = sleep(Duration::from_millis(100));
22
    tokio::pin!(deadline);
23

24
    loop {
25
        tokio::select! {
26
            maybe = set.join_next() => {
27
                match maybe {
28
                    Some(res) => done.push(res.expect("task panicked")),
29
                    None => break, // all tasks finished
30
                }
31
            }
32
            _ = &mut deadline => {
33
                set.abort_all();      // cancel the unfinished slow tasks
34
                while set.join_next().await.is_some() {} // drain
35
                break;
36
            }
37
        }
38
    }
39

40
    done.sort();
41
    println!("completed within budget: {done:?}");
42
}

Output:

1
completed within budget: ["job-1", "job-3"]

The two fast (odd) jobs finish well under 100 ms; the slow (even) ones are cancelled by abort_all() when the deadline fires. tokio::pin! is needed because we poll the same deadline future across multiple select! iterations. select! is covered in select-join.md.

Spawning Tasks

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

What tokio::spawn returns and when the task starts

Awaiting the handle yields a Result

The 'static and Send bounds

Detaching: dropping the handle does not cancel the task

Cancelling with abort

spawn_blocking: the escape hatch for synchronous work

Tasks vs OS Threads

Key Differences

Common Pitfalls

Pitfall 1: Borrowing a local into a spawned task (missing move)

Pitfall 2: Holding a non-Send value across an .await in a spawned task

Pitfall 3: Blocking the runtime with synchronous work

Pitfall 4: Spawning a future and forgetting it does nothing without a runtime, or expecting T instead of Result<T, _>

Best Practices

Reach for join! before spawn when awaiting a fixed set

Use a JoinSet for dynamic groups of tasks

Always decide what a JoinError means

Share state with Arc, not by capturing references

Keep spawn_blocking closures genuinely blocking-only

Name long-lived tasks for observability

Real-World Example

Further Reading

Exercises

Exercise 1: Spawn and sum

Exercise 2: Offload CPU work with spawn_blocking

Exercise 3: Bounded batch with a deadline

What `tokio::spawn` returns and when the task starts

Awaiting the handle yields a `Result`

The `'static` and `Send` bounds

Cancelling with `abort`

`spawn_blocking`: the escape hatch for synchronous work

Pitfall 1: Borrowing a local into a spawned task (missing `move`)

Pitfall 2: Holding a non-`Send` value across an `.await` in a spawned task

Pitfall 4: Spawning a future and forgetting it does nothing without a runtime, or expecting `T` instead of `Result<T, _>`

Reach for `join!` before `spawn` when awaiting a fixed set

Use a `JoinSet` for dynamic groups of tasks

Always decide what a `JoinError` means

Share state with `Arc`, not by capturing references

Keep `spawn_blocking` closures genuinely blocking-only

Exercise 2: Offload CPU work with `spawn_blocking`