rust-mutability_skill

Overview

This skill is an interior mutability expert for Rust, explaining patterns like Cell, RefCell, Mutex, and RwLock and diagnosing common borrow errors (E0596, E0499, E0502). It guides strategy selection for single-threaded and multi-threaded contexts and shows practical fixes for borrow conflicts and lock misuse. The focus is on correct, performant, and safe mutation in real-world Rust codebases.

How this skill works

The skill inspects code patterns and runtime symptoms to recommend the right mutability primitive or redesign. It maps symptoms (compile errors, runtime RefCell panics, deadlocks) to concrete fixes such as splitting structs, minimizing borrow scopes, using try_borrow, or switching to atomic types. It also prescribes trade-offs and profiling steps for lock-heavy paths.

When to use it

• Default: use &mut T when caller controls mutability and single-threaded ownership suffices.
• Use Cell<T> for interior mutation of small Copy types with &self methods.
• Use RefCell<T> when you need &mut from &self in single-threaded code, accepting runtime borrow checks.
• Use Mutex<T> for interior mutability across threads when writes are frequent or simple to serialize.
• Use RwLock<T> when reads greatly outnumber writes and you need concurrent readers.

Best practices

• Prefer external mutability (&mut) by default; add interior mutability only when caller control is impractical.
• Keep lock scopes minimal and never hold a MutexGuard or RwLockWriteGuard across await points in async code.
• Use Atomic types for simple counters/flags to avoid unnecessary locking.
• When facing E0499/E0502, consider splitting a struct into independent fields or using interior mutability for the conflicting parts.
• Use try_borrow/try_borrow_mut with RefCell to avoid panics and handle borrowing failures gracefully.

Example use cases

• A cached lookup object that needs mutable inserts from &self in a single-threaded context → RefCell<HashMap<..>>.
• A global configuration object with many concurrent readers and occasional writes → RwLock<HashMap<..>>.
• A shared counter across threads where atomic increments suffice → AtomicU64 with fetch_add.
• A small mutable flag inside an immutable API object → Cell<bool> for O(1) interior mutation.
• Refactoring a struct causing E0499 by splitting heavy fields so independent mutable borrows no longer conflict.