Interior Mutability: RefCell<T> and Mutex<T>

In TypeScript every object is freely mutable through any reference you hold — aliasing and mutation coexist without comment. Rust forbids that at compile time: you may have many shared & references or one exclusive &mut, never both. Interior mutability is the escape hatch that lets you mutate data through a shared reference anyway, by moving the “one writer, many readers” check from compile time to runtime. RefCell<T> does this on a single thread; Mutex<T> does it across threads.

---

Quick Overview

RefCell<T> and Mutex<T> both let you mutate data you only hold a shared reference to (&self rather than &mut self). They enforce the same rule the borrow checker enforces statically — no aliased mutation — but they enforce it dynamically. RefCell checks on the current thread and panics if you break the rule; Mutex is thread-safe and blocks until the data is free. For a TypeScript developer the mental model is: these types give you back the casual “mutate through any handle” feeling of JavaScript objects, but with a guardrail that fails loudly instead of silently corrupting data.

Note: This file covers the two checked interior-mutability containers. Its single-threaded sibling for Copy values, Cell<T>, needs no runtime flag at all. For sharing the same data between owners (the thing you almost always combine RefCell/Mutex with) see Rc<T> / Arc<T>. When you cannot decide which container to reach for, jump to the decision guide.

---

TypeScript/JavaScript Example

In TypeScript, a shared mutable object is the default. Here a MetricsCollector is handed to several subsystems; each holds the same object and mutates it freely. Nothing in the type system stops two code paths from writing at “the same time.” JavaScript’s single-threaded event loop makes that mostly safe, and TypeScript never asks you to think about it.

// TypeScript/JavaScript - shared mutable state is the default
class MetricsCollector {
  private counts = new Map<string, number>();

  // `increment` mutates internal state, but callers never see a difference
  // between a "read" method and a "write" method — both just take `this`.
  increment(event: string): void {
    this.counts.set(event, (this.counts.get(event) ?? 0) + 1);
  }

  total(): number {
    let sum = 0;
    for (const n of this.counts.values()) sum += n;
    return sum;
  }
}

const metrics = new MetricsCollector();

// Two unrelated subsystems share the SAME collector via aliasing.
const auth = metrics;
const api = metrics;

auth.increment("login");
api.increment("request");
api.increment("request");

console.log(metrics.total()); // 3

Under Node v22 this prints 3. Note three things a Rust developer will care about: the two aliases (auth, api) point at one object, increment mutates through a plain shared reference, and nobody had to declare the object “mutable.”

---

Rust Equivalent

The naive port fails: if record takes &self, you cannot assign to self.hits. Wrapping the field in RefCell<T> restores the ability to mutate through a shared reference: borrow_mut() hands you a temporary exclusive handle, checked at runtime.

use std::cell::RefCell;

#[derive(Debug)]
struct Counter {
    hits: RefCell<u32>,
}

impl Counter {
    fn new() -> Self {
        Counter { hits: RefCell::new(0) }
    }

    // Note: &self, NOT &mut self — the mutation happens "inside" the cell.
    fn record(&self) {
        *self.hits.borrow_mut() += 1;
    }

    fn total(&self) -> u32 {
        *self.hits.borrow()
    }
}

fn main() {
    let counter = Counter::new();
    counter.record();
    counter.record();
    counter.record();
    println!("total hits = {}", counter.total());
}

Running it prints:

total hits = 3

The signature fn record(&self) is the whole point. The method takes a shared reference, yet mutates, exactly the TypeScript ergonomics, but the mutation is funneled through RefCell’s runtime check rather than being a free-for-all.

---

Detailed Explanation

Why the compiler refuses plain mutation through &self

Rust’s borrowing rules are not a style guide; they are how the language guarantees memory safety without a garbage collector (see Section 05 — Ownership). The rule: at any instant a value has either one &mut reference or any number of & references. A method taking &self only has a shared reference, so writing to a field is rejected:

struct Logger {
    count: u32, // plain field, no interior mutability
}

impl Logger {
    fn log(&self, msg: &str) {
        println!("{msg}");
        self.count += 1; // does not compile (error[E0594]): cannot assign through &self
    }
}

fn main() {
    let logger = Logger { count: 0 };
    logger.log("hi");
}

The real compiler output:

error[E0594]: cannot assign to `self.count`, which is behind a `&` reference
 --> src/main.rs:8:9
  |
8 |         self.count += 1; // does not compile (error[E0594]): cannot assign through &self
  |         ^^^^^^^^^^^^^^^ `self` is a `&` reference, so the data it refers to cannot be written
  |
