The borrow checker’s one-owner rule is a feature until you’re modeling a graph, a cache, or any structure where “who owns this?” honestly has more than one answer. Rc<T> is the escape hatch: a reference-counted pointer that lets multiple owners share the same heap allocation, single-threaded, no locking, no overhead beyond a counter increment.

The pain: a value with no single owner

Imagine a config blob a couple of subsystems need to read. You don’t want to copy it — it’s big — and you can’t give either subsystem a &Config without inventing a parent that outlives them both:

1
2
3
4
5
6
7
8

struct Config { name: String }

fn build() -> (Logger, Metrics) {
    let cfg = Config { name: "app".into() };
    let logger = Logger { cfg: &cfg };  // error: `cfg` does not live long enough
    let metrics = Metrics { cfg: &cfg };
    (logger, metrics)
}

You could clone() the Config and hand each subsystem its own copy. You could thread the lifetime through every type that touches it. Or you could acknowledge that this value genuinely has multiple owners and say so.

Rc<T>: many owners, one allocation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

use std::rc::Rc;

struct Config { name: String }
struct Logger { cfg: Rc<Config> }
struct Metrics { cfg: Rc<Config> }

let cfg = Rc::new(Config { name: "app".into() });
let logger = Logger { cfg: Rc::clone(&cfg) };
let metrics = Metrics { cfg: Rc::clone(&cfg) };

assert_eq!(logger.cfg.name, "app");
assert_eq!(metrics.cfg.name, "app");

Rc::new puts the Config on the heap alongside a strong-count of 1. Rc::clone doesn’t clone the Config — it bumps the counter and hands back another pointer to the same allocation. When a clone is dropped the count decrements; when the last clone is dropped, the Config is destroyed and the heap memory is freed.

The convention is Rc::clone(&x) rather than x.clone(). Both compile, both do the same thing, but the explicit form makes “this is a cheap counter bump, not a deep copy” obvious at the call site — especially helpful when T itself is Clone.

Inspecting the count

Rc::strong_count is a debugging window into the same counter:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

use std::rc::Rc;

let a = Rc::new(String::from("shared"));
assert_eq!(Rc::strong_count(&a), 1);

let b = Rc::clone(&a);
let c = Rc::clone(&a);
assert_eq!(Rc::strong_count(&a), 3);

drop(b);
assert_eq!(Rc::strong_count(&a), 2);

You almost never need to read it in production code — its main use is asserting “yes, this is actually shared” in tests, or understanding a memory leak.

You only get &T through an Rc<T>

The price for shared ownership is read-only access. Rc<T> is Deref<Target = T>, but not DerefMut. Try to mutate and the compiler stops you:

1
2
3
4
5
6

use std::rc::Rc;

let cfg = Rc::new(String::from("app"));
let other = Rc::clone(&cfg);
cfg.push_str("-prod");
// error: cannot borrow data in an `Rc` as mutable

This is the correct default. If two owners could both call &mut simultaneously, you’d have a data race in single-threaded code — exactly the bug Rust exists to prevent. So you need a runtime borrow check, which is what RefCell<T> provides.

The classic pattern: Rc<RefCell<T>>

When the shared value also needs to mutate, wrap it in a RefCell. The outer Rc gives you shared ownership; the inner RefCell gives you borrow_mut through &self:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

use std::rc::Rc;
use std::cell::RefCell;

let log: Rc<RefCell<Vec<String>>> = Rc::new(RefCell::new(Vec::new()));

let writer_a = Rc::clone(&log);
let writer_b = Rc::clone(&log);

writer_a.borrow_mut().push("a says hi".into());
writer_b.borrow_mut().push("b says hi".into());

let snapshot = log.borrow();
assert_eq!(snapshot.len(), 2);
assert_eq!(snapshot[0], "a says hi");

Every Rc::clone owns the cell; every borrow goes through RefCell’s runtime check. Forget the inner RefCell and you’ll be staring at cannot borrow as mutable errors. Forget the outer Rc and you can’t share the cell in the first place. The pair shows up so often that “Rc<RefCell<…>>” should land in your fingers as one token.

Rc::clone vs (*rc).clone()

It’s worth seeing the difference once:

1
2
3
4
5
6
7
8
9

use std::rc::Rc;

let a = Rc::new(vec![1, 2, 3]);

let cheap = Rc::clone(&a);        // counter += 1, no allocation
let expensive: Vec<i32> = (*a).clone();   // brand new Vec, separate heap allocation

assert_eq!(Rc::strong_count(&a), 2);   // a + cheap; `expensive` isn't an Rc at all
assert_eq!(expensive, vec![1, 2, 3]);

Rc<T> doesn’t change what T::clone does — it just adds a much cheaper way to make another pointer to the same T. Use Rc::clone for the pointer; reach for (*rc).clone() only when you really do want a fresh, independent T.

The catch: Rc<T> is not Send

Rc is deliberately not thread-safe. The counter increment isn’t atomic; if two threads bumped it simultaneously you could undercount and free a still-referenced allocation. Try to move one across a thread boundary and the compiler refuses:

1
2
3
4
5
6

use std::rc::Rc;
use std::thread;

let a = Rc::new(42);
thread::spawn(move || println!("{a}"));
// error: `Rc<i32>` cannot be sent between threads safely

That refusal is the whole reason Rc is cheap — no atomic ops, no fences. Cross threads and you want the atomically-counted sibling: Arc<T>, which this afternoon’s bite is about. Same API, same shape, just Send + Sync and a slightly costlier clone.

The other catch: reference cycles

