Concurrency vs Parallelism

27 min read

Coming from Node.js, you have lived your whole career inside a single-threaded event loop: lots of things happen “at once,” but only one line of your JavaScript ever executes at a time. Rust forces you to be precise about a distinction Node mostly hides — the difference between concurrency (juggling many tasks) and parallelism (actually running them simultaneously on multiple cores) — and gives you safe tools for both.

Quick Overview

Concurrency is dealing with many things at once (structure); parallelism is doing many things at once (execution). Node.js gives you concurrency on one thread via the event loop; Rust gives you concurrency and opt-in, compiler-checked parallelism. This page covers how Rust’s async tasks relate to OS threads, how to structure groups of tasks so they don’t leak, and how to cancel work cleanly — something that is genuinely hard in JavaScript.

Note: This page is about the concepts and patterns of concurrency. The mechanics live in sibling pages: spawning tasks, select!/join!, channels, and sync primitives. The deeper “async vs threads vs blocking” decision is its own page: async-vs-sync.md.

TypeScript/JavaScript Example

In Node.js, you achieve concurrency by kicking off multiple promises and awaiting them together. This looks parallel, but the JavaScript callbacks never run simultaneously — the event loop interleaves them on one thread. The waiting (I/O, timers) happens off-thread; your code does not.

1
// TypeScript / JavaScript (Node v22)
2
// Concurrency on one thread: three "downloads" overlap because the WAITING
3
// is offloaded to libuv, but our JS code runs one statement at a time.
4

5
function fetchUser(id: number): Promise<string> {
6
  return new Promise((resolve) => {
7
    setTimeout(() => resolve(`user-${id}`), 100); // simulated network latency
8
  });
9
}
10

11
async function main() {
12
  const start = Date.now();
13

14
  // Promise.all runs all three concurrently — total ~100ms, not ~300ms.
15
  const users = await Promise.all([fetchUser(1), fetchUser(2), fetchUser(3)]);
16

17
  console.log(`fetched ${JSON.stringify(users)} in ~${Date.now() - start} ms`);
18
}
19

20
main();
21
// fetched ["user-1","user-2","user-3"] in ~10X ms

For CPU-bound work, Node cannot help you with Promise.all — a heavy for loop blocks the event loop and everything else stalls. To get real parallelism you must reach for Worker Threads (or child processes) and pass messages across a serialization boundary:

1
// CPU-bound parallelism in Node requires Worker Threads — a separate V8 isolate.
2
import { Worker } from "node:worker_threads";
3

4
function countPrimes(maxN: number): Promise<number> {
5
  return new Promise((resolve, reject) => {
6
    const worker = new Worker("./prime-worker.js", { workerData: maxN });
7
    worker.on("message", resolve);
8
    worker.on("error", reject);
9
  });
10
}
11

12
// Each worker is a heavyweight thread with its OWN heap; data is copied, not shared.

Rust Equivalent

Rust draws the same picture, but the pieces are explicit. A task (tokio::spawn) is the lightweight, async analogue of “kick off a promise.” On Tokio’s default multi-thread runtime, those tasks are scheduled across a pool of worker threads, so I/O-bound tasks run concurrently and CPU work spread across them can run in parallel — no Worker-Thread ceremony, no copying.

1
// Rust + Tokio 1.52 — concurrency via tasks.
2
use std::time::Instant;
3
use tokio::time::{sleep, Duration};
4

5
// Simulated I/O-bound work: fetch a user record from a remote service.
6
async fn fetch_user(id: u32) -> String {
7
    sleep(Duration::from_millis(100)).await; // pretend this is a network round-trip
8
    format!("user-{id}")
9
}
10

11
#[tokio::main]
12
async fn main() {
13
    let start = Instant::now();
14

15
    // Spawn three tasks. Each runs CONCURRENTLY on the runtime.
16
    // On the multi-thread scheduler they may also run in PARALLEL.
17
    let handles: Vec<_> = (1..=3)
18
        .map(|id| tokio::spawn(fetch_user(id)))
19
        .collect();
20

21
    // Await all of them (like Promise.all).
22
    let mut users = Vec::new();
23
    for handle in handles {
24
        users.push(handle.await.unwrap());
25
    }
26

27
    println!("fetched {:?} in ~{} ms", users, start.elapsed().as_millis());
28
}

Real output (Rust 1.96, Tokio 1.52):

1
fetched ["user-1", "user-2", "user-3"] in ~102 ms

For CPU-bound parallelism Rust does not need a separate isolate or message passing. You can use plain OS threads with shared, borrow-checked memory:

1
use std::thread;
2

3
// CPU-bound work split across OS threads — true parallelism, no async needed.
4
fn sum_range(lo: u64, hi: u64) -> u64 {
5
    (lo..hi).fold(0u64, |a, x| a.wrapping_add(x.wrapping_mul(x)))
6
}
7

