Mutability

Layer 1: Language Mechanics

Core Question

Why does this data need to change, and who can change it?

Before adding interior mutability, understand:

• Is mutation essential or accidental complexity?

• Who should control mutation?

• Is the mutation pattern safe?

Error → Design Question

Error

Don't Just Say

Ask Instead

E0596

"Add mut"

Should this really be mutable?

E0499

"Split borrows"

Is the data structure right?

E0502

"Separate scopes"

Why do we need both borrows?

RefCell panic

"Use try_borrow"

Is runtime check appropriate?

Thinking Prompt

Before adding mutability:

-

Is mutation necessary?

• Maybe transform → return new value

• Maybe builder → construct immutably

-

Who controls mutation?

• External caller → &mut T

• Internal logic → interior mutability

• Concurrent access → synchronized mutability

-

What's the thread context?

• Single-thread → Cell/RefCell

• Multi-thread → Mutex/RwLock/Atomic

Trace Up ↑

When mutability conflicts persist:

E0499/E0502 (borrow conflicts)

    ↑ Ask: Is the data structure designed correctly?

    ↑ Check: m09-domain (should data be split?)

    ↑ Check: m07-concurrency (is async involved?)

Persistent Error

Trace To

Question

Repeated borrow conflicts

m09-domain

Should data be restructured?

RefCell in async

m07-concurrency

Is Send/Sync needed?

Mutex deadlocks

m07-concurrency

Is the lock design right?

Trace Down ↓

From design to implementation:

"Need mutable access from &self"

    ↓ T: Copy → Cell<T>

    ↓ T: !Copy → RefCell<T>

"Need thread-safe mutation"

    ↓ Simple counters → AtomicXxx

    ↓ Complex data → Mutex<T> or RwLock<T>

"Need shared mutable state"

    ↓ Single-thread: Rc<RefCell<T>>

    ↓ Multi-thread: Arc<Mutex<T>>

Borrow Rules

At any time, you can have EITHER:

├─ Multiple &T (immutable borrows)

└─ OR one &mut T (mutable borrow)

Never both simultaneously.

Quick Reference

Pattern

Thread-Safe

Runtime Cost

Use When

&mut T

N/A

Zero

Exclusive mutable access

Cell<T>

No

Zero

Copy types, no refs needed

RefCell<T>

No

Runtime check

Non-Copy, need runtime borrow

Mutex<T>

Yes

Lock contention

Thread-safe mutation

RwLock<T>

Yes

Lock contention

Many readers, few writers

Atomic*

Yes

Minimal

Simple types (bool, usize)

Error Code Reference

Error

Cause

Quick Fix

E0596

Borrowing immutable as mutable

Add mut or redesign

E0499

Multiple mutable borrows

Restructure code flow

E0502

&mut while & exists

Separate borrow scopes

Interior Mutability Decision

Scenario

Choose

T: Copy, single-thread

Cell<T>

T: !Copy, single-thread

RefCell<T>

T: Copy, multi-thread

AtomicXxx

T: !Copy, multi-thread

Mutex<T> or RwLock<T>

Read-heavy, multi-thread

RwLock<T>

Simple flags/counters

AtomicBool, AtomicUsize

Anti-Patterns

Anti-Pattern

Why Bad

Better

RefCell everywhere

Runtime panics

Clear ownership design

Mutex for single-thread

Unnecessary overhead

RefCell

Ignore RefCell panic

Hard to debug

Handle or restructure

Lock inside hot loop

Performance killer

Batch operations

Related Skills

When

See

Smart pointer choice

m02-resource

Thread safety

m07-concurrency

Data structure design

m09-domain

Anti-patterns

m15-anti-pattern