Two Rcs pointing at each other never drop, because each is keeping the other’s count above zero:

1
2
3
4

struct Node {
    next: RefCell<Option<Rc<Node>>>,
}
// build a -> b -> a … and neither will ever be freed

Rc is a counter, not a tracing GC — it can’t notice that an island of nodes is unreachable from the outside as long as the nodes are still pointing at each other. The fix is Weak<T>, the non-owning sibling pointer you get from Rc::downgrade. That’s tomorrow’s bite. For now: if your data is a tree, plain Rc<RefCell<T>> is fine; if it’s a graph or has back-pointers, plan for Weak.

This morning’s Atomic* handled “many threads, one scalar.” For “many threads, one value — computed once, then read forever” the std answer is two types: LazyLock<T, F> when you can name the initializer up front, OnceLock<T> when you only learn the value at runtime. Both make the old lazy_static! macro and the once_cell crate redundant.

The bad old days: lazy_static!

Until Rust 1.80 (mid-2024), a thread-safe lazy global meant a macro from a crate:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// Cargo.toml: lazy_static = "1"
use lazy_static::lazy_static;
use std::collections::HashMap;

lazy_static! {
    static ref COUNTRIES: HashMap<&'static str, &'static str> = {
        let mut m = HashMap::new();
        m.insert("fr", "France");
        m.insert("de", "Germany");
        m
    };
}

fn main() {
    assert_eq!(COUNTRIES.get("fr"), Some(&"France"));
}

It worked, but it pulled in a dependency, used macro magic to fake a static, and gave you a custom Deref wrapper instead of a normal type. Every dependency in your tree that wanted a lazy global was either pulling in lazy_static or the more modern once_cell crate.

The std way: LazyLock<T, F>

Stabilized in Rust 1.80, LazyLock is a normal type — no macro, no Deref trickery, just a static like any other:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

use std::collections::HashMap;
use std::sync::LazyLock;

static COUNTRIES: LazyLock<HashMap<&'static str, &'static str>> = LazyLock::new(|| {
    let mut m = HashMap::new();
    m.insert("fr", "France");
    m.insert("de", "Germany");
    m
});

assert_eq!(COUNTRIES.get("fr"), Some(&"France"));

The closure runs the first time anything touches COUNTRIES, exactly once, and every thread that races to be that “first” gets the same value back. If two threads arrive together, one wins the init and the other blocks until it’s done — same contract lazy_static! always had, now in std.

When the initializer isn’t known at compile time: OnceLock<T>

LazyLock is great when you can write the initializer as a const fn-friendly closure. But what about config you only know after main() starts — a CLI flag, an env var, a parsed file? Stuffing that into a closure means either re-reading the env var at first use or capturing values you don’t have yet at static time. That’s OnceLock<T>’s job:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

use std::sync::OnceLock;

static GREETING: OnceLock<String> = OnceLock::new();

fn init_from_args(name: &str) {
    GREETING.set(format!("hello, {name}")).ok();   // ok() = ignore "already set"
}

fn greeting() -> &'static str {
    GREETING.get().map(String::as_str).unwrap_or("hello, world")
}

init_from_args("ferris");
assert_eq!(greeting(), "hello, ferris");

set returns Err(value) if someone beat you to it — handy when multiple call sites might initialize and you want the first one to win without panicking.

The convenience method: get_or_init

The “check if set, init if not” dance is so common that OnceLock ships it as one call:

1
2
3
4
5
6
7
8
9

use std::sync::OnceLock;

fn config() -> &'static String {
    static CFG: OnceLock<String> = OnceLock::new();
    CFG.get_or_init(|| std::env::var("APP_CFG").unwrap_or_else(|_| "default".into()))
}

assert!(!config().is_empty());
assert_eq!(config(), config());    // same &'static str on every call

This is what most “lazy global computed from runtime data” code actually wants. Functions can own their own OnceLock as a function-local static — no need to pollute the module namespace.

Which one when

LazyLock is the closer match to lazy_static!. OnceLock is the closer match to manual Mutex<Option<T>> patterns where you wanted “set once, read many.”

The trait bounds, briefly

Because these are Sync and live in a static, the contained T must be Send + Sync. The initializer closure for LazyLock must be Send. You won’t notice for String, HashMap, Vec, Arc<…> — but if you try to stuff an Rc<T> in there the compiler will (correctly) yell. The single-threaded versions, LazyCell and OnceCell, have no such bound — that’s the whole reason both pairs exist.

What you can finally delete

If a crate in your tree still has lazy_static = "1" or once_cell = "1" in its Cargo.toml, and your MSRV is 1.80 or newer, the migration is mechanical:

1
2
3
4

// before
lazy_static! { static ref X: T = init(); }
// after
static X: LazyLock<T> = LazyLock::new(init);

1
2
3
4
5
6

// before
use once_cell::sync::OnceCell;
static X: OnceCell<T> = OnceCell::new();
// after
use std::sync::OnceLock;
static X: OnceLock<T> = OnceLock::new();

One fewer dependency, one less macro in the expansion, and the type that shows up in error messages is just LazyLock<T> — not some crate-private deref wrapper. Tomorrow’s bite picks up the thread on Arc<T> — what to reach for when “one global value” isn’t enough and you need shared ownership across threads.

A Cell<T> lets a single thread mutate through &self — get/set instead of &mut. The atomic types in std::sync::atomic are the same shape, just Sync: a counter, flag, or pointer many threads can poke at without a Mutex, no lock acquisition, no guard, no panic on contention.

The pain: Mutex<u64> for a single counter