8
fn main() {
9
    // thread::scope lets borrowed data cross into threads safely (stable since 1.63).
10
    let total = thread::scope(|s| {
11
        let h1 = s.spawn(|| sum_range(0, 50_000_000));
12
        let h2 = s.spawn(|| sum_range(50_000_000, 100_000_000));
13
        h1.join().unwrap().wrapping_add(h2.join().unwrap())
14
    });
15
    println!("sum = {total}");
16
}

Note: Mixing the two is also fine and idiomatic: run CPU-bound work on threads via spawn_blocking from inside async code, so it does not stall the event loop. More on that choice in async-vs-sync.md.

Detailed Explanation

Concurrency is structure; parallelism is execution

The canonical phrasing (from Rob Pike) is: “Concurrency is about dealing with lots of things at once. Parallelism is about doing lots of things at once.” Concurrency is how you structure a program as independently-progressing tasks; parallelism is a runtime property — whether those tasks happen to execute at the same instant on different cores.

A Node.js server is concurrent (thousands of in-flight requests) but not parallel (one thread runs your JS).
A Rust tokio server on the multi-thread runtime is both: thousands of concurrent tasks, executing across N worker threads in parallel.
A single-threaded tokio runtime (flavor = "current_thread") is concurrent but not parallel — the closest match to Node’s model.

You write the same async code either way; the runtime flavor decides whether parallelism is on the table. That separation is the whole point: you express concurrency once, and choose the execution strategy separately.

Tasks are not threads

A tokio::spawned task is not an OS thread. It is a future that the runtime schedules cooperatively onto a small pool of worker threads (by default, one per CPU core). This is “M:N” scheduling: M tasks multiplexed onto N threads.

The practical consequence is that tasks are cheap. Spawning a hundred thousand of them is routine; spawning a hundred thousand OS threads would exhaust memory because each thread reserves megabytes of stack.

1
use std::sync::atomic::{AtomicU64, Ordering};
2
use std::sync::Arc;
3

4
// Tasks are cheap: spawning 100,000 of them is fine. 100,000 OS THREADS
5
// would exhaust memory (each thread reserves ~MBs of stack).
6
#[tokio::main]
7
async fn main() {
8
    let counter = Arc::new(AtomicU64::new(0));
9
    let mut handles = Vec::with_capacity(100_000);
10

11
    for _ in 0..100_000 {
12
        let counter = Arc::clone(&counter);
13
        handles.push(tokio::spawn(async move {
14
            counter.fetch_add(1, Ordering::Relaxed);
15
        }));
16
    }
17
    for h in handles {
18
        h.await.unwrap();
19
    }
20

21
    println!("100,000 tasks all ran: counter = {}", counter.load(Ordering::Relaxed));
22
}

Real output:

1
100,000 tasks all ran: counter = 100000

Tip: Use a task for I/O-bound concurrency (waiting on sockets, timers, databases). Use a thread (or spawn_blocking) for CPU-bound or blocking work. The litmus test: does it spend its time waiting, or computing? Waiting → task; computing → thread. See async-vs-sync.md.

The runtime flavor decides parallelism

Tasks only run in parallel if the runtime has more than one worker thread. Compare the two flavors by counting the distinct OS threads that actually execute the tasks.