help: consider changing this to be a mutable reference
  |
6 |     fn log(&mut self, msg: &str) {
  |             +++

Sometimes &mut self is the right fix. But it is contagious: every caller now needs exclusive access, which is impossible the moment the value is shared (behind an Rc, stored in a Vec you are iterating, captured by two closures). RefCell is the answer when you need the mutation but cannot get exclusive access at compile time.

What borrow and borrow_mut actually return

RefCell<T> is a struct holding your T plus a small integer “borrow flag.” Two methods read and update that flag:

• borrow() -> Ref<'_, T>: registers a shared borrow and returns a smart-pointer guard that derefs to &T.
• borrow_mut() -> RefMut<'_, T>: registers an exclusive borrow and returns a guard that derefs to &mut T.

The guard’s Drop releases the borrow. So the flag tracks “how many Refs and whether a RefMut is alive” exactly the way the compiler’s static analysis would, just at runtime. The *self.hits.borrow_mut() += 1 line creates a RefMut, dereferences it to a &mut u32, increments, and drops the guard at the end of the statement (the temporary’s lifetime ends at the ;).

Runtime checking means runtime panics

If you violate the one-writer rule, RefCell does not return an error by default; it panics, the same way an out-of-bounds array index does. Holding a read borrow and then asking for a write borrow:

use std::cell::RefCell;

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

    let reader = cell.borrow();          // Ref<Vec<i32>>, a shared read borrow
    println!("len is {}", reader.len());
    cell.borrow_mut().push(4);           // panics: reader is still alive
}

The real output:

len is 3

thread 'main' panicked at src/main.rs:8:10:
already borrowed: BorrowMutError
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

reader is still in scope when borrow_mut() runs, so the borrow flag says “a shared borrow is active” and the write request panics. The fix is to end the read borrow first: drop reader or scope it in a { } block.

Mutex<T>: the same idea, made thread-safe

RefCell is not thread-safe (it is !Sync), so the compiler will not let you share one across threads. When you need interior mutability across threads, reach for std::sync::Mutex<T>. It enforces the identical rule — one writer at a time — but instead of panicking when the data is busy, lock() blocks the calling thread until the lock is free.

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

fn main() {
    let counter = Arc::new(Mutex::new(0u64));
    let mut handles = Vec::new();

    for _ in 0..8 {
        let counter = Arc::clone(&counter);
        let handle = thread::spawn(move || {
            for _ in 0..1000 {
                // lock() blocks until the mutex is free, returns a guard.
                let mut n = counter.lock().unwrap();
                *n += 1;
            } // guard dropped here -> lock released each iteration
        });
        handles.push(handle);
    }

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

    println!("final count = {}", *counter.lock().unwrap());
}

Running it prints:

final count = 8000

Eight threads each increment 1000 times; the Mutex serializes every *n += 1, so the result is exactly 8000 with no lost updates. The Arc (atomic reference count) is what lets all eight threads own the same mutex. Mutex provides the mutation, Arc provides the sharing. This Arc<Mutex<T>> pair is to multithreaded Rust what a plain shared object is to JavaScript.

Tip: lock() returns a Result because the mutex can be poisoned (see Pitfalls). In application code, .unwrap() (or .expect("lock poisoned")) is the common, accepted choice: a poisoned lock usually means another thread already crashed.

Holding the guard for as little time as possible

A MutexGuard (and a RefMut) keeps the lock until it is dropped. Wrapping the locked work in a block releases it early, before any expensive non-locked work runs:

use std::sync::Mutex;

fn main() {
    let data = Mutex::new(vec![10, 20, 30]);

    let sum: i32 = {
        let guard = data.lock().unwrap();
        guard.iter().sum()
    }; // guard dropped here, before the println formatting below

    println!("sum = {}", sum);
}

Output:

sum = 60

When you do have exclusive access, skip the lock

If you own a Mutex<T> by &mut (or by value), the compiler has already proven no other thread can touch it, so locking is pure overhead. get_mut() (borrow) and into_inner() (by value) reach the data without any locking:

use std::sync::Mutex;

fn main() {
    let mut m = Mutex::new(0);
    // We own `m` mutably, so the compiler proves no other thread can race.
    *m.get_mut().unwrap() += 100;
    println!("value = {}", m.into_inner().unwrap());
}

Output:

value = 100

This mirrors RefCell::get_mut, and it is a good signal of intent: it tells the reader “no contention is possible here.”

---

Key Differences