A request counter shared across worker threads is the textbook reach-for-Arc<Mutex<_>> case — and the textbook overkill:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

use std::sync::{Arc, Mutex};
use std::thread;

let hits = Arc::new(Mutex::new(0u64));
let mut handles = Vec::new();

for _ in 0..8 {
    let h = Arc::clone(&hits);
    handles.push(thread::spawn(move || {
        for _ in 0..1000 {
            let mut g = h.lock().unwrap();   // lock, increment, unlock — 1000 times
            *g += 1;
        }
    }));
}
for h in handles { h.join().unwrap(); }
assert_eq!(*hits.lock().unwrap(), 8_000);

Eight threads contending on a lock for an n += 1 is a lot of ceremony to add one to an integer. The CPU has a single instruction for this. Rust exposes it.

The fix: AtomicU64 (or AtomicUsize, AtomicBool, …)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

use std::sync::Arc;
use std::sync::atomic::{AtomicU64, Ordering};
use std::thread;

let hits = Arc::new(AtomicU64::new(0));
let mut handles = Vec::new();

for _ in 0..8 {
    let h = Arc::clone(&hits);
    handles.push(thread::spawn(move || {
        for _ in 0..1000 {
            h.fetch_add(1, Ordering::Relaxed);   // one instruction, no lock
        }
    }));
}
for h in handles { h.join().unwrap(); }
assert_eq!(hits.load(Ordering::Relaxed), 8_000);

No lock(), no guard, no unwrap. fetch_add is a single read-modify-write — on x86 it’s literally lock xadd. The Arc is still there because the threads need shared ownership, but the interior is lock-free.

The API is just Cell’s API, with orderings

Every atomic has the same small surface:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

use std::sync::atomic::{AtomicUsize, Ordering};

let n = AtomicUsize::new(7);

// like Cell::get / Cell::set
let v = n.load(Ordering::Relaxed);     assert_eq!(v, 7);
n.store(42, Ordering::Relaxed);
assert_eq!(n.load(Ordering::Relaxed), 42);

// like Cell::replace
let old = n.swap(100, Ordering::Relaxed);
assert_eq!(old, 42);
assert_eq!(n.load(Ordering::Relaxed), 100);

Notice what’s missing: there is no &mut T anywhere. You never borrow the inside. You read out a copy or write one in. That’s why this works across threads at all — there’s nothing to alias.

Read-modify-write: the real reason atomics exist

The fetch_* family is where atomics earn their keep. Each is a single uninterruptible round-trip:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

use std::sync::atomic::{AtomicI32, Ordering};

let n = AtomicI32::new(10);

assert_eq!(n.fetch_add(5, Ordering::Relaxed), 10);  // returns old
assert_eq!(n.load(Ordering::Relaxed), 15);

assert_eq!(n.fetch_sub(3, Ordering::Relaxed), 15);
assert_eq!(n.fetch_or(0b1000, Ordering::Relaxed), 12);
assert_eq!(n.fetch_and(0b1100, Ordering::Relaxed), 0b1100);
assert_eq!(n.load(Ordering::Relaxed), 0b1100);

fetch_add, fetch_sub, fetch_or, fetch_and, fetch_xor, fetch_min, fetch_max — each one returns the value before the operation. That “before” is what makes them composable: you know exactly which thread did the increment that took you from 999 to 1000.

For anything more complex than a single op (clamp, toggle a state machine, transform), reach for update instead of hand-rolling a compare_exchange loop.

AtomicBool: the flag that doesn’t need a Mutex

The most common “I just want one bit” case:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

use std::sync::atomic::{AtomicBool, Ordering};

let stop = AtomicBool::new(false);

// thread A
stop.store(true, Ordering::Release);

// thread B's hot loop
if stop.load(Ordering::Acquire) {
    // shut down
}
# assert!(stop.load(Ordering::Acquire));

Release on the writer + Acquire on the reader pairs everything written before the store with everything read after the load — the standard cancellation-flag pattern. Relaxed would be fine if stop is the only thing the two threads share; use Acquire/Release when the flag is gating other writes.

The full menu

std::sync::atomic ships an atomic for every primitive size:

Not every target supports every width lock-free (32-bit ARM lacks 64-bit CAS, for example). cfg(target_has_atomic = "64") lets you gate code that requires it. On modern x86_64 and aarch64, all of the above are lock-free.

What you give up vs Mutex<T>

Atomics work only on values the CPU already knows how to swap in one instruction. The moment you need to atomically update two fields together — a counter and a timestamp, say — you’re back to Mutex<T>. There is no AtomicStruct. You can’t fetch_push a Vec.

The other thing you give up is loud failure. A Mutex poisoned by a panic returns an Err; a deadlock blocks forever and shows up in a stack dump. An atomic happily does the wrong thing forever if you pick the wrong Ordering — the bug manifests as a flaky test under heavy load on a weakly-ordered CPU, and not at all on your laptop. Use SeqCst when in doubt; reach for Relaxed/Acquire/Release only when you can name what’s being synchronized with what.

When to reach for atomics

Counters, flags, generation numbers, fetch_add-style ID allocators, the “is this initialized yet” bit. Anything where the value fits in a register and the only operation is read / write / one-shot RMW.

Anything fatter — a config map, a parsed AST, a connection pool — wants a Mutex<T> or RwLock<T> wrapped in an Arc. And for the “compute once, then read forever” case across threads, there’s a purpose-built tool — that’s this afternoon’s bite.