On the multi-thread runtime (the default for #[tokio::main]), tasks spread across worker threads:

1
use std::collections::HashSet;
2
use std::sync::{Arc, Mutex};
3

4
#[tokio::main] // multi-thread: one worker per CPU core by default
5
async fn main() {
6
    let threads = Arc::new(Mutex::new(HashSet::new()));
7
    let mut handles = Vec::new();
8

9
    for _ in 0..8 {
10
        let threads = Arc::clone(&threads);
11
        handles.push(tokio::spawn(async move {
12
            // A CPU loop so a worker stays busy long enough to spread the load.
13
            let mut acc = 0u64;
14
            for i in 0..20_000_000u64 {
15
                acc = acc.wrapping_add(i);
16
            }
17
            threads.lock().unwrap().insert(format!("{:?}", std::thread::current().id()));
18
            acc
19
        }));
20
    }
21
    for h in handles {
22
        h.await.unwrap();
23
    }
24

25
    let count = threads.lock().unwrap().len();
26
    println!("8 tasks ran across {count} distinct OS threads");
27
}

Real output on an 8+ core machine:

1
8 tasks ran across 8 distinct OS threads

Note: That 8 is the worker-thread count, which equals the number of CPU cores on the test machine. On a 4-core box you would see 4; the exact number is hardware-dependent. The point is more than one — real parallelism.

The current-thread runtime (flavor = "current_thread") runs everything on one thread — concurrent, never parallel, exactly like Node’s event loop:

1
use std::collections::HashSet;
2
use std::sync::{Arc, Mutex};
3

4
// current_thread flavor: everything runs on ONE thread (like Node's event loop).
5
// Tasks are CONCURRENT (interleaved) but never PARALLEL.
6
#[tokio::main(flavor = "current_thread")]
7
async fn main() {
8
    let threads = Arc::new(Mutex::new(HashSet::new()));
9
    let mut handles = Vec::new();
10

11
    for _ in 0..8 {
12
        let threads = Arc::clone(&threads);
13
        handles.push(tokio::spawn(async move {
14
            tokio::task::yield_now().await; // let the single thread interleave tasks
15
            threads.lock().unwrap().insert(format!("{:?}", std::thread::current().id()));
16
        }));
17
    }
18
    for h in handles {
19
        h.await.unwrap();
20
    }
21

22
    let count = threads.lock().unwrap().len();
23
    println!("8 tasks ran across {count} distinct OS thread(s)");
24
}

Real output:

1
8 tasks ran across 1 distinct OS thread(s)

This is why the multi-thread runtime requires your tasks to be Send: a task may be moved to a different worker thread at an .await point. The single-thread runtime has no such requirement. (See the Pitfalls section for the !Send error this produces.) Runtime flavors are covered in depth in tokio-intro.md.

Concurrency on one thread is still a win for I/O

Even with no parallelism, concurrency speeds up I/O-bound work, because waiting overlaps. Here three async sleeps run on a single thread and still finish in ~100ms, not ~300ms — the thread is free to advance other tasks while each one waits:

1
use std::time::Instant;
2

3
// tokio::time::sleep yields to the runtime, so other tasks run during the wait.
4
async fn good_task(id: u32) {
5
    tokio::time::sleep(std::time::Duration::from_millis(100)).await;
6
    println!("  good_task {id} done");
7
}
8

9
#[tokio::main(flavor = "current_thread")]
10
async fn main() {
11
    let start = Instant::now();
12
    tokio::join!(good_task(1), good_task(2), good_task(3));
13
    println!("non-blocking version took ~{} ms", start.elapsed().as_millis());
14
}

Real output (ordering of the “done” lines varies):

1
  good_task 2 done
2
  good_task 3 done
3
  good_task 1 done
4
non-blocking version took ~102 ms

This is the heart of why async exists: a single thread can serve thousands of waiting connections. Parallelism adds throughput on top; concurrency alone already wins for I/O.

Structured concurrency: don’t leak tasks

A loose tokio::spawn is fire-and-forget — if the parent finishes, the child may be silently abandoned, and errors inside it vanish. Structured concurrency keeps a group of tasks tied to a scope: you spawn them into a container, await them together, and when the container is dropped any stragglers are cancelled. Tokio’s JoinSet is the workhorse:

1
use tokio::task::JoinSet;
2

3
async fn process(item: u32) -> u32 {
4
    tokio::time::sleep(tokio::time::Duration::from_millis(50)).await;
5
    item * item
6
}
7

8
#[tokio::main]
9
async fn main() {
10
    let mut set = JoinSet::new();
11

12
    // Spawn a dynamic number of tasks into a structured set.
13
    for item in 1..=5 {
14
        set.spawn(process(item));
15
    }
16

17
    // join_next waits for the next task to finish, in completion order.
18
    // When `set` is dropped, any still-running tasks are aborted automatically.
19
    let mut total = 0;
20
    while let Some(res) = set.join_next().await {
21
        total += res.unwrap();
22
    }
23

24
    println!("sum of squares = {total}");
25
}

Real output:

1
sum of squares = 55

The key safety property: JoinSet owns the tasks. If main returns early, panics, or you break out of the loop, the set’s Drop aborts the unfinished tasks. There are no orphaned, still-running tasks logging into the void — the failure mode you get with bare spawn. This is the Rust answer to a JavaScript codebase littered with un-awaited promises.

Cancellation: a first-class concept

This is where Rust pulls decisively ahead of JavaScript. A Promise, once started, runs to completion even if nobody is listening — there is no built-in .cancel(). (The AbortController/AbortSignal API helps, but only for APIs that explicitly opt in, like fetch.) In Rust, a future is just a value, so dropping it stops its work, and its destructors run for clean teardown. Three layers, from coarse to fine:

Drop the future → its poll is never called again; its Drop impls run.
JoinHandle::abort() / JoinSet::abort_all() → ask the runtime to stop a spawned task at its next .await.
Cooperative cancellation with a CancellationToken → the task checks a signal and winds down gracefully.

The simplest form is a timeout, which drops the loser:

1
use tokio::time::{timeout, sleep, Duration};
2

3
async fn slow_query() -> &'static str {
4
    sleep(Duration::from_millis(500)).await;
5
    "query result"
6
}
7