Concept	TypeScript / JavaScript	RefCell<T> (Rust)	Mutex<T> (Rust)
Mutate via shared handle	Always allowed	Allowed, runtime-checked	Allowed, runtime-checked
Aliased mutation rule	None enforced	One writer XOR many readers	One writer at a time
When the rule is broken	Possible silent bug	Panics immediately	(Cannot — it blocks)
Thread-safe?	N/A (single event loop)	No (!Sync)	Yes (Send + Sync)
Cost when uncontended	n/a	A few integer ops	An atomic compare-and-swap
Get exclusive access cheaply	n/a	get_mut()	get_mut(), into_inner()
Typical pairing for sharing	just alias the object	Rc<RefCell<T>>	Arc<Mutex<T>>

A few conceptual contrasts worth internalizing:

• Compile-time vs runtime. Rust’s default borrow checking is static and free. RefCell and Mutex opt into a runtime check, paying a little performance and (for RefCell) the risk of a panic, in exchange for flexibility the static checker cannot express.
• Panic vs block. This is the headline difference between the two types. A second borrow_mut on a busy RefCell is a bug and panics. A second lock on a busy Mutex is normal contention and waits. They feel similar but model opposite situations.
• Mutex<T> wraps the data, it is not a separate object. Unlike a Java synchronized block or a free-standing lock variable, a Rust Mutex contains the data it protects. You literally cannot read the value without locking: the type system makes “forgot to take the lock” impossible.
• Unlike TypeScript, sharing and mutating are separate concerns with separate tools. JavaScript gives you both in one move (alias an object). Rust makes you pick a sharer (Rc/Arc) and a mutator (RefCell/Mutex) and compose them.

---

Common Pitfalls

Pitfall 1: Two live borrow_muts on the same thread

The single most common RefCell mistake, taking a second mutable borrow while the first is alive:

use std::cell::RefCell;

fn main() {
    let cell = RefCell::new(5);

    let mut first = cell.borrow_mut();
    let mut second = cell.borrow_mut(); // panics: already mutably borrowed
    *first += 1;
    *second += 1;
}

Real output:

thread 'main' panicked at src/main.rs:7:27:
already borrowed: BorrowMutError
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

The opposite ordering (a read while a write is held) panics with a slightly different message — already mutably borrowed: BorrowError — but it is the same class of bug. Fix: never hold two borrows that overlap. Finish with the first guard (let it drop, or scope it) before taking the second, and prefer one short borrow_mut() per statement over long-lived guard variables.

Pitfall 2: Trying to send a RefCell across threads

A RefCell looks like it should work in a thread, but it is !Sync and the compiler rejects sharing it: exactly the protection that pushes you toward Mutex:

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

fn main() {
    let shared = Arc::new(RefCell::new(0));

    let s = Arc::clone(&shared);
    let handle = thread::spawn(move || {
        *s.borrow_mut() += 1; // does not compile: RefCell is not Sync
    });

    handle.join().unwrap();
    println!("{}", shared.borrow());
}

The real error (abridged):