This morning’s Mutex<T> treats every caller the same: one at a time, no matter what they’re doing. If ninety-nine of them only want to read, that’s ninety-nine threads serialized behind a lock they didn’t need. RwLock<T> splits the door in two — many readers OR one writer — so read-heavy workloads actually fan out.

The pain: Mutex serializes readers too

A Mutex doesn’t know or care whether you’re going to mutate. Two threads that just want to peek at a config still queue up:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

use std::sync::{Arc, Mutex};
use std::thread;

let config = Arc::new(Mutex::new(vec!["a", "b", "c"]));
let mut handles = Vec::new();

for _ in 0..8 {
    let c = Arc::clone(&config);
    handles.push(thread::spawn(move || {
        let g = c.lock().unwrap();        // all 8 threads serialize here
        g.iter().map(|s| s.len()).sum::<usize>()
    }));
}

Eight threads, eight reads, zero writes — and they still run one at a time. For a config that’s read on every request and updated once an hour, that’s a lot of wasted parallelism.

The fix: read() and write()

RwLock<T> has two acquire methods, and they map directly onto the two halves of the aliasing rule:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

use std::sync::RwLock;

let lock = RwLock::new(vec![1, 2, 3]);

// Many readers can hold a read guard at the same time.
{
    let r1 = lock.read().unwrap();
    let r2 = lock.read().unwrap();
    assert_eq!(r1.len(), 3);
    assert_eq!(r2.len(), 3);
}

// Exactly one writer at a time, with no readers alive.
{
    let mut w = lock.write().unwrap();
    w.push(4);
}

assert_eq!(*lock.read().unwrap(), vec![1, 2, 3, 4]);

read() hands back a RwLockReadGuard that derefs to &T. write() hands back a RwLockWriteGuard that derefs to &mut T. Both release on drop. The whole point: any number of read() guards can be alive at once, as long as no write() guard is.

The classic shape: Arc<RwLock<T>> with many readers

The pattern is the same Arc<_>-wraps-the-shared-thing shape as Arc<Mutex<T>>, but the parallelism story changes. Readers actually run at the same time:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

use std::sync::{Arc, RwLock};
use std::thread;

let cache: Arc<RwLock<Vec<u32>>> = Arc::new(RwLock::new(vec![10, 20, 30]));
let mut handles = Vec::new();

// 8 readers, all running concurrently.
for _ in 0..8 {
    let c = Arc::clone(&cache);
    handles.push(thread::spawn(move || {
        let g = c.read().unwrap();
        g.iter().sum::<u32>()
    }));
}

// One writer, runs alone.
{
    let c = Arc::clone(&cache);
    handles.push(thread::spawn(move || {
        let mut w = c.write().unwrap();
        w.push(40);
        0
    }));
}

let sums: Vec<u32> = handles.into_iter().map(|h| h.join().unwrap()).collect();
// Every reader saw either the pre-write or post-write state, never a torn one.
assert!(sums.iter().all(|&s| s == 60 || s == 100 || s == 0));

The point isn’t the assertion — it’s that the eight readers can interleave freely on real hardware. Swap in a Mutex and they’d be a stairstep.

The footgun: writer starvation

A reader-heavy workload can keep the lock in “shared” mode forever. A writer waiting on write() blocks every new reader from joining (on most platforms), but the current readers keep working — and as soon as one of them is done, if a new reader sneaks in before the writer is scheduled, the writer stays parked. The standard library’s RwLock does not promise any particular fairness policy, and historically the behavior varied per OS.

Two practical takeaways:

1. Keep the write path short. Compute what you want to write outside the lock; take write() only to swap the result in.
2. If you find yourself reaching for “give readers priority” or “give writers priority” knobs, you’ve outgrown std::sync::RwLock. Either restructure to publish snapshots through Arc::new swaps, or pull in parking_lot::RwLock which exposes fairness controls.

The other footgun: holding the read guard across a write

Same shape as the Mutex “hold the guard too long” bug, but uglier — because nested re-entry on the same thread will deadlock, not panic:

1
2
3
4
5
6

let lock = RwLock::new(0u32);

let r = lock.read().unwrap();
// Some library calls back into us here and tries:
let mut w = lock.write().unwrap();  // deadlock: we still hold `r`
*w += 1;

RefCell would panic loudly with already borrowed. RwLock will silently park the thread, and you’ll see it only in a stack dump. When in doubt, drop the guard explicitly before any call you don’t control.

Going the other way: downgrade to keep reading what you just wrote

Once you’ve finished a write and want to keep reading the same value without a release/reacquire window, RwLockWriteGuard::downgrade is the atomic way across. Worth knowing about for the cache-refresh shape, where the writer thread immediately turns into a long-lived reader.

When to pick RwLock vs Mutex

Mutex<T> for short critical sections, mixed read/write workloads, or anywhere the per-operation cost of a lock matters. Cheaper per acquire, simpler mental model, no fairness surprises.

RwLock<T> when reads vastly outnumber writes and the read critical section is non-trivial — long enough that running them in parallel actually pays for the higher per-acquire cost. Read-only config lookups served on every request, periodically refreshed snapshots, anything shaped like “1000 readers, 1 writer per minute.”

If reads are short (a single field load) and contention is low, plain Mutex is often faster in practice — the extra bookkeeping in RwLock isn’t free. Measure before assuming the read-write split is a win.

Yesterday’s RefCell<T> gives you &mut through &self on a single thread — and panics the moment a second borrow shows up. Mutex<T> is the same idea wearing a hard hat: it’s Sync, so it works across threads, and instead of panicking on contention it just blocks until the other holder is done.

The pain: RefCell is single-threaded, and panics on contention