8
#[tokio::main]
9
async fn main() {
10
    // Like Promise.race([query, timer]) — but the losing future is actually
11
    // DROPPED (cancelled), not left running in the background.
12
    match timeout(Duration::from_millis(100), slow_query()).await {
13
        Ok(value) => println!("got: {value}"),
14
        Err(_elapsed) => println!("timed out — the query future was dropped/cancelled"),
15
    }
16
}

Real output:

1
timed out — the query future was dropped/cancelled

Because cancellation runs destructors, you get RAII-style cleanup for free. A guard’s Drop fires whether the task completes or is aborted:

1
use tokio::time::{sleep, Duration};
2

3
// A guard whose Drop runs even when the future is cancelled (dropped).
4
struct CleanupGuard;
5
impl Drop for CleanupGuard {
6
    fn drop(&mut self) {
7
        println!("  cleanup: releasing resources");
8
    }
9
}
10

11
async fn job() {
12
    let _guard = CleanupGuard; // Drop runs if the future is cancelled mid-flight
13
    println!("  job started");
14
    sleep(Duration::from_secs(10)).await; // never completes in this demo
15
    println!("  job finished"); // unreachable here
16
}
17

18
#[tokio::main]
19
async fn main() {
20
    let handle = tokio::spawn(job());
21
    sleep(Duration::from_millis(50)).await; // let the job start
22

23
    handle.abort(); // request cancellation
24
    let result = handle.await;
25
    println!("task was cancelled: {}", result.unwrap_err().is_cancelled());
26
}

Real output:

1
  job started
2
  cleanup: releasing resources
3
task was cancelled: true

Notice the CleanupGuard::drop ran even though the job never reached its own end — that is the cancellation path executing your teardown. In JavaScript there is no equivalent: a Promise that “loses” a Promise.race keeps executing, and any cleanup you wrote after its await simply never fires.

Warning: Cancellation in Rust happens only at .await points. A task that enters a long synchronous CPU loop with no .await cannot be aborted until it next yields — the abort is recorded but only takes effect at the next suspension. This is why CPU-bound work belongs on a thread / spawn_blocking, not inline in a task.

Cooperative cancellation with `CancellationToken`

For graceful shutdown — letting a worker finish its current unit and clean up — use a CancellationToken from tokio-util. Cloning the token shares one cancellation state, so a single .cancel() signals every holder at once. This is the idiomatic shape for a long-lived worker loop, combining it with select!:

1
use tokio::time::{sleep, Duration};
2
use tokio_util::sync::CancellationToken;
3
use tokio::task::JoinSet;
4

5
// Three workers that share one CancellationToken. When the token fires,
6
// they all wind down — structured, parent-driven cancellation.
7
async fn worker(id: u32, token: CancellationToken) {
8
    let mut done = 0;
9
    loop {
10
        tokio::select! {
11
            // Branch 1: cancellation requested — exit the loop cleanly.
12
            _ = token.cancelled() => {
13
                println!("  worker {id}: stopping (did {done} units)");
14
                return;
15
            }
16
            // Branch 2: do one unit of work.
17
            _ = sleep(Duration::from_millis(30)) => {
18
                done += 1;
19
            }
20
        }
21
    }
22
}
23

24
#[tokio::main]
25
async fn main() {
26
    let token = CancellationToken::new();
27
    let mut set = JoinSet::new();
28
    for id in 1..=3 {
29
        set.spawn(worker(id, token.clone())); // clones share one cancellation state
30
    }
31

32
    // Run for a bit, then signal shutdown to all workers at once.
33
    sleep(Duration::from_millis(100)).await;
34
    println!("main: broadcasting shutdown");
35
    token.cancel();
36

37
    // Wait for every worker to finish its cleanup before exiting.
38
    while set.join_next().await.is_some() {}
39
    println!("main: all workers stopped cleanly");
40
}

Real output:

1
main: broadcasting shutdown
2
  worker 1: stopping (did 3 units)
3
  worker 2: stopping (did 3 units)
4
  worker 3: stopping (did 3 units)
5
main: all workers stopped cleanly

This is the difference between forced cancellation (abort — stop at the next .await, no chance to react) and cooperative cancellation (the worker observes the token and decides how to wind down). For graceful shutdown you almost always want the cooperative version, because the worker controls its own teardown.

Key Differences

