docs: concurrency patterns from rust-lang/rust

10 patterns, 723 lines. Full spec compliance. Patterns: Send/Sync, Arc<Mutex<T>>, RwLock, atomics, channels, OnceLock/LazyLock, scoped threads, Cell/RefCell, thread_local!, poisoning.
2026-04-30 15:04:32 -07:00
parent 82b1366a94
commit f397dba013
1 changed files with 723 additions and 0 deletions
@@ -0,0 +1,723 @@
+# Rust Concurrency Patterns
+
+Patterns for concurrent programming in Rust, extracted from the
+standard library source.
+
+**Source:** [rust-lang/rust](https://github.com/rust-lang/rust) at commit
+[`f53b654`](https://github.com/rust-lang/rust/tree/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6)
+
+**Stats:** 783 Atomic type references, 721 Ordering usages,
+274 Send/Sync markers, 135 Mutex/RwLock, 125 channel references,
+254 OnceLock/LazyLock usages.
+
+---
+
+## 1. Send + Sync (Compiler-Enforced Thread Safety)
+
+### Source:
+
+[library/core/src/marker.rs#L92](https://github.com/rust-lang/rust/blob/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6/library/core/src/marker.rs#L92) (Send), [library/core/src/marker.rs#L657](https://github.com/rust-lang/rust/blob/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6/library/core/src/marker.rs#L657) (Sync)
+
+```rust
+pub unsafe auto trait Send { }
+pub unsafe auto trait Sync { }
+```
+
+### Why
+
+Send and Sync are auto traits — the compiler implements them
+automatically when safe. Send means "can be moved to another thread."
+Sync means "can be shared between threads via &T." These are the
+foundation of Rust's fearless concurrency: data races are compile-time
+errors, not runtime bugs.
+
+- `Rc<T>` is !Send (not thread-safe reference counting)
+- `Arc<T>` is Send + Sync (atomic reference counting)
+- `Cell<T>` is !Sync (interior mutability without synchronization)
+- `Mutex<T>` is Sync (provides synchronized access)
+
+### When to Use
+
+**Triggers:**
+- When your type contains raw pointers that ARE safe to send
+  (implement `unsafe impl Send`)
+- When you need to prove thread safety at compile time (bound with
+  `T: Send + Sync`)
+- When designing concurrent APIs (require Send on closures for spawn)
+
+**Example — before:**
+```rust
+// Compiles but has a data race (other languages):
+let data = Rc::new(RefCell::new(vec![1, 2, 3]));
+let data_clone = data.clone();
+thread::spawn(move || {
+    data_clone.borrow_mut().push(4);  // RACE CONDITION
+});
+data.borrow_mut().push(5);
+```
+
+**Example — in Rust:**
+```rust
+// COMPILE ERROR: `Rc<RefCell<Vec<i32>>>` cannot be sent between threads safely
+let data = Rc::new(RefCell::new(vec![1, 2, 3]));
+thread::spawn(move || {
+    data.borrow_mut().push(4);  // ERROR: Rc is !Send
+});
+
+// FIX: Use Arc + Mutex for thread-safe shared mutation
+let data = Arc::new(Mutex::new(vec![1, 2, 3]));
+let data_clone = Arc::clone(&data);
+thread::spawn(move || {
+    data_clone.lock().unwrap().push(4);  // safe: Mutex provides synchronization
+});
+```
+
+### When NOT to Use
+
+**Don't use this when:**
+- Your type is inherently single-threaded (let the auto trait do
+  its job — it will be !Send automatically if it contains !Send fields)
+- You're unsure whether your type is safe to send (DON'T blindly
+  add `unsafe impl Send` — prove it first)
+
+---
+
+## 2. Arc<Mutex<T>> (Shared Mutable State)
+
+### Source:
+
+[library/std/src/sync/mutex.rs](https://github.com/rust-lang/rust/blob/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6/library/std/src/sync/mutex.rs), [library/alloc/src/sync.rs](https://github.com/rust-lang/rust/blob/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6/library/alloc/src/sync.rs)
+
+```rust
+use std::sync::{Arc, Mutex};
+
+let counter = Arc::new(Mutex::new(0));
+let counter_clone = Arc::clone(&counter);
+
+thread::spawn(move || {
+    let mut num = counter_clone.lock().unwrap();
+    *num += 1;
+});
+```
+
+### Why
+
+Arc provides shared ownership across threads. Mutex provides
+exclusive access (one thread at a time). Together: multiple threads
+can share mutable state safely. The lock guard (MutexGuard) drops
+automatically, releasing the lock — you can't forget to unlock.
+
+### When to Use
+
+**Triggers:**
+- Multiple threads need to read AND write the same data
+- Writes are short-lived (don't hold the lock long)
+- You need strong consistency (every read sees the latest write)
+
+**Example — before:**
+```rust
+// Single-threaded: RefCell is fine
+let state = RefCell::new(HashMap::new());
+state.borrow_mut().insert("key", "value");
+```
+
+**Example — after (multi-threaded):**
+```rust
+use std::sync::{Arc, Mutex};
+
+let state = Arc::new(Mutex::new(HashMap::new()));
+
+// Thread 1:
+let state1 = Arc::clone(&state);
+thread::spawn(move || {
+    state1.lock().unwrap().insert("key", "value");
+});
+
+// Thread 2:
+let state2 = Arc::clone(&state);
+thread::spawn(move || {
+    let map = state2.lock().unwrap();
+    println!("{:?}", map.get("key"));
+});
+```
+
+### When NOT to Use
+
+**Don't use this when:**
+- Only one thread needs access (just own it directly)
+- Reads vastly outnumber writes (use `RwLock` instead)
+- Lock contention is high (consider lock-free data structures
+  or message passing)
+- The protected data is a simple counter (use `AtomicUsize`)
+
+### Anti-pattern
+
+```rust
+// DON'T: Hold the lock across await points
+let data = Arc::new(Mutex::new(vec![]));
+async fn bad(data: Arc<Mutex<Vec<i32>>>) {
+    let mut guard = data.lock().unwrap();
+    some_async_operation().await;  // DEADLOCK RISK: lock held across await
+    guard.push(1);
+}
+
+// DO: Lock, extract, drop, then await
+async fn good(data: Arc<Mutex<Vec<i32>>>) {
+    let value = {
+        let guard = data.lock().unwrap();
+        guard.last().copied()
+    };  // lock dropped here
+    some_async_operation().await;  // safe: no lock held
+}
+```
+
+---
+
+## 3. RwLock for Read-Heavy Workloads
+
+### Source:
+
+[library/std/src/sync/rwlock.rs](https://github.com/rust-lang/rust/blob/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6/library/std/src/sync/rwlock.rs)
+
+```rust
+use std::sync::RwLock;
+
+let lock = RwLock::new(5);
+
+// Multiple readers simultaneously:
+let r1 = lock.read().unwrap();
+let r2 = lock.read().unwrap();
+assert_eq!(*r1, 5);
+assert_eq!(*r2, 5);
+drop((r1, r2));
+
+// Exclusive writer:
+let mut w = lock.write().unwrap();
+*w += 1;
+```
+
+### Why
+
+RwLock allows multiple simultaneous readers OR one exclusive writer.
+For read-heavy workloads, this dramatically reduces contention
+compared to Mutex (which blocks all access during any operation).
+
+### When to Use
+
+**Triggers:**
+- Reads vastly outnumber writes (>10:1 ratio)
+- Read operations are not trivially fast (worth avoiding the lock)
+- Multiple threads frequently read simultaneously
+
+### When NOT to Use
+
+**Don't use this when:**
+- Writes are frequent (RwLock has higher overhead than Mutex)
+- You're on a single-threaded runtime
+- The protected operation is so fast that contention doesn't matter
+
+---
+
+## 4. Atomic Types for Lock-Free Operations
+
+### Source:
+
+[library/core/src/sync/atomic.rs](https://github.com/rust-lang/rust/blob/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6/library/core/src/sync/atomic.rs)
+
+783 Atomic type references, 721 Ordering usages.
+
+```rust
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+static COUNTER: AtomicUsize = AtomicUsize::new(0);
+
+fn increment() {
+    COUNTER.fetch_add(1, Ordering::Relaxed);
+}
+```
+
+### Why
+
+Atomics provide thread-safe operations WITHOUT locks. They're faster
+than Mutex for simple values (counters, flags, pointers) because
+they use CPU hardware instructions directly.
+
+### When to Use
+
+**Triggers:**
+- Simple values: counters, flags, booleans
+- High contention where lock overhead matters
+- Statistics/metrics that don't need precise ordering
+- Implementing lock-free data structures
+
+**Example — before:**
+```rust
+// Mutex for a simple counter — overkill
+let counter = Arc::new(Mutex::new(0usize));
+let c = Arc::clone(&counter);
+thread::spawn(move || {
+    *c.lock().unwrap() += 1;  // lock overhead for one add
+});
+```
+
+**Example — after:**
+```rust
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::sync::Arc;
+
+let counter = Arc::new(AtomicUsize::new(0));
+let c = Arc::clone(&counter);
+thread::spawn(move || {
+    c.fetch_add(1, Ordering::Relaxed);  // no lock, hardware instruction
+});
+```
+
+### When NOT to Use
+
+**Don't use this when:**
+- You need to update multiple values atomically (use Mutex)
+- The operation is complex (compare-and-swap loops get tricky)
+- You don't understand memory ordering (use Mutex instead — 
+  wrong Ordering is UB in theory, bugs in practice)
+
+### Ordering Guide
+
+```rust
+// Simple counter — order doesn't matter:
+counter.fetch_add(1, Ordering::Relaxed);
+
+// Flag that another thread checks:
+flag.store(true, Ordering::Release);      // writer
+if flag.load(Ordering::Acquire) { ... }   // reader
+
+// When in doubt (and you can afford it):
+value.load(Ordering::SeqCst);  // strongest, safest, slowest
+```
+
+---
+
+## 5. Channels (mpsc) for Message Passing
+
+### Source:
+
+[library/std/src/sync/mpsc.rs](https://github.com/rust-lang/rust/blob/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6/library/std/src/sync/mpsc.rs)
+
+125 channel references in library/.
+
+```rust
+use std::sync::mpsc;
+
+let (tx, rx) = mpsc::channel();
+
+thread::spawn(move || {
+    tx.send("hello").unwrap();
+});
+
+let msg = rx.recv().unwrap();
+```
+
+### Why
+
+Channels move data between threads without shared state. "Do not
+communicate by sharing memory; share memory by communicating."
+The sender and receiver are separate types — the type system
+ensures correct usage.
+
+### When to Use
+
+**Triggers:**
+- Producer-consumer patterns
+- Work distribution (fan-out)
+- Event notification between threads
+- You want to avoid shared mutable state entirely
+
+**Example — before:**
+```rust
+// Shared state approach — complex and error-prone
+let results = Arc::new(Mutex::new(Vec::new()));
+for i in 0..10 {
+    let results = Arc::clone(&results);
+    thread::spawn(move || {
+        let answer = compute(i);
+        results.lock().unwrap().push(answer);
+    });
+}
+// How do we know when all threads are done?
+```
+
+**Example — after:**
+```rust
+let (tx, rx) = mpsc::channel();
+
+for i in 0..10 {
+    let tx = tx.clone();
+    thread::spawn(move || {
+        let answer = compute(i);
+        tx.send(answer).unwrap();
+    });
+}
+drop(tx);  // close the sender so rx.iter() terminates
+
+let results: Vec<_> = rx.iter().collect();
+// Clean, simple, no shared state
+```
+
+### When NOT to Use
+
+**Don't use this when:**
+- You need multiple consumers (mpsc = multi-producer, SINGLE consumer)
+- You need bidirectional communication (use two channels or shared state)
+- The "message" is just a counter increment (use atomics)
+
+---
+
+## 6. OnceLock / LazyLock for One-Time Initialization
+
+### Source:
+
+[library/std/src/sync/once_lock.rs](https://github.com/rust-lang/rust/blob/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6/library/std/src/sync/once_lock.rs)
+
+254 OnceLock/LazyLock references.
+
+```rust
+use std::sync::OnceLock;
+
+static CONFIG: OnceLock<Config> = OnceLock::new();
+
+fn get_config() -> &'static Config {
+    CONFIG.get_or_init(|| {
+        load_config_from_disk()  // runs exactly once, thread-safe
+    })
+}
+```
+
+### Why
+
+OnceLock guarantees initialization happens exactly once, even with
+concurrent access. Multiple threads calling `get_or_init` simultaneously
+will block until the first one finishes, then all get the same value.
+
+### When to Use
+
+**Triggers:**
+- Global/static configuration loaded once at startup
+- Expensive computation cached forever
+- Regex compilation (compile once, use many times)
+- Database connection pools initialized on first use
+
+**Example — before:**
+```rust
+// Mutex just for initialization — unnecessary lock on every access
+static CONFIG: Mutex<Option<Config>> = Mutex::new(None);
+
+fn get_config() -> Config {
+    let mut config = CONFIG.lock().unwrap();
+    if config.is_none() {
+        *config = Some(load_config());
+    }
+    config.as_ref().unwrap().clone()  // clone on EVERY access!
+}
+```
+
+**Example — after:**
+```rust
+use std::sync::LazyLock;
+
+static CONFIG: LazyLock<Config> = LazyLock::new(|| load_config());
+
+fn get_config() -> &'static Config {
+    &CONFIG  // no lock after initialization, just a pointer read
+}
+```
+
+### When NOT to Use
+
+**Don't use this when:**
+- The value needs to change after initialization (use Mutex/RwLock)
+- Initialization failure should be retried (OnceLock panics in init
+  leave it permanently empty)
+- You need non-static lifetime (use regular lazy initialization)
+
+---
+
+## 7. Scoped Threads (thread::scope)
+
+### Source:
+
+[library/std/src/thread/scoped.rs](https://github.com/rust-lang/rust/blob/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6/library/std/src/thread/scoped.rs)
+
+```rust
+let mut data = vec![1, 2, 3];
+
+thread::scope(|s| {
+    s.spawn(|| {
+        println!("{data:?}");  // can borrow from parent scope!
+    });
+    s.spawn(|| {
+        println!("{}", data.len());
+    });
+});
+// All threads joined here — data is safe to use again
+```
+
+### Why
+
+Regular `thread::spawn` requires 'static data (because the thread
+might outlive the caller). `thread::scope` guarantees all spawned
+threads finish before the scope ends, so they can BORROW local data.
+No Arc needed.
+
+### When to Use
+
+**Triggers:**
+- Parallel processing of local data
+- Fork-join parallelism
+- You want multiple threads to borrow the same data without Arc
+
+**Example — before:**
+```rust
+// thread::spawn requires ownership or 'static — must Arc everything
+let data = Arc::new(vec![1, 2, 3, 4, 5]);
+let handles: Vec<_> = data.chunks(2).map(|chunk| {
+    // Can't do this — chunks borrows data which isn't 'static
+    thread::spawn(move || chunk.iter().sum::<i32>())
+}).collect();
+```
+
+**Example — after:**
+```rust
+let data = vec![1, 2, 3, 4, 5];
+
+let sums: Vec<i32> = thread::scope(|s| {
+    let handles: Vec<_> = data.chunks(2)
+        .map(|chunk| s.spawn(|| chunk.iter().sum::<i32>()))
+        .collect();
+    handles.into_iter().map(|h| h.join().unwrap()).collect()
+});
+// No Arc, no clone, just direct borrows
+```
+
+### When NOT to Use
+
+**Don't use this when:**
+- Threads need to outlive the current function (use regular spawn)
+- You're in an async context (use async tasks instead)
+- The work is too small to benefit from parallelism
+
+---
+
+## 8. Interior Mutability (Cell/RefCell)
+
+### Source:
+
+[library/core/src/cell.rs](https://github.com/rust-lang/rust/blob/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6/library/core/src/cell.rs)
+
+410 Cell/RefCell usages in library/.
+
+```rust
+use std::cell::Cell;
+
+struct Counter {
+    count: Cell<u32>,
+}
+
+impl Counter {
+    fn increment(&self) {  // note: &self, not &mut self
+        self.count.set(self.count.get() + 1);
+    }
+}
+```
+
+### Why
+
+Sometimes you need mutation through a shared reference (&T).
+Cell provides this for Copy types (get/set), RefCell for any type
+(runtime borrow checking). This is !Sync — single-thread only.
+
+### When to Use
+
+**Triggers:**
+- You need mutation through &self (caching, counters, lazy init)
+- Multiple parts of code hold &T but one needs to mutate
+- Single-threaded context only
+- **Cell:** Value is Copy (integers, booleans)
+- **RefCell:** Value isn't Copy or you need a reference into it
+
+**Example — before:**
+```rust
+// Can't cache in &self — need &mut self for mutation
+impl Graph {
+    fn expensive_traversal(&mut self) -> &[Node] {
+        if self.cache.is_none() {
+            self.cache = Some(self.compute_traversal());
+        }
+        self.cache.as_ref().unwrap()
+    }
+}
+// Every caller needs &mut Graph just to read cached data
+```
+
+**Example — after:**
+```rust
+use std::cell::RefCell;
+
+impl Graph {
+    fn expensive_traversal(&self) -> Ref<'_, [Node]> {
+        if self.cache.borrow().is_none() {
+            *self.cache.borrow_mut() = Some(self.compute_traversal());
+        }
+        Ref::map(self.cache.borrow(), |c| c.as_ref().unwrap().as_slice())
+    }
+}
+// Callers only need &Graph — mutation is interior
+```
+
+### When NOT to Use
+
+**Don't use this when:**
+- You can restructure to use &mut self (preferred)
+- Multi-threaded (use Mutex/RwLock instead — Cell/RefCell are !Sync)
+- RefCell borrow violations would be common (panic at runtime)
+
+---
+
+## 9. thread_local! for Per-Thread State
+
+### Source:
+
+[library/std/src/thread/local.rs](https://github.com/rust-lang/rust/blob/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6/library/std/src/thread/local.rs)
+
+```rust
+thread_local! {
+    static BUFFER: RefCell<Vec<u8>> = RefCell::new(Vec::new());
+}
+
+fn process(data: &[u8]) {
+    BUFFER.with(|buf| {
+        let mut buf = buf.borrow_mut();
+        buf.clear();
+        buf.extend_from_slice(data);
+        // reuses allocation across calls within same thread
+    });
+}
+```
+
+### Why
+
+Thread-local storage gives each thread its own copy. No
+synchronization needed because there's no sharing. Useful for
+per-thread caches, buffers, and RNG state.
+
+### When to Use
+
+**Triggers:**
+- Per-thread caches or buffers (avoid allocation per call)
+- Thread-specific state (random number generators)
+- Avoiding synchronization overhead for thread-independent data
+
+### When NOT to Use
+
+**Don't use this when:**
+- State needs to be shared between threads (use Arc<Mutex<T>>)
+- You're in an async context (tasks migrate between threads —
+  thread-local doesn't follow the task)
+- The state is small and cheap to create per-call
+
+---
+
+## 10. Poisoning (Mutex Recovery After Panic)
+
+### Source:
+
+[library/std/src/sync/mutex.rs](https://github.com/rust-lang/rust/blob/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6/library/std/src/sync/mutex.rs)
+
+```rust
+let mutex = Arc::new(Mutex::new(0));
+
+// Thread panics while holding the lock:
+let m = Arc::clone(&mutex);
+let _ = thread::spawn(move || {
+    let _guard = m.lock().unwrap();
+    panic!("oops");
+}).join();
+
+// The mutex is now "poisoned" — lock() returns Err:
+match mutex.lock() {
+    Ok(guard) => println!("value: {}", *guard),
+    Err(poisoned) => {
+        // Can still access the data if you choose:
+        let guard = poisoned.into_inner();
+        println!("recovered: {}", *guard);
+    }
+}
+```
+
+### Why
+
+If a thread panics while holding a Mutex, the protected data may be
+in an inconsistent state. Rust "poisons" the mutex: future lock()
+calls return Err, alerting other threads that something went wrong.
+You can choose to recover or propagate the panic.
+
+### When to Use
+
+**Triggers:**
+- You need to handle the case where a sibling thread panicked
+- You want to "unwrap" the poisoned lock when you know the data
+  is still valid
+- Robust services that shouldn't crash because one request panicked
+
+### When NOT to Use
+
+**Don't use this when:**
+- A panic in one thread should crash everything (just `.unwrap()`)
+- You're using `catch_unwind` to prevent panics from poisoning
+- The data is always valid regardless of panic point
+
+---
+
+## Summary: Concurrency Decision Tree
+
+```
+Do you need shared state across threads?
+├── NO → Use owned data + message passing (channels)
+└── YES → What kind of access?
+    ├── Read-only → Arc<T> (no Mutex needed)
+    ├── Simple counter/flag → Arc<AtomicUsize> / AtomicBool
+    ├── Read-heavy, rare writes → Arc<RwLock<T>>
+    └── Frequent reads and writes → Arc<Mutex<T>>
+
+Do threads need to borrow local data?
+├── YES → thread::scope (no Arc needed)
+└── NO → thread::spawn (requires Send + 'static)
+
+Need one-time initialization?
+├── Static, known at compile time → const
+├── Static, computed at runtime → LazyLock / OnceLock
+└── Per-instance → Option + init-on-first-use
+
+Single-threaded interior mutability?
+├── Copy type → Cell<T>
+├── Non-Copy → RefCell<T>
+└── Multi-threaded → Mutex<T> or RwLock<T>
+```
+
+| Pattern | Use when |
+|---|---|
+| `Send + Sync` | Compiler proves thread safety |
+| `Arc<Mutex<T>>` | Shared mutable state across threads |
+| `Arc<RwLock<T>>` | Read-heavy shared state |
+| `AtomicUsize` etc. | Lock-free counters/flags |
+| `mpsc::channel` | Message passing between threads |
+| `OnceLock`/`LazyLock` | One-time initialization |
+| `thread::scope` | Parallel work on local data |
+| `Cell`/`RefCell` | Interior mutability (single-thread) |
+| `thread_local!` | Per-thread state |
+| Poisoning | Recovery after panic |
+
+See also:
+- [ownership.md](ownership.md) — Arc vs Rc, Box
+- [unsafe-patterns.md](unsafe-patterns.md) — unsafe impl Send/Sync
+- [error-handling.md](error-handling.md) — Handling poisoned locks
+
+<!-- PATTERN_COMPLETE -->