RefCell<T> is !Sync. The moment you try to share one across threads, the compiler stops you:

1
2
3
4
5
6
7
8
9

use std::cell::RefCell;
use std::sync::Arc;
use std::thread;

let shared = Arc::new(RefCell::new(0u32));
let s2 = Arc::clone(&shared);

thread::spawn(move || { *s2.borrow_mut() += 1; });
// error[E0277]: `RefCell<u32>` cannot be shared between threads safely

Even on one thread, RefCell will panic if a borrow_mut() clashes with a live borrow(). That’s fine for logic bugs you want to find loudly — useless for two real threads that genuinely both want to write.

The fix: lock() returns a guard

Mutex<T> is Sync (when T: Send), and its .lock() method takes &self, blocks until the mutex is free, and hands back a MutexGuard<'_, T>. The guard derefs to &mut T, and releases the lock when it drops:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

use std::sync::Mutex;

let m = Mutex::new(0u32);

{
    let mut g = m.lock().unwrap();   // blocks here if held; we're alone, so it's instant
    *g += 1;
    *g += 1;
}                                     // lock released as `g` drops

assert_eq!(*m.lock().unwrap(), 2);

The .unwrap() is there because lock() returns Result — see “Poisoning” below.

The classic: Arc<Mutex<T>> across threads

Mutex is the inside half. To share ownership across threads you wrap it in Arc — the thread-safe sibling of Rc (covered in Sunday’s morning bite):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

use std::sync::{Arc, Mutex};
use std::thread;

let counter = Arc::new(Mutex::new(0u32));
let mut handles = Vec::new();

for _ in 0..8 {
    let c = Arc::clone(&counter);
    handles.push(thread::spawn(move || {
        for _ in 0..100 {
            *c.lock().unwrap() += 1;
        }
    }));
}

for h in handles { h.join().unwrap(); }

assert_eq!(*counter.lock().unwrap(), 800);

Eight threads, a hundred increments each, eight hundred total — no torn writes, no races, because every increment runs while exactly one thread holds the lock.

The footgun: holding the guard too long

The single most common Mutex bug is leaving the guard alive across slow work. Anything between lock() and the guard going out of scope is serialized:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// BAD — lock held for the whole block, including the slow call
let g = state.lock().unwrap();
if let Some(v) = g.cache.get(&key) {
    slow_network_thing(v);            // every other thread is blocked on us
}

// BETTER — get out what you need, drop the guard, then do the slow work
let v = state.lock().unwrap().cache.get(&key).cloned();
if let Some(v) = v {
    slow_network_thing(&v);
}

drop(g) works too if you can’t easily restructure. The mental model: the guard is a lease, keep it as short as you can.

Poisoning, and why .lock() returns Result

If a thread panics while holding the lock, the Mutex is poisoned. Future lock() calls return Err(PoisonError) so you can decide whether the data is still consistent. You can always recover the inner guard with .into_inner():

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

use std::sync::{Arc, Mutex};
use std::thread;

let m = Arc::new(Mutex::new(vec![1, 2, 3]));
let m2 = Arc::clone(&m);

let _ = thread::spawn(move || {
    let _g = m2.lock().unwrap();
    panic!("oops");
}).join();                            // panic propagates, then mutex is poisoned

let mut g = match m.lock() {
    Ok(g) => g,
    Err(p) => p.into_inner(),         // we know our data is still fine
};
g.push(4);
assert_eq!(*g, vec![1, 2, 3, 4]);

For data where one panic mid-update really would leave things half-written, the Err is the signal to crash the whole component instead of papering over it.

When to pick Mutex vs RefCell vs RwLock

RefCell<T> for single-threaded interior mutability where contention is a bug. Panics loudly. Zero locking cost.

Mutex<T> when more than one thread needs to write — or might. Blocks instead of panicking. One holder at a time, readers and writers treated identically.

RwLock<T> (covered in this afternoon’s bite) when reads vastly outnumber writes and you want many readers to proceed in parallel. Pricier per-op than Mutex, but the parallelism wins for read-heavy workloads.

This morning’s OnceCell / LazyCell bite — and Cell, RefCell, Mutex, RwLock, OnceLock, every atomic — all bottom out at the same type: UnsafeCell<T>. It is the one and only legal way in Rust to mutate through a shared reference. You’ll almost never type its name, but knowing what it does explains why all the rest exist.

The pain: &T is “you may not mutate” — to the optimizer too

Outside UnsafeCell, the compiler is allowed to assume &T points to data that won’t change underneath it. It can cache loads, hoist reads out of loops, mark pointers noalias in LLVM. Try to fake interior mutability with a raw cast and you’ve signed up for undefined behavior — not “it works but is ugly,” actual UB the optimizer is free to exploit:

1
2
3
4

fn cheat(r: &u32) {
    let p = r as *const u32 as *mut u32;
    unsafe { *p = 99; } // UB: mutating through &T without UnsafeCell
}

The cast compiles. The write may even appear to happen. But the program has lost all guarantees, and the next release of rustc — or a different opt level — can break it.

The fix: UnsafeCell::get returns *mut T through &self

UnsafeCell<T> is the one type the compiler treats specially: a &UnsafeCell<T> is not a promise that the inside won’t change, so noalias and friends don’t apply. Its .get() method takes &self and hands back a raw *mut T:

1
2
3
4
5
6

use std::cell::UnsafeCell;

let cell = UnsafeCell::new(10u32);
let p: *mut u32 = cell.get();    // legal through &cell
unsafe { *p = 20; }              // legal — UnsafeCell opted out of the no-mutation rule
assert_eq!(unsafe { *cell.get() }, 20);

