In Rust, when should you start worker threads with `std::thread::Builder` rather than `thread::spawn`, and how does `available_parallelism` help decide how many?
answer
- names show up in panic lines
- stack size in bytes
- spawn failure as io::Error
- an estimate, not a core count
basics
~20 sUse thread::Builder to name a thread, set its stack size, or handle a failed spawn as an io::Error instead of a panic. thread::available_parallelism() returns io::Result<NonZero<usize>>, an estimate of usable parallelism that can fail and should be given a fallback.
solid answer
~40 s`thread::spawn(f)` is shorthand for `Builder::new().spawn(f).expect("failed to spawn thread")`. Reach for `Builder` when you need what that hides: `.name(..)` puts the name into panic messages (`thread 'compactor-2' panicked at ...`), `thread::current().name()` and, where supported, the OS thread name; `.stack_size(bytes)` overrides the default (2 MiB on Tier-1 platforms today) for deep recursion; and `.spawn(f)` returns `io::Result<JoinHandle<T>>`, so a service can report a refused spawn instead of crashing. To pick a worker count, `thread::available_parallelism()` returns `io::Result<NonZero<usize>>`, an estimate that on Linux tries to respect affinity masks and cgroup quotas. It can be wrong or fail, it is recomputed on every call, and it should not be called in hot code; a common pattern is `.map(NonZero::get).unwrap_or(1)`.
code
rust · 26 linesuse std::num::NonZero;
use std::thread;
fn main() -> std::io::Result<()> {
// An estimate; fall back to one worker when the platform cannot say.
let workers = thread::available_parallelism()
.map(NonZero::get)
.unwrap_or(1)
.min(4);
let mut handles = Vec::with_capacity(workers);
for id in 0..workers {
let h = thread::Builder::new()
.name(format!("compactor-{id}"))
.stack_size(8 * 1024 * 1024)
.spawn(move || {
let me = thread::current();
format!("{} done", me.name().unwrap())
})?; // io::Result: a failed OS spawn is an Err, not a panic
handles.push(h);
}
for h in handles {
println!("{}", h.join().expect("compactor panicked"));
}
Ok(())
}go deeper
Recall that Builder lets you name a thread and set its stack size, and that available_parallelism gives a suggested worker count that can be an Err.
Explain that thread::spawn is Builder::new().spawn(f).expect(..), that Builder::spawn returns io::Result, the 2 MiB default and RUST_MIN_STACK, and the NonZero<usize> return.
Show how a service handles a refused spawn without crashing, names workers so panic lines are actionable, and treats available_parallelism as an estimate in containers.
Decide how worker counts are configured across deployments: estimated from the environment, capped per job, or set explicitly, and how that interacts with other processes sharing the host.
## What `thread::spawn` hides `std::thread::spawn` is a convenience wrapper. Its body is literally `Builder::new().spawn(f).expect("failed to spawn thread")`, so it starts a thread with default settings and panics if the OS refuses. **`std::thread::Builder`** exposes the settings and the error: - **`name(String)`** names the thread. - **`stack_size(usize)`** sets the stack size in bytes. - **`spawn(f)`** returns **`io::Result<JoinHandle<T>>`** instead of panicking. - **`spawn_scoped(&scope, f)`** does the same for a thread inside `thread::scope`, returning `io::Result<ScopedJoinHandle<'scope, T>>`. The closure bounds are the same as for `thread::spawn`: `FnOnce() -> T + Send + 'static` for `spawn`, `'scope` instead of `'static` for `spawn_scoped`. `Builder` itself is `#[must_use]`, so building one and forgetting to call `spawn` draws a warning. ## Naming threads A name is used for identification. The standard library uses it in two places it documents: 1. The panic message: a panic on a named thread prints `thread 'compactor-2' panicked at ...` instead of `thread '<unnamed>'`. 2. The OS, where the platform supports it (for example `pthread_setname_np` on Unix-like systems), which makes the name visible in debuggers and profilers. Inside the thread, `thread::current().name()` returns `Some("compactor-2")`; an unnamed spawned thread returns `None`, and the main thread reports `Some("main")`. The name must not contain a NUL byte; `Builder::spawn` panics if it does, with "thread name may not contain interior null bytes". Naming every long-lived worker costs nothing and turns an anonymous stderr line into an actionable one. ## Stack size The std docs say the default stack size is platform-dependent and subject to change, and currently 2 MiB on all Tier-1 platforms. You can change it in two ways: - `Builder::stack_size(bytes)` for one thread; the platform may round it up to its minimum. - The `RUST_MIN_STACK` environment variable for every spawned thread; `Builder::stack_size` overrides it, and changes after program start may be ignored. The **main thread's** stack is not set by Rust at all; it comes from the OS and the linker. A worker that recurses deeply over a nested log format may need a bigger stack; a server with thousands of mostly idle threads may want a smaller one. ## Spawn failures as values Creating a thread can fail: for example the process hit a thread limit, or memory for the new stack could not be reserved. `thread::spawn` turns that into a panic. `Builder::spawn` hands you an `io::Error`, so a service can log it, retry later or degrade to fewer workers, which is why long-running services often use `Builder` even when they need no name. ## Choosing a worker count with `available_parallelism` `std::thread::available_parallelism()` returns **`io::Result<NonZero<usize>>`**: an estimate of the default amount of parallelism the program should use. Its docs are explicit about the limits: | Point | What the docs say | |---|---| | what it counts | often the CPU count, but VMs and container orchestrators may restrict it | | Linux | tries affinity masks and cgroup quotas; may overcount when those cannot be queried; ignores `ulimit` | | Windows | may undercount on machines with more than 64 logical CPUs | | any target | may overcount in a VM with CPU limits; does not account for current system load | | caching | not cached; recomputed on each call, so keep it out of hot code | | errors | e.g. unknown on the platform, or no permission to query | Because the result is `NonZero`, it is never zero, but it can be an `Err`. Read it once at startup, unwrap with a fallback, and cap it for the job: a four-way split of a log file does not get faster with 64 threads. ## Putting it together - Use `thread::spawn` for quick, short-lived threads in tools where a spawn failure can reasonably crash the program. - Use `Builder` for named, long-lived or deep-stack workers, and anywhere a spawn failure must be handled. - Size worker counts from `available_parallelism` with a fallback and a cap; reusable pools that size themselves are a separate subject (Rayon). ## A review checklist for worker startup 1. Is every long-lived worker named, so a panic line or a profiler view says which one it is? 2. Does a failed spawn reach a log or a retry, rather than a panic deep in startup code? 3. Is the worker count read once, defaulted when the call fails, and capped for the job? 4. Does any worker recurse deeply enough to need more than the default stack?
- Why might a containerised service still start too many workers when it sizes them with `available_parallelism`?On Linux the function tries to honour the process affinity mask and cgroup CPU quotas, but its docs say it may overcount when `sched_getaffinity()` or the cgroup filesystem cannot be queried, for example under sandboxing, and in VMs with CPU limits. Allow an explicit configuration override and cap the count for the workload.
- How do you raise the stack size of every spawned thread without touching each spawn call?Set the `RUST_MIN_STACK` environment variable to a byte count before the program starts; std uses it as the default for spawned threads, and changes after start may be ignored. An explicit `Builder::stack_size` still wins. The main thread is unaffected, because its stack is not determined by Rust.
- available_parallelism returns the number of physical cores on the machine.
- thread::spawn returns an Err when the OS refuses to create a thread.
- A thread name is only cosmetic and never appears in panic messages.
- The main thread's stack size can be set with Builder::stack_size.
- available_parallelism is cached, so calling it in a hot loop is free.