M03 Mutability Agent Skill

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 |