That’s the whole feature. Every other interior-mutability type in std is a safe wrapper around exactly this primitive plus an invariant — a borrow counter, a lock bit, an atomic flag — that justifies the unsafe block inside.

Build Cell from scratch in 20 lines

To see it in action, here’s a stripped-down Cell<T> clone. Real std::cell::Cell is more polished, but the shape is identical:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

use std::cell::UnsafeCell;

struct MyCell<T> {
    value: UnsafeCell<T>,
}

impl<T: Copy> MyCell<T> {
    fn new(v: T) -> Self {
        Self { value: UnsafeCell::new(v) }
    }

    fn get(&self) -> T {
        // SAFETY: UnsafeCell makes Self !Sync, so no thread races us.
        // We never hand out a reference into the cell, so no aliased &mut exists.
        unsafe { *self.value.get() }
    }

    fn set(&self, v: T) {
        // SAFETY: same as `get`.
        unsafe { *self.value.get() = v; }
    }
}

let counter = MyCell::new(0u32);
counter.set(counter.get() + 1);
counter.set(counter.get() + 1);
assert_eq!(counter.get(), 2);

UnsafeCell does the optimizer-level work; the Copy bound plus “never lend a reference out” does the safety work. Drop either piece and the type is unsound.

The !Sync default — and how Mutex opts back in

UnsafeCell<T> is !Sync even when T: Sync. That’s deliberate: if you could share an &UnsafeCell<T> across threads with no synchronization, two threads could race on the inside and you’d be back to UB.

That’s why Cell and RefCell are !Sync (single-thread only), and why Mutex<T> carries an explicit:

1

unsafe impl<T: ?Sized + Send> Sync for Mutex<T> {}

The unsafe impl is the author asserting “I added the lock; now sharing across threads is sound.” The pattern recurs in every sync interior-mutability type — RwLock (tomorrow’s afternoon bite), OnceLock, LazyLock, the atomics. The shape is always: UnsafeCell<T> + an invariant + an unsafe impl Sync.

When to reach for it yourself

In application code: basically never. Cell, RefCell, Mutex, RwLock, OnceCell, OnceLock cover every common pattern and they’re already audited.

Real reasons to hold UnsafeCell directly: writing a new lock primitive, an arena that hands out &mut slots from &self, a lock-free data structure, FFI cells that mirror an existing C struct. If you’re not building infrastructure of that kind, the right move is to use a wrapper that already wraps it — and now you know what’s in the bottom of the box.

You have a parse(&self) -> &Heavy accessor that needs to compute once and cache. &self rules out a plain field assignment. Cell needs Copy. RefCell won’t lend the inside out past .borrow(). OnceCell<T> is the missing piece — write-once, &self API, hands back a real &T that lives as long as the cell.

The pain: &self memoization is awkward

Classic shape — an immutable-looking accessor that’s expensive on first call and free afterwards:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

use std::cell::RefCell;

struct DocSlow {
    raw: String,
    parsed: RefCell<Option<Vec<String>>>,
}

impl DocSlow {
    fn lines(&self) -> Vec<String> {
        let mut slot = self.parsed.borrow_mut();
        if slot.is_none() {
            *slot = Some(self.raw.lines().map(str::to_owned).collect());
        }
        slot.clone().unwrap() // can't return a borrow that escapes RefMut
    }
}

Two problems. We .clone() on every call because a Ref<'_, T> can’t outlive the borrow() it came from. And Option<Vec<String>> plus runtime borrow checking is overkill for “set this exactly once.”

The fix: OnceCell::get_or_init

OnceCell<T> stores at most one value. get_or_init runs the closure the first time it’s called and returns &T ever after — and that &T is tied to the lifetime of &self, so you can hand it back without cloning:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

use std::cell::OnceCell;

struct Doc {
    raw: String,
    parsed: OnceCell<Vec<String>>,
}

impl Doc {
    fn new(s: &str) -> Self {
        Self { raw: s.to_owned(), parsed: OnceCell::new() }
    }

    fn lines(&self) -> &[String] {
        self.parsed
            .get_or_init(|| self.raw.lines().map(str::to_owned).collect())
    }
}

let doc = Doc::new("one\ntwo\nthree");
assert_eq!(doc.lines(), &["one", "two", "three"]);
assert_eq!(doc.lines().len(), 3); // cached — closure does not run again

No Option, no clone, no borrow_mut. The closure fires exactly once even across multiple calls, and the returned slice is good for as long as the &Doc is.

When you want to decide later, not on first read

OnceCell doesn’t require a closure at the call site. Use set when initialization is driven by something outside the cell — a parsed CLI flag, a value computed by a sibling method, anything that doesn’t fit a self-contained || ...:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

use std::cell::OnceCell;

let cell: OnceCell<String> = OnceCell::new();
assert_eq!(cell.get(), None);

cell.set("loaded".into()).unwrap();
assert_eq!(cell.get(), Some(&"loaded".to_string()));

// Second set is rejected — the cell is full.
assert!(cell.set("nope".into()).is_err());

set returns Err(value) on the second call so you get your input back instead of dropping it on the floor. Reach for set when initialization is driven from outside; reach for get_or_init when it isn’t.

LazyCell<T, F>: when the closure is fixed at construction

If you already know how to build the value when you create the cell, LazyCell bakes the closure in and skips the Option-style API. The first deref runs it:

1
2
3
4
5
6
7
8

use std::cell::LazyCell;

