In Rust, how does a `thread_local!` static behave: when is each thread's copy created and dropped, and why is it read through `with`?
answer
- one copy per thread
- built on first access
- a reference that cannot escape
- Cell or RefCell for mutation
basics
~20 sA thread_local! static gives each thread its own copy, built on that thread's first access and dropped, best effort, at thread exit. LocalKey::with lends a &T inside a closure so it cannot outlive the thread; mutation needs Cell or RefCell.
solid answer
~50 s`thread_local! { static SCRATCH: RefCell<Vec<u8>> = ... }` declares a `LocalKey<T>`, not a plain static. Each thread that touches it gets its own value, built from the initializer on first access; a thread that never touches it never builds one. `LocalKey::with(|v| ...)` passes a `&T` into a closure instead of returning it, because the value dies with its thread, and a `&'static T` would let it escape. Only shared references are handed out, so a mutable per-thread value is wrapped in `Cell` or `RefCell`; since Rust 1.73 `LocalKey<Cell<T>>` has `get`, `set`, `take` and `replace` and `LocalKey<RefCell<T>>` has `with_borrow` and `with_borrow_mut`. Values that implement `Drop` are dropped when their thread exits, but only best effort: on Unix with pthread-based TLS the main thread's values are not dropped. Writing `const { ... }` for the initializer enables cheaper initialisation.
code
rust · 30 linesuse std::cell::{Cell, RefCell};
use std::thread;
thread_local! {
// Each thread gets its own scratch buffer, built on first use.
static SCRATCH: RefCell<Vec<u8>> = RefCell::new(Vec::with_capacity(4096));
static LINES: Cell<u64> = const { Cell::new(0) };
}
fn compact(line: &str) -> usize {
LINES.set(LINES.get() + 1);
SCRATCH.with_borrow_mut(|buf| {
buf.clear();
buf.extend(line.bytes().filter(|b| !b.is_ascii_whitespace()));
buf.len()
})
}
fn main() {
compact("a b c");
let worker = thread::spawn(|| {
compact("x y");
compact("z");
LINES.get()
});
println!("worker lines = {}", worker.join().unwrap()); // 2
println!("main lines = {}", LINES.get()); // 1
let cap = SCRATCH.with(|b| b.borrow().capacity());
println!("main buffer capacity >= 4096: {}", cap >= 4096);
}go deeper
Recall that thread_local! gives each thread its own value, built on first use, and that you read it with with or, for Cell and RefCell, with get, set and with_borrow_mut.
Explain lazy per-thread initialisation, why with passes &T into a closure, why mutation needs Cell or RefCell, and what const { } initialisers buy.
Show the teardown caveats: best-effort destructors, no main-thread destructors with pthread TLS, try_with in Drop code, and scope not waiting for thread-local destructors.
Judge when per-thread state is worth it: lock-free scratch space and caches versus memory multiplied by thread count and state that silently differs between threads.
## What `thread_local!` declares The `thread_local!` macro declares one or more **thread-local statics**: ```rust thread_local! { static SCRATCH: RefCell<Vec<u8>> = RefCell::new(Vec::with_capacity(4096)); static LINES: Cell<u64> = const { Cell::new(0) }; } ``` Each name has type **`LocalKey<T>`** (here `LocalKey<RefCell<Vec<u8>>>` and `LocalKey<Cell<u64>>`). It is a key, not the value: every thread that uses the key gets its own separate `T`. In a log-compaction worker, `SCRATCH` gives each thread a reusable buffer with no locking and no sharing; a thread that sets `LINES` to 5 does not change what any other thread reads. ## When each thread's copy is created The docs state that initialisation is performed dynamically on the **first call to an accessor** (such as `with`) within a thread: - a thread that never touches the key never runs the initializer; - a newly spawned thread starts from the initializer's value, never a copy of its parent's current value; - the initializer runs on the thread that first touches the key, so it can read that thread's state, such as its name. An initializer written as a **`const { ... }` block** tells the compiler the value is known at compile time, which enables a more efficient implementation. An initializer must not depend on its own key: the docs warn that this may cause panics, aborts or infinite recursion on first access. ## Why access goes through `with` `LocalKey::with<F, R>(&'static self, f: F) -> R where F: FnOnce(&T) -> R` passes a reference **into a closure** instead of returning one. The value lives only as long as its thread, so a `&'static T` would be a lie. Inside the closure the reference's lifetime is tied to the call, and trying to return it out (`let r = KEY.with(|s| s);`) fails to compile with "lifetime may not live long enough". Only **shared** references are handed out. There is no race with other threads, but the same thread could reach the value from two places on its call stack, for example a function that calls `with` and, inside the closure, calls another function that also calls `with`. So mutation goes through interior mutability: | Value type | Convenience methods on the key | Since | |---|---|---| | `Cell<T>` | `get`, `set`, `take`, `replace` | Rust 1.73 | | `RefCell<T>` | `with_borrow`, `with_borrow_mut`, `set`, `take`, `replace` | Rust 1.73 | | any `T` | `with`, `try_with` | Rust 1.0 and 1.26 | Without the Rust 1.73 helpers you write `KEY.with(|c| c.borrow_mut().push(..))`. How `Cell` and `RefCell` check borrows is covered in their own lesson; here, a nested `with_borrow_mut` on the same key in the same thread is a `RefCell` double borrow and panics. ## When each copy is dropped, and the caveats Values that implement `Drop` are dropped **when their thread exits**, after the thread's main function returns. `JoinHandle::join` waits for these destructors too, while `thread::scope` only waits for the threads' main functions, so thread-local destructors of scoped threads may still be running after `scope` returns. A panic inside a thread-local destructor aborts the process. The docs call destruction **best effort** and list known gaps: 1. On Unix with pthread-based TLS, destructors are not run for the **main thread's** values when it exits; the process exits right after anyway. 2. A destructor may re-initialise other thread-local slots during teardown; some platforms guard against this and some cap it. 3. On Windows, at process exit, destructors may only run on the thread that causes the exit. So a thread-local is the wrong place for a buffer that must be flushed to disk; flush explicitly. During teardown, `with` panics if the key's destructor is running and may panic if it already ran, while **`try_with`** returns `Err(AccessError)` instead, which is what code called from destructors should use. ## When to use one - Per-thread scratch buffers, caches and counters that would otherwise need a lock. - Per-thread context such as a random-number generator state. - Not for data that must outlive the thread or be seen by other threads: share that through `Arc`, channels or atomics instead. One cost to keep in mind: memory is multiplied by the number of threads that touch the key. A 4 KiB scratch buffer is trivial across four workers and noticeable across thousands of threads, and each copy keeps whatever capacity it grew to until its thread exits. Clearing a buffer with `clear()` keeps that capacity, which is usually the point of a scratch buffer.
- Can you return the reference from `LocalKey::with` so a caller can keep it?No. `with` takes `FnOnce(&T) -> R`, and the reference's lifetime is limited to the call, so `let r = KEY.with(|s| s);` fails with "lifetime may not live long enough". Return an owned value computed from it instead, such as a clone or a length.
- Code in a `Drop` impl reads a thread-local during thread exit and sometimes panics; what should it use?`LocalKey::try_with`. During teardown `with` panics if the key's destructor is running and may panic if it already ran, while `try_with` returns `Err(AccessError)` so the destructor can skip the work. Note that `try_with` still panics if the initializer itself panics.
- A spawned thread inherits a copy of its parent's thread-local value.
- thread_local! values are built eagerly for every thread at startup.
- LocalKey::with hands out &mut T, so no Cell or RefCell is needed.
- Thread-local destructors are guaranteed to run, so they can flush files safely.
- A thread-local needs Sync because several threads use the same key.
Assumes Rust 1.99 on edition 2024; the LocalKey<Cell<T>> and LocalKey<RefCell<T>> helpers such as get, set and with_borrow_mut are stable since Rust 1.73.