Aspect	Node.js / TypeScript	Rust + Tokio
Concurrency unit	Promise on the event loop	Task (`tokio::spawn`) or future
Parallelism unit	Worker Thread (separate isolate)	OS thread / multi-thread runtime workers
Threads under the hood	One JS thread + libuv pool	M:N — many tasks over N worker threads
Default execution	Concurrent, single-threaded	Concurrent + parallel (multi-thread runtime)
Single-threaded mode	The only mode for JS code	Opt-in (`flavor = "current_thread"`)
Sharing data across workers	Copy / structured clone / `SharedArrayBuffer`	Borrow-checked shared memory (`Arc`, `Mutex`)
Task cost	Promise is cheap; Worker is heavy	Task is very cheap; thread is heavy
Cancellation	No built-in cancel; `AbortController` opt-in	Drop the future, `abort()`, or `CancellationToken`
Cleanup on cancel	Code after a lost `await` never runs	`Drop` impls run on cancellation
Leak protection	Un-awaited promises run unsupervised	`JoinSet` cancels stragglers on drop

Why Rust makes you choose

Node’s “everything is one thread” model is simpler but limiting: CPU-bound work blocks everything, and parallelism means crossing a serialization boundary into a Worker. Rust separates the two axes — you write concurrent async code, then pick a runtime flavor for the parallelism you want — and the borrow checker lets parallel threads share memory safely (data races are a compile error). This is “fearless concurrency”: the cost is that the compiler insists you make Send/Sync correct up front, which can feel strict at first.

The “cancellation gap” closed

The most underappreciated win is cancellation. In JavaScript, “stop this in-flight work” ranges from awkward to impossible. In Rust it is the default consequence of dropping a value, with destructors guaranteeing cleanup. This makes timeouts, “race and discard the loser,” and graceful shutdown straightforward and correct — patterns that are perennially buggy in Node services.

Common Pitfalls

Pitfall 1: Non-`Send` data held across `.await` in a spawned task

The multi-thread runtime may move a task between worker threads at any .await, so spawned futures must be Send. Holding a !Send type (like Rc, the non-atomic reference counter — see Section 05: reference counting) across an .await makes the whole future !Send, and tokio::spawn rejects it.

1
use std::rc::Rc;
2

3
#[tokio::main]
4
async fn main() {
5
    tokio::spawn(async {
6
        let data = Rc::new(5); // Rc is !Send
7
        tokio::time::sleep(tokio::time::Duration::from_millis(1)).await;
8
        println!("{}", data); // data held across .await -> future is !Send
9
    });
10
}

Real compiler error (cargo build):

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

The fixes: use Arc instead of Rc (it is the atomic, Send reference counter), or restructure so the !Send value is dropped before the .await (e.g., enclose it in a { } block that ends first). If the work genuinely must stay on one thread, use a LocalSet or the current_thread runtime.

Pitfall 2: Blocking the runtime with synchronous waits

The number-one async footgun for Node developers: calling a blocking function (std::thread::sleep, synchronous file/network I/O, a tight CPU loop) directly inside a task. It does not yield, so it freezes the worker thread, starving every other task scheduled there. This compiles and runs — it is a performance bug, which makes it sneaky.

1
use std::time::Instant;
2

3
// Anti-pattern: std::thread::sleep BLOCKS the worker thread, so other tasks
4
// on that thread cannot make progress.
5
async fn bad_task(id: u32) {
6
    std::thread::sleep(std::time::Duration::from_millis(100)); // blocks the thread!
7
    println!("  bad_task {id} done");
8
}
9

10
#[tokio::main(flavor = "current_thread")]
11
async fn main() {
12
    let start = Instant::now();
13
    // Even though we "join" them, on a single-threaded runtime they run serially
14
    // because each one monopolizes the only worker thread.
15
    tokio::join!(bad_task(1), bad_task(2), bad_task(3));
16
    println!("blocking version took ~{} ms", start.elapsed().as_millis());
17
}

Real output — ~300ms (serial) instead of ~100ms (overlapping):

1
  bad_task 1 done
2
  bad_task 2 done
3
  bad_task 3 done
4
blocking version took ~306 ms

The fix for waiting is the async equivalent (tokio::time::sleep(...).await, async I/O). The fix for genuine blocking/CPU work is tokio::task::spawn_blocking, which moves it onto a dedicated blocking-thread pool so the async workers stay free.

Pitfall 3: Confusing “concurrent” with “parallel”

Two sequential .awaits are not concurrent — the second future has not even started while the first runs (Rust futures are lazy; see promises-vs-futures.md). And concurrent is not the same as parallel: on a current_thread runtime, join!/select! interleave tasks on one thread with zero parallelism. If you measured join! of CPU-bound tasks on the single-thread runtime expecting a speedup, you would get none — there is only one core in play. Match the tool to the goal: join! for overlapping waiting, the multi-thread runtime or threads for overlapping computing.

Pitfall 4: Assuming a Promise-style “cancel” cancels nothing