let tags: LazyCell<Vec<&'static str>> = LazyCell::new(|| {
    vec!["rust", "interior-mutability"]
});

assert_eq!(tags.len(), 2);   // closure runs here
assert_eq!(tags[0], "rust"); // cached

Rule of thumb: LazyCell when there is exactly one obvious way to compute the value and you want the cell to handle it; OnceCell when you need set from outside, or different get_or_init closures at different call sites.

Thread safety

Both types are !Sync — they’re the single-thread counterparts to OnceLock / LazyLock. If a static or a field shared across threads needs this pattern, swap to the sync versions. The API shape is intentionally the same; only the guarantees (and the cost) change.

This morning’s Cell<T> only lets you swap whole values in and out. The moment you want to call .push() on the Vec inside, or hand out a &str slice of the String inside, you need a real &mut — and that’s exactly what RefCell<T> gives you, just with the aliasing rules checked at runtime instead of compile time.

The pain: Cell can’t lend the inside out

Cell<T> is great until you need to do anything to the value in place:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

use std::cell::Cell;

let log: Cell<Vec<String>> = Cell::new(Vec::new());

// We want: log.push("hit".into());
// We can't — Cell only gives us `get` (copy) and `set` (overwrite).
// `log.get_mut()` exists, but that needs `&mut Cell`, defeating the point.

// Workaround: take the Vec out, mutate, put it back.
let mut v = log.take();
v.push("hit".into());
log.set(v);

The take/mutate/replace dance works but it’s noisy, and any code that runs between take and set sees an empty Vec. For non-trivial data structures — a cache, an arena, a graph node — that “hole” is unworkable.

The fix: borrow() and borrow_mut()

RefCell<T> hands out actual references through &self. borrow() gives you a Ref<T> (deref to &T), borrow_mut() gives you a RefMut<T> (deref to &mut T):

1
2
3
4
5
6
7
8
9

use std::cell::RefCell;

let log: RefCell<Vec<String>> = RefCell::new(Vec::new());

log.borrow_mut().push("first".into());
log.borrow_mut().push("second".into());

assert_eq!(log.borrow().len(), 2);
assert_eq!(log.borrow()[0], "first");

Both methods take &self, so this works behind an Rc, inside an Fn closure, in any field of a struct you only have a shared reference to. That’s the whole point of interior mutability — &self outside, &mut inside.

The invariant: same rules, just checked at runtime

RefCell enforces the exact same aliasing rule the compiler enforces statically: many &T xor one &mut T. Try to break it and it panics:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

use std::cell::RefCell;

let cell = RefCell::new(vec![1, 2, 3]);

let r1 = cell.borrow();
let r2 = cell.borrow();    // fine — multiple readers
assert_eq!(r1.len(), 3);
assert_eq!(r2.len(), 3);
drop((r1, r2));

let mut w = cell.borrow_mut();
w.push(4);
// cell.borrow();          // would panic: already mutably borrowed
drop(w);

assert_eq!(cell.borrow().len(), 4);

The panic message is already borrowed: BorrowMutError (or BorrowError). If you can’t guarantee statically that the borrows are well-nested, use try_borrow / try_borrow_mut — they return a Result instead of panicking, which is what you want inside a Drop impl or any code path that already might be re-entering itself.

A real pattern: shared mutable state through Rc<RefCell<_>>

The canonical use is sharing one piece of mutable state between several owners on a single thread — a cache, a config, an observer list:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

use std::cell::RefCell;
use std::rc::Rc;

#[derive(Default)]
struct Cache {
    hits: u32,
    keys: Vec<String>,
}

let cache = Rc::new(RefCell::new(Cache::default()));

let writer = Rc::clone(&cache);
let reader = Rc::clone(&cache);

writer.borrow_mut().keys.push("a".into());
writer.borrow_mut().hits += 1;

let snapshot = reader.borrow();
assert_eq!(snapshot.hits, 1);
assert_eq!(snapshot.keys, vec!["a".to_string()]);

Keep borrow_mut() scopes short — release the RefMut (let it drop) before calling any code that might try to borrow the same cell again. The most common “works in tests, panics in prod” bug with RefCell is a long-lived RefMut colliding with a callback that re-enters.

When to pick RefCell vs Cell

Cell<T> if swapping or copying whole values is enough — counters, flags, small Copy state. Zero overhead, no panic risk.

RefCell<T> when the inside is a real data structure you want to call methods on in place: Vec, String, HashMap, your own structs. You pay one extra word for the borrow flag and runtime checks, but you get the full &T / &mut T API back.

For multi-threaded shared state, neither of these works — both are !Sync. Reach for Mutex<T> (covered in tomorrow’s morning bite) or RwLock<T> instead.

You hand the same struct to two closures and both want to bump a counter. &mut fights you, RefCell introduces runtime borrow checks you don’t need — Cell<T> quietly mutates through a shared & reference, with zero overhead, as long as you only ever swap whole values in and out.

The pain: shared & and a counter

Two closures, one counter, one immutable reference:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

struct Counter {
    hits: u32,
}

let counter = Counter { hits: 0 };
let bump = || {
    // ERROR: cannot assign to `counter.hits`, which is behind a `&` reference
    // counter.hits += 1;
};
bump();

Fn closures only capture &, so a plain field is read-only. You could redesign for FnMut and a single owner, but the moment you have two observers or a callback registry, you need interior mutability.

The fix: Cell<T> mutates through &

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

use std::cell::Cell;

struct Counter {
    hits: Cell<u32>,
}

let counter = Counter { hits: Cell::new(0) };

