m03-mutability

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 | 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? |

---

Before adding mutability:

1. Is mutation necessary?

- Maybe transform → return new value

- Maybe builder → construct immutably

1. Who controls mutation?

- External caller → &mut T

- Internal logic → interior mutability

- Concurrent access → synchronized mutability

1. What's the thread context?

- Single-thread → Cell/RefCell

- Multi-thread → Mutex/RwLock/Atomic

---

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? |

---

From design to implementation:

```

"Need mutable access from &self"

↓ T: Copy → Cell

↓ T: !Copy → RefCell

"Need thread-safe mutation"

↓ Simple counters → AtomicXxx

↓ Complex data → Mutex or RwLock

"Need shared mutable state"

↓ Single-thread: Rc>

↓ Multi-thread: Arc>

```

---

```

At any time, you can have EITHER:

├─ Multiple &T (immutable borrows)

└─ OR one &mut T (mutable borrow)

Never both simultaneously.

```

| Pattern | Thread-Safe | Runtime Cost | Use When |

|---------|-------------|--------------|----------|

| &mut T | N/A | Zero | Exclusive mutable access |

| Cell | No | Zero | Copy types, no refs needed |

| RefCell | No | Runtime check | Non-Copy, need runtime borrow |

| Mutex | Yes | Lock contention | Thread-safe mutation |

| RwLock | Yes | Lock contention | Many readers, few writers |

| Atomic* | Yes | Minimal | Simple types (bool, usize) |

| 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 |

---

| Scenario | Choose |

|----------|--------|

| T: Copy, single-thread | Cell |

| T: !Copy, single-thread | RefCell |

| T: Copy, multi-thread | AtomicXxx |

| T: !Copy, multi-thread | Mutex or RwLock |

| Read-heavy, multi-thread | RwLock |

| Simple flags/counters | AtomicBool, AtomicUsize |

---

| 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 |

---

| When | See |

|------|-----|

| Smart pointer choice | m02-resource |

| Thread safety | m07-concurrency |

| Data structure design | m09-domain |

| Anti-patterns | m15-anti-pattern |