Because JavaScript Promises cannot really be cancelled, developers sometimes assume Rust’s are the same and leave work running. The opposite is true: in Rust, forgetting to keep a future alive cancels it. If you tokio::spawn a task and drop the JoinHandle without awaiting it, the task keeps running (spawn detaches it) — but if you build a future and never spawn or .await it, it never runs at all. And dropping a JoinSet aborts everything inside. The rule of thumb: a future’s lifetime is its work’s lifetime, unless you explicitly spawn to detach it.

Best Practices

Pick the runtime flavor deliberately. Default #[tokio::main] (multi-thread) for servers and parallel workloads; flavor = "current_thread" for CLIs, tests, or when every task is !Send and you want Node-like single-threaded semantics. See tokio-setup.md.
Prefer structured concurrency. Reach for JoinSet (or join!/try_join!) over scattered tokio::spawn so tasks are owned, awaited, and cancelled together. A bare spawn is “detach this from supervision” — use it intentionally.
Keep tasks non-blocking. Never call blocking code inside a task. Use async APIs for I/O and spawn_blocking for CPU/blocking work, so the scheduler can keep the event loop responsive.
Bound your concurrency. Unbounded spawn can overwhelm a database or remote API. Gate in-flight work with a Semaphore (shown below) — the safe analogue of a connection pool.
Design for cancellation from the start. Thread a CancellationToken through long-lived workers and select on it, so graceful shutdown is built in rather than bolted on. Let Drop handle resource cleanup.
Use Arc<Mutex<T>> for shared mutable state across tasks, and Arc alone for shared read-only data. The pattern is detailed in arc-mutex-pattern.md; when to use the async-aware tokio::sync::Mutex vs std::sync::Mutex is in sync-primitives.md.

Real-World Example

A concurrent fetcher that processes a list of URLs with bounded concurrency — the bread-and-butter of crawlers, batch importers, and fan-out API clients. It combines everything on this page: tasks for concurrency, a Semaphore to cap in-flight work (like a connection pool), and a JoinSet for structured collection so nothing leaks.

1
use std::sync::Arc;
2
use std::time::Instant;
3
use tokio::sync::Semaphore;
4
use tokio::task::JoinSet;
5
use tokio::time::{sleep, Duration};
6

7
/// Fetch one URL (simulated). Returns (url, byte length).
8
async fn fetch(url: String) -> (String, usize) {
9
    sleep(Duration::from_millis(100)).await; // simulated network latency
10
    (url.clone(), url.len() * 10)
11
}
12

13
#[tokio::main]
14
async fn main() {
15
    let urls: Vec<String> = (1..=10)
16
        .map(|i| format!("https://example.com/page/{i}"))
17
        .collect();
18

19
    // Limit concurrency to 3 in-flight requests at a time (like a connection pool).
20
    let limit = Arc::new(Semaphore::new(3));
21
    let mut set: JoinSet<(String, usize)> = JoinSet::new();
22
    let start = Instant::now();
23

24
    for url in urls {
25
        let limit = Arc::clone(&limit);
26
        set.spawn(async move {
27
            // Acquire a permit; this await blocks until a slot is free.
28
            let _permit = limit.acquire_owned().await.unwrap();
29
            fetch(url).await
30
            // _permit dropped here -> slot returned to the pool
31
        });
32
    }
33

34
    // Collect results as tasks finish. Dropping `set` would abort any stragglers.
35
    let mut total_bytes = 0;
36
    let mut count = 0;
37
    while let Some(res) = set.join_next().await {
38
        let (_url, bytes) = res.unwrap();
39
        total_bytes += bytes;
40
        count += 1;
41
    }
42

43
    println!(
44
        "fetched {count} pages ({total_bytes} bytes) in ~{} ms with max 3 concurrent",
45
        start.elapsed().as_millis()
46
    );
47
}

Real output (10 pages, 3 at a time, ~100ms each → ~4 batches):

1
fetched 10 pages (2610 bytes) in ~411 ms with max 3 concurrent

The timing tells the story: 10 requests at 100ms each, run three-wide, take roughly ceil(10 / 3) × 100 ≈ 400 ms rather than 1000ms (fully serial) or 100ms (fully unbounded). The Semaphore is the throttle, the JoinSet is the structure, and dropping either cleanly cancels everything in flight.

Note: In real code, fetch would use an HTTP client like reqwest and return a Result, which you would collect with try_join! or by matching in the loop. See select-join.md for the error-aware combinators and channels.md for streaming results back as they arrive rather than collecting at the end.

Exercises

Exercise 1: Concurrent, not sequential

Difficulty: Beginner

Objective: Turn a sequential set of I/O-bound calls into concurrent tasks and observe the timing collapse.

Instructions: The program below checks three services one after another, taking ~250ms. Rewrite it to run all three checks concurrently using tokio::spawn (or JoinSet), so the total time drops to roughly the slowest single check (~120ms). Print how many of the three are “healthy” (latency under 100ms).