error[E0277]: `RefCell<i32>` cannot be shared between threads safely
   --> src/main.rs:9:32
    |
  9 |       let handle = thread::spawn(move || {
    |  __________________-------------_^
...
    | |_____^ `RefCell<i32>` cannot be shared between threads safely
    |
    = help: the trait `Sync` is not implemented for `RefCell<i32>`
    = note: if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` instead
    = note: required for `Arc<RefCell<i32>>` to implement `Send`

Fix: swap RefCell for Mutex (or RwLock if reads vastly outnumber writes) and Rc for Arc: Arc<Mutex<i32>>. The compiler error is doing you a favor: it caught a data race before it could exist.

Pitfall 3: Locking the same Mutex twice on one thread (deadlock)

Because lock() blocks rather than panicking, locking a non-reentrant Mutex you already hold on the same thread deadlocks the thread forever:

// Conceptual — do NOT run; this hangs:
// let m = Mutex::new(0);
// let g1 = m.lock().unwrap();
// let g2 = m.lock().unwrap(); // thread blocks forever waiting for itself

There is no compiler error and no panic: the program simply hangs. Fix: never call lock() while you still hold a guard from the same mutex. Keep critical sections small, and if a helper needs the data, pass it &mut T from the already-acquired guard rather than re-locking.

Warning: Rust’s Mutex is not reentrant. Unlike some languages’ recursive locks, taking the same lock twice on one thread is undefined-time hang, not a no-op.

Pitfall 4: Forgetting that a long-lived guard blocks others

A MutexGuard held across an .await or a slow I/O call keeps every other thread (or task) waiting. In synchronous code this just hurts throughput; in async code it can stall an entire runtime (std::sync::Mutex should generally not be held across .await; see Section 11 — Async). Fix: copy or move what you need out of the guard, drop it, then do the slow work.

---

Best Practices

• Reach for the borrow checker first. Interior mutability is a deliberate exception, not a default. If &mut self or restructuring the data threads cleanly, prefer it: you keep compile-time guarantees and zero runtime cost.

• Keep borrows and locks short. One borrow_mut()/lock() per statement when you can. Scope guards in { } blocks so they drop early. Long-lived guards are how both panics (RefCell) and deadlocks (Mutex) happen.

• Pick the container by thread-boundary, not by habit. Single thread → RefCell (cheaper, no atomics). Crossing threads → Mutex (or RwLock for read-heavy workloads). The compiler enforces this for you via Send/Sync.

• Compose intentionally: Rc<RefCell<T>> for a shared, mutable, single-threaded graph; Arc<Mutex<T>> for the multithreaded version. Document why the shared mutability is needed.

• Use try_borrow_mut() / try_lock() when contention is expected and recoverable. They return a Result instead of panicking/blocking, so you can fall back gracefully:

  use std::cell::RefCell;
  
  fn main() {
      let cell = RefCell::new(String::from("hello"));
      let _read = cell.borrow();
      match cell.try_borrow_mut() {
          Ok(mut w) => w.push_str(" world"),
          Err(_) => println!("already borrowed; skipping mutation"),
      }
  }

  Output: already borrowed; skipping mutation.

• Prefer the unlocked accessors when you own the data. get_mut() and into_inner() skip the runtime check entirely and signal “no contention here” to the next reader of your code.

---

Real-World Example

A memoizing cache is interior mutability’s sweet spot: the interface is a read-only “look up a value,” but the implementation must mutate a cache on a miss. With RefCell the public get method takes &self, so the memoizer composes like any other read-only service. Callers never need &mut.

use std::cell::RefCell;
use std::collections::HashMap;

/// A memoizing wrapper around an expensive pure function.
/// The cache mutates on a miss, yet `get` takes `&self` — callers
/// never need a `&mut Memoizer`, so the type composes like a read-only service.
struct Memoizer<F> {
    compute: F,
    cache: RefCell<HashMap<u64, u64>>,
    calls: RefCell<u64>, // how many times we actually ran `compute`
}

impl<F: Fn(u64) -> u64> Memoizer<F> {
    fn new(compute: F) -> Self {
        Memoizer {
            compute,
            cache: RefCell::new(HashMap::new()),
            calls: RefCell::new(0),
        }
    }

    fn get(&self, key: u64) -> u64 {
        // Fast path: check the cache, and release the borrow before recomputing.
        if let Some(&hit) = self.cache.borrow().get(&key) {
            return hit;
        }
        // Miss: no borrow of `cache` is held while we run the real computation.
        *self.calls.borrow_mut() += 1;
        let value = (self.compute)(key);
        self.cache.borrow_mut().insert(key, value);
        value
    }

    fn compute_calls(&self) -> u64 {
        *self.calls.borrow()
    }
}

fn main() {
    // Pretend this is an expensive call (DB hit, hashing, etc.).
    let memo = Memoizer::new(|n: u64| n * n);

    let inputs = [4, 4, 7, 4, 7, 9];
    let results: Vec<u64> = inputs.iter().map(|&n| memo.get(n)).collect();

    println!("results       = {results:?}");
    println!("inputs        = {inputs:?}");
    println!(
        "compute calls = {} (vs {} lookups)",
        memo.compute_calls(),
        inputs.len()
    );
}

Running it prints:

results       = [16, 16, 49, 16, 49, 81]
inputs        = [4, 4, 7, 4, 7, 9]
compute calls = 3 (vs 6 lookups)

Six lookups, only three real computations: the three distinct inputs 4, 7, 9. The important detail is in get: the if let Some(&hit) = self.cache.borrow()... borrow ends at the end of that if’s condition expression, so when we later call self.cache.borrow_mut().insert(...) there is no overlapping borrow to panic on. Sequencing borrows like this — read, drop, then write — is the discipline that keeps RefCell panic-free.

Note: To make this cache thread-safe, change both RefCell to Mutex, wrap the whole Memoizer in an Arc, and lock instead of borrow. The structure is identical; only the runtime-check strategy changes.

---

Further Reading

• std::cell::RefCell — standard library docs
• std::sync::Mutex — standard library docs
• The Rust Book — RefCell<T> and the Interior Mutability Pattern
• The Rust Book — Shared-State Concurrency (Mutex/Arc)
• Sibling topics: Cell<T> (unchecked, Copy-only interior mutability) · Rc<T> / Arc<T> (shared ownership you compose these with) · Weak<T> (breaking cycles in Rc<RefCell<…>> graphs) · Smart-pointer decision guide
• Foundations: Section 05 — Ownership (the borrow rules these types relax) · Section 11 — Async (why std::sync::Mutex should not be held across .await)

---

Exercises

Exercise 1: A rate limiter that counts down through &self

Difficulty: Easy

Objective: Get comfortable mutating state behind a shared reference with RefCell.

Instructions: Implement a RateLimiter with a try_acquire(&self) -> bool method. It starts with a quota and returns true (consuming one unit) while units remain, and false once exhausted. Note that try_acquire must take &self, not &mut self.

use std::cell::RefCell;

struct RateLimiter {
    remaining: RefCell<u32>,
}

impl RateLimiter {
    fn new(quota: u32) -> Self {
        /* ??? */
    }
    fn try_acquire(&self) -> bool {
        /* ??? */
    }
}

fn main() {
    let limiter = RateLimiter::new(2);
    // Expected: true true false
    println!("{} {} {}", limiter.try_acquire(), limiter.try_acquire(), limiter.try_acquire());
}

Solution

use std::cell::RefCell;

struct RateLimiter {
    remaining: RefCell<u32>,
}

impl RateLimiter {
    fn new(quota: u32) -> Self {
        RateLimiter { remaining: RefCell::new(quota) }
    }

    fn try_acquire(&self) -> bool {
        let mut r = self.remaining.borrow_mut();
        if *r == 0 {
            false
        } else {
            *r -= 1;
            true
        }
    }
}

fn main() {
    let limiter = RateLimiter::new(2);
    println!(
        "{} {} {}",
        limiter.try_acquire(),
        limiter.try_acquire(),
        limiter.try_acquire()
    );
}

Output:

true true false

The single borrow_mut() at the top of try_acquire is dropped when the method returns, so consecutive calls never overlap and never panic.

Exercise 2: A shared event log written by two closures

Difficulty: Medium

Objective: Combine Rc (sharing) with RefCell (mutation): the single-threaded shared-mutable-state idiom.

Instructions: Build a Vec<String> event log that two independent logging closures both append to. Each closure should tag its messages with a name (e.g. "auth", "db"). After running a few events, print the whole log in order. Hint: the log’s type is Rc<RefCell<Vec<String>>>, and each closure should hold its own Rc::clone.

Solution

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

type Log = Rc<RefCell<Vec<String>>>;

fn make_logger(log: &Log, name: &'static str) -> impl Fn(&str) {
    let log = Rc::clone(log);
    move |msg: &str| log.borrow_mut().push(format!("{name}: {msg}"))
}

fn main() {
    let log: Log = Rc::new(RefCell::new(Vec::new()));
    let auth = make_logger(&log, "auth");
    let db = make_logger(&log, "db");

    auth("login ok");
    db("query 1");
    auth("logout");

    for line in log.borrow().iter() {
        println!("{line}");
    }
}

Output:

auth: login ok
db: query 1
auth: logout

Each make_logger call takes its own Rc::clone, so both closures own the same heap-allocated RefCell<Vec<String>>. The borrow_mut() inside each closure is short-lived (one push then dropped), so the appends never collide.

Exercise 3: Make a registry thread-safe

Difficulty: Hard

Objective: Convert a single-threaded interior-mutability pattern to a thread-safe one — RefCell → Mutex, Rc → Arc — and have several threads write to a shared collection.

Instructions: Spawn four threads, each of which pushes a value (id * 10) into a shared Vec<u64>. Join all threads, then print the collected values sorted ascending. You should reach for Arc<Mutex<Vec<u64>>>. (Why not Rc<RefCell<…>>? Try it and read the compiler error — it is Pitfall 2.)

Solution

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

fn main() {
    let registry: Arc<Mutex<Vec<u64>>> = Arc::new(Mutex::new(Vec::new()));
    let mut handles = Vec::new();

    for id in 0..4u64 {
        let registry = Arc::clone(&registry);
        handles.push(thread::spawn(move || {
            registry.lock().unwrap().push(id * 10);
        }));
    }

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

    let mut final_ids = registry.lock().unwrap().clone();
    final_ids.sort_unstable();
    println!("{final_ids:?}");
}

Output:

[0, 10, 20, 30]

Each thread takes its own Arc::clone (cheap reference-count bump, see Rc<T>/Arc<T>) so all four own the same Mutex. The lock() serializes the four push calls, so no update is lost. We sort at the end because thread completion order — and therefore insertion order — is nondeterministic.