m03-mutability

name	m03-mutability
description	CRITICAL: Use for mutability issues. Triggers: E0596, E0499, E0502, cannot borrow as mutable, already borrowed as immutable, mut, &mut, interior mutability, Cell, RefCell, Mutex, RwLock, 可变性, 内部可变性, 借用冲突
user-invocable	false

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:

1. Is mutation necessary?

   • Maybe transform → return new value
   • Maybe builder → construct immutably

2. Who controls mutation?

   • External caller → &mut T
   • Internal logic → interior mutability
   • Concurrent access → synchronized mutability

3. 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> (.get()/.set())
    ↓ T: !Copy → Cell<T> (.replace()/.take()) or RefCell<T>
    ↓ Initialize once → OnceLock (thread-safe) or OnceCell (single-thread)

"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	Any T; .get() for Copy, .replace()/.take() for non-Copy
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> (.get()/.set())
T: !Copy, single-thread	Cell<T> (.replace()/.take()) or 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 (but in async/tokio, Mutex is often required because RefCell is !Send)
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