Skip to content

T0004 static-interior-mutability

Rule: A static with interior mutability has one owner, or a reason why a global lock is right.

Code T0004 (stable, never reused)
Id static-interior-mutability
Category state
Source spirit_level
Fix by hand

Level per tier

Tier Level Reason
small warn every piece of mutable state has one owner; a global lock says why
small-workspace warn every piece of mutable state has one owner; a global lock says why
medium warn every piece of mutable state has one owner; a global lock says why
big deny every piece of mutable state has one owner; a global lock says why on the item
ai off
embedded off
ui off
egui off
units-strict off
units-paranoid off

Parameters

Name Type Default Meaning
types list of strings ["Mutex", "RwLock", "RefCell", "Cell", "UnsafeCell", "OnceCell", "DashMap", "ArcSwap", "ReentrantMutex"] type names that make a static mutable
atomics boolean false also report statics of atomic types (counters and flags are usually fine)

Why

A static with interior mutability is shared mutable state that every caller in the process reaches. Each one brings a lock order, a poison story, a risk of being held across I/O, and contention on a hot path. In tpm's crates about 1,700 hits of Mutex|RwLock|OnceLock|... held some 200 real pieces of global state; most of the CLI's were a Mutex that only existed to satisfy static in a single-threaded run.

The rule: every piece of mutable state has one owner. Pick the first shape that fits:

Shape When
V, by value state of one request, run or connection: a local or a context passed by &mut
A, owner task outlives a request, several tasks change it: one task owns it, others send it messages
S, swapped snapshot read far more than written: ArcSwap / watch, readers never block
E, the event log shared across machines: a fold over the stream
O, set once OnceLock / LazyLock of something without interior mutability: not reported
K, a lock that is right a tiny section with no I/O, a callback API that demands Sync, a per-thread buffer: with the reason

Example

// reported
static SEEN: Mutex<Vec<String>> = Mutex::new(Vec::new());

// kept on purpose, with the reason
// spirit-level: allow(static-interior-mutability) K: the panic hook's ring; one writer per thread, dumped on exit
static RING: Mutex<Ring> = Mutex::new(Ring::new());

How to fix

Move the state to its owner (see the table). When a global lock is the right tool, write the reason in a waiver on the item. The parameter types lists the type names that count; atomics = true also reports atomic statics.

Configure

[lints.static-interior-mutability]
level = "deny"
types = ["Mutex", "RwLock", "RefCell", "Cell", "UnsafeCell", "OnceCell", "DashMap", "ArcSwap", "ReentrantMutex"]
atomics = false
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(static-interior-mutability) <reason> (waivers); the code works there too, as in [lints.T0004].