M03 Mutability

by actionbook5c40d3ad7851No license1.5K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 6 weeks ago

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, 可变性, 内部可变性, 借用冲突

Instructions onlySoftware Development Learning & Education

AI-generated overview

Reference guide for Rust mutability errors, borrow conflicts, and interior mutability choices.

What it does: This skill is an instructional reference for Rust mutability problems. It maps compiler errors such as E0596, E0499 and E0502 to design questions, explains borrow rules, and provides decision tables for choosing between &mut T, Cell, RefCell, Mutex, RwLock and atomics. It also lists anti-patterns and points to related skills for resource, concurrency and domain design topics.
When to use it: Use it when diagnosing Rust borrow-checker errors about mutable or immutable borrowing, or when deciding how to allow mutation through shared references. It is also meant for choosing thread-safe versus single-threaded interior mutability.
Requirements: No tools, packages or credentials; it is instructions only and ships no scripts.

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

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

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

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

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

Source and attribution

Source:actionbook/rust-skillsinskills/m03-mutabilityat commit5c40d3a

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

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

When	See
Smart pointer choice	m02-resource
Thread safety	m07-concurrency
Data structure design	m09-domain
Anti-patterns	m15-anti-pattern

M03 Mutability

Mutability

Core Question

Error → Design Question

Thinking Prompt

Trace Up ↑

Trace Down ↓

Borrow Rules

Quick Reference

Error Code Reference

Interior Mutability Decision

Anti-Patterns

Related Skills

Source and attribution

More from actionbook/rust-skills

Rust Trait Explorer

Rust Symbol Analyzer

Rust Skill Creator

Rust Router

Rust Refactor Helper

Rust Daily

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices