# 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/poison/mutex.rs](https://github.com/rust-lang/rust/blob/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6/library/std/src/sync/poison/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/poison/rwlock.rs](https://github.com/rust-lang/rust/blob/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6/library/std/src/sync/poison/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/poison/mutex.rs](https://github.com/rust-lang/rust/blob/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6/library/std/src/sync/poison/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 -->