1
use std::time::Instant;
2
use tokio::time::{sleep, Duration};
3

4
async fn check_health(service: &str, ms: u64) -> (String, bool) {
5
    sleep(Duration::from_millis(ms)).await;
6
    (service.to_string(), ms < 100)
7
}
8

9
#[tokio::main]
10
async fn main() {
11
    let start = Instant::now();
12
    // TODO: run these three concurrently instead of awaiting one at a time.
13
    let a = check_health("auth", 50).await;
14
    let b = check_health("db", 80).await;
15
    let c = check_health("cache", 120).await;
16
    let healthy = [a, b, c].iter().filter(|(_, ok)| *ok).count();
17
    println!("{healthy}/3 healthy in ~{} ms", start.elapsed().as_millis());
18
}

Solution

Spawn each check into a JoinSet so they overlap; collect as they complete. (You could also use tokio::join! since the count is fixed.)

1
use std::time::Instant;
2
use tokio::task::JoinSet;
3
use tokio::time::{sleep, Duration};
4

5
async fn check_health(service: &str, ms: u64) -> (String, bool) {
6
    sleep(Duration::from_millis(ms)).await;
7
    (service.to_string(), ms < 100)
8
}
9

10
#[tokio::main]
11
async fn main() {
12
    let start = Instant::now();
13
    let services = [("auth", 50u64), ("db", 80), ("cache", 120)];
14

15
    let mut set = JoinSet::new();
16
    for (name, ms) in services {
17
        set.spawn(check_health(name, ms));
18
    }
19

20
    let mut healthy = 0;
21
    let mut total = 0;
22
    while let Some(res) = set.join_next().await {
23
        let (name, ok) = res.unwrap();
24
        total += 1;
25
        if ok { healthy += 1; }
26
        println!("  {name}: {}", if ok { "healthy" } else { "DEGRADED" });
27
    }
28
    println!("{healthy}/{total} healthy in ~{} ms", start.elapsed().as_millis());
29
}

Real output (the per-service lines arrive in completion order, ~123ms total — the slowest check, not the sum):

1
  auth: healthy
2
  db: healthy
3
  cache: DEGRADED
4
2/3 healthy in ~123 ms

The three checks overlap, so the total is governed by the slowest one (~120ms), not their sum (~250ms). See select-join.md for the join! alternative.

Exercise 2: Fail fast and cancel the rest

Difficulty: Intermediate

Objective: Use structured concurrency to abort outstanding tasks the moment one fails.

Instructions: Three downloads run concurrently; one of them (id == 3) fails fast. Complete the program so that, on the first error, it prints the error, aborts the remaining in-flight downloads, and stops. Use a JoinSet and its abort_all() method.

1
use tokio::task::JoinSet;
2
use tokio::time::{sleep, Duration};
3

4
async fn download(id: u32, ms: u64) -> Result<String, String> {
5
    sleep(Duration::from_millis(ms)).await;
6
    if id == 3 {
7
        Err(format!("download {id} failed"))
8
    } else {
9
        Ok(format!("file-{id}"))
10
    }
11
}
12

13
#[tokio::main]
14
async fn main() {
15
    let mut set = JoinSet::new();
16
    set.spawn(download(1, 80));
17
    set.spawn(download(2, 40));
18
    set.spawn(download(3, 20)); // fails fastest
19

20
    // TODO: collect results; on the first Err, abort the rest and stop.
21
    while let Some(joined) = set.join_next().await {
22
        let _ = joined; // replace with real handling
23
    }
24
    println!("done");
25
}

Solution

1
use tokio::task::JoinSet;
2
use tokio::time::{sleep, Duration};
3

4
async fn download(id: u32, ms: u64) -> Result<String, String> {
5
    sleep(Duration::from_millis(ms)).await;
6
    if id == 3 {
7
        Err(format!("download {id} failed"))
8
    } else {
9
        Ok(format!("file-{id}"))
10
    }
11
}
12

13
#[tokio::main]
14
async fn main() {
15
    let mut set = JoinSet::new();
16
    set.spawn(download(1, 80));
17
    set.spawn(download(2, 40));
18
    set.spawn(download(3, 20)); // this one fails fastest
19

20
    // Stop at the first error; abort the remaining tasks.
21
    while let Some(joined) = set.join_next().await {
22
        match joined.unwrap() {
23
            Ok(file) => println!("ok: {file}"),
24
            Err(e) => {
25
                println!("error: {e} -> aborting remaining downloads");
26
                set.abort_all();
27
                break;
28
            }
29
        }
30
    }
31
    println!("done");
32
}

Real output (the fastest task fails first, so the others are aborted before they print):

1
error: download 3 failed -> aborting remaining downloads
2
done