let bump = || counter.hits.set(counter.hits.get() + 1);
let read = || counter.hits.get();

bump();
bump();
bump();
assert_eq!(read(), 3);

Cell::new wraps the value; get returns a copy (so T: Copy for that method); set overwrites. Both take &self — no &mut anywhere — which is why this works inside Fn closures, inside Rc, inside any structure that hands out shared references.

The invariant: you can never borrow the inside

This is the single rule that makes Cell<T> sound without runtime checks: you cannot get a reference to the value inside, only copies and swaps. There is no cell.as_ref(), no cell.deref(). The compiler enforces this — there’s nothing to alias, so the optimizer is free to assume the inner value can’t change underneath an outstanding &T.

That’s also why Cell<T> is !Sync — fine for one thread, but two threads racing on set would tear the value. For threads, reach for Atomic* (scalars) or Mutex<T> (the rest).

replace and take work for non-Copy types too

get requires T: Copy, but Cell works with String, Vec, anything — you just have to move the value out instead of copying it:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

use std::cell::Cell;

let slot: Cell<String> = Cell::new(String::from("hello"));

// `replace` swaps in a new value, returns the old one.
let old = slot.replace(String::from("world"));
assert_eq!(old, "hello");

// `take` is `replace(Default::default())`.
let now: String = slot.take();
assert_eq!(now, "world");
assert_eq!(slot.into_inner(), ""); // default String

This is the trick people miss: Cell<Vec<T>> is perfectly usable for a shared, append-only-ish buffer — you just swap the whole Vec in and out.

When to pick Cell vs RefCell

Cell<T> if you only need to swap whole values: counters, flags, configuration knobs, small Copy state, or any field where replace/take is enough. Zero runtime overhead, no panic risk.

RefCell<T> (tomorrow afternoon’s bite) if you need to borrow the inside — call &mut self methods on a Vec in place, hand a &str slice to a caller, anything where copying or swapping the whole value would be wrong. You pay for runtime borrow tracking and risk a panic, but you get back the ability to use the value normally.

Default to Cell when it fits — it almost always does for simple shared-state tweaks, and the “no inner references” rule turns out to be exactly what you wanted anyway.

You reserve 4 KiB to read from a socket, and to hand the buffer over you first… write 4096 zeros. Vec::spare_capacity_mut exposes the reserved-but-uninitialized tail as &mut [MaybeUninit<u8>] so the callback writes straight into the allocation.

The pain: paying to overwrite

The intuitive fill-a-buffer pattern resizes the Vec first so the slice exists:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

let mut buf: Vec<u8> = Vec::with_capacity(8);
buf.resize(8, 0); // writes 8 zeros we're about to clobber

// Pretend this is `read(fd, buf.as_mut_ptr(), buf.len())`.
fill(&mut buf);

assert_eq!(buf, b"rustbite");

fn fill(out: &mut [u8]) {
    out.copy_from_slice(b"rustbite");
}

It works, but resize walks the whole tail writing zeros that the next line overwrites — a measurable cost for big reads, and pointless for types where “zero” isn’t even a valid value.

The fix: write into the uninitialized tail

Vec::spare_capacity_mut(&mut self) -> &mut [MaybeUninit<T>] hands you a slice covering exactly capacity - len slots. Write into them, then call set_len to tell the Vec they’re now initialized:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

use std::mem::MaybeUninit;

let mut buf: Vec<u8> = Vec::with_capacity(8);

// View the reserved-but-uninitialized tail.
let spare: &mut [MaybeUninit<u8>] = buf.spare_capacity_mut();
assert_eq!(spare.len(), 8);

// Write through the MaybeUninit pointer — no zeroing first.
for (slot, byte) in spare.iter_mut().zip(b"rustbite") {
    slot.write(*byte);
}

// Promise the Vec those 8 slots are now valid `u8`s.
unsafe { buf.set_len(8); }

assert_eq!(buf, b"rustbite");

spare_capacity_mut itself is safe — MaybeUninit<T> is the type that lets you hold “maybe garbage” without UB. The unsafe block is just the set_len call where you assert you really did initialize them.

Pairing with a real fill API

The standard pattern is “reserve, write, set_len”:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

use std::mem::MaybeUninit;

fn read_bytes(buf: &mut Vec<u8>, extra: usize, source: &[u8]) {
    buf.reserve(extra);

    let spare = buf.spare_capacity_mut();
    let n = extra.min(source.len()).min(spare.len());

    // Initialize the prefix we actually wrote.
    for i in 0..n {
        spare[i].write(source[i]);
    }

    // Only extend by what's been initialized.
    unsafe { buf.set_len(buf.len() + n); }
}

let mut v = vec![b'>', b' '];
read_bytes(&mut v, 8, b"rustbite");
assert_eq!(v, b"> rustbite");

The same shape works with read-style callbacks: cast the MaybeUninit<u8> slice to a raw pointer, hand it to C, and only extend len by the byte count the call returned. The bytes you didn’t write stay MaybeUninit — never read them.

When to reach for it

Reading from sockets, files, or FFI fill-style APIs into a Vec<u8> is the headline use case — every tokio and mio read path eventually bottoms out in this pattern. It’s also useful for non-Copy types where there’s no sensible default to seed with: image decoders writing Vec<Pixel>, audio decoders writing Vec<f32>, parser arenas writing Vec<Node>.

If you don’t need the spare capacity view — you’re building up element-by-element — Vec::push (or Vec::push_mut from bite 88) is still the right call. spare_capacity_mut is the tool for the moment you have an external writer that wants a flat buffer and you’d rather not pay to zero it first.