This is the try_join! philosophy generalized to a dynamic set: the first failure short-circuits the group. abort_all() plus break ensures no orphaned tasks survive. Compare with select-join.md’s try_join!.

Exercise 3: Graceful shutdown with a cancellation token

Difficulty: Advanced

Objective: Build a long-running worker that shuts down cooperatively, finishing cleanly rather than being killed mid-step.

Instructions: Spawn a worker that processes “jobs” every 30ms in a loop. From main, let it run ~100ms, then signal a CancellationToken. The worker must detect the signal, print how many jobs it completed, and return. main should wait for the worker to finish before exiting. Add tokio-util to your Cargo.toml (cargo add tokio-util).

1
use tokio::time::{sleep, Duration};
2
use tokio_util::sync::CancellationToken;
3

4
async fn worker(token: CancellationToken) {
5
    let mut jobs = 0;
6
    loop {
7
        // TODO: select between the cancellation signal and doing one job.
8
        // On cancellation: print the job count and return.
9
        todo!()
10
    }
11
}
12

13
#[tokio::main]
14
async fn main() {
15
    let token = CancellationToken::new();
16
    let handle = tokio::spawn(worker(token.clone()));
17
    sleep(Duration::from_millis(100)).await;
18
    // TODO: request shutdown, then wait for the worker to finish.
19
    todo!()
20
}

Solution

1
use tokio::time::{sleep, Duration};
2
use tokio_util::sync::CancellationToken;
3

4
async fn worker(token: CancellationToken) {
5
    let mut jobs = 0;
6
    loop {
7
        tokio::select! {
8
            // Cancellation requested: report progress and exit cleanly.
9
            _ = token.cancelled() => {
10
                println!("worker: shutting down after {jobs} jobs");
11
                return;
12
            }
13
            // Otherwise, do one unit of work.
14
            _ = sleep(Duration::from_millis(30)) => {
15
                jobs += 1;
16
            }
17
        }
18
    }
19
}
20

21
#[tokio::main]
22
async fn main() {
23
    let token = CancellationToken::new();
24
    let handle = tokio::spawn(worker(token.clone()));
25

26
    sleep(Duration::from_millis(100)).await;
27
    println!("main: requesting shutdown");
28
    token.cancel();              // cooperative signal
29
    handle.await.unwrap();       // wait for clean teardown
30
    println!("main: worker stopped");
31
}

Real output (about three 30ms jobs fit into the 100ms window):

1
main: requesting shutdown
2
worker: shutting down after 3 jobs
3
main: worker stopped

The crucial detail is the select! between token.cancelled() and the work branch: the worker chooses when to stop (after the current job), so cleanup is graceful, not forced. This is the production pattern for shutting down servers on SIGTERM/Ctrl+C — you would replace the timer in main with tokio::signal::ctrl_c().await. See select-join.md and the Tokio graceful-shutdown guide linked above.

Concurrency vs Parallelism

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Concurrency is structure; parallelism is execution

Tasks are not threads

The runtime flavor decides parallelism

Concurrency on one thread is still a win for I/O

Structured concurrency: don’t leak tasks

Cancellation: a first-class concept

Cooperative cancellation with `CancellationToken`

Key Differences

Why Rust makes you choose

The “cancellation gap” closed

Common Pitfalls

Pitfall 1: Non-`Send` data held across `.await` in a spawned task

Pitfall 2: Blocking the runtime with synchronous waits

Pitfall 3: Confusing “concurrent” with “parallel”

Pitfall 4: Assuming a Promise-style “cancel” cancels nothing

Best Practices

Real-World Example

Further Reading

Official Documentation

Exercises

Exercise 1: Concurrent, not sequential

Exercise 2: Fail fast and cancel the rest

Exercise 3: Graceful shutdown with a cancellation token

Concurrency vs Parallelism

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Concurrency is structure; parallelism is execution

Tasks are not threads

The runtime flavor decides parallelism

Concurrency on one thread is still a win for I/O

Structured concurrency: don’t leak tasks

Cancellation: a first-class concept

Cooperative cancellation with CancellationToken

Key Differences

Why Rust makes you choose

The “cancellation gap” closed

Common Pitfalls

Pitfall 1: Non-Send data held across .await in a spawned task

Pitfall 2: Blocking the runtime with synchronous waits

Pitfall 3: Confusing “concurrent” with “parallel”

Pitfall 4: Assuming a Promise-style “cancel” cancels nothing

Best Practices

Real-World Example

Further Reading

Official Documentation

Related Sections in This Guide

Exercises

Exercise 1: Concurrent, not sequential

Exercise 2: Fail fast and cancel the rest

Exercise 3: Graceful shutdown with a cancellation token

Cooperative cancellation with `CancellationToken`

Pitfall 1: Non-`Send` data held across `.await` in a spawned task