The question this answers
What does the phrase "this class is thread-safe" actually promise me?
Two request handlers calling cache.get(key) and, on a miss, cache.put(key, expensiveLoad(key)) — on a map whose documentation says thread-safe.
The cache and its entries. The map internally synchronizes each operation; nothing synchronizes the get-then-put sequence, and nothing in the type system indicates that difference.
At most one expensive load runs per key, and every caller that receives a value receives the value that is actually stored in the cache.
Synchronization exists to preserve this sentence. If a schedule can make it false, the code is wrong no matter which primitive it uses.
Thread safety is a contract, not an implementation
"Thread-safe" is a statement about a specification: this type behaves correctly when used concurrently in these documented ways. It says nothing about how — an immutable type is thread-safe with no locks at all, a value confined to one thread is thread-safe by never being shared, and a lock-free queue is thread-safe with atomics and no mutual exclusion anywhere. Equating thread safety with locking gets both directions wrong: it implies immutable types need locks, and it implies anything with a lock is safe.
The useful mental model is a ladder of guarantees, and the documentation should tell you which rung a type sits on. Immutable: safe under all use with no coordination. Thread-safe: every operation is atomic and the object maintains its own invariants under concurrent calls. Conditionally thread-safe: safe per call, but some sequences require external synchronization — this is the rung almost everything actually sits on, and the one most documentation fails to say. Not thread-safe: safe only under external synchronization or confinement. Thread-hostile: unsafe even with external synchronization, usually because it mutates global state.
The practical consequence is that "is this thread-safe?" is not answerable in general. The answerable question is "which of my usages does this type's contract cover?" — and the get-then-put sequence is the canonical usage it does not.
| Level | Promise | What you still must do | Typical example |
|---|---|---|---|
| Immutable | Correct under all concurrent use, with no coordination whatsoever | Publish the reference safely — that is all | A frozen config object, a value type |
| Thread-safe | Every individual operation is atomic; the object's own invariants hold | Synchronize any multi-call sequence you depend on | A concurrent map, an atomic counter |
| Conditionally thread-safe | Individual operations are safe; documented sequences are not | Read the documentation and lock the sequences it names | A collection whose iterator requires external locking |
| Not thread-safe | Nothing under concurrent use | Confine to one thread, or lock every access | An ordinary array, list or dictionary |
| Thread-hostile | Unsafe even when you synchronize your own access | Avoid, or isolate it in a single dedicated thread or process | Something mutating a process-wide global such as a locale or an environment variable |
The trap: safe calls, unsafe sequence
Here is the entire misconception in one line of code: if (!map.containsKey(k)) map.put(k, compute(k)). Both calls are atomic. The sequence is not. Two threads can both observe the key as absent, both compute, and both put — and the guarantee the map gave you is intact the whole time, because it promised per-call atomicity and delivered exactly that.
This is a check-then-act race, and the invariant it breaks is an *application* invariant: "at most one expensive load per key". The map has no idea that invariant exists, and no amount of internal locking could protect it. Only the caller knows the sequence is meant to be indivisible, so only the caller can make it so — with a lock over the sequence, or by using a single compound operation the type provides for exactly this reason (computeIfAbsent, putIfAbsent, SETNX, an upsert).
The habit worth building: when you use a thread-safe type, identify every sequence of two or more calls whose intermediate state matters, and treat each one as an unprotected critical section until proven otherwise. Iteration is the other classic — a snapshot iterator gives you a consistent view, a weakly consistent one gives you neither the old nor the new state reliably, and a fail-fast one throws.
| # | Handler 1 | Handler 2 | State |
|---|---|---|---|
| 1 | cache.get("user:9") -> miss [atomic call] | · | cache=empty |
| 2 | · | cache.get("user:9") -> miss [atomic call] | cache=empty |
| 3 | expensiveLoad("user:9") — 400 ms, one DB query | · | cache=empty queries=1 |
| 4 | · | expensiveLoad("user:9") — 400 ms, second DB query | cache=empty queries=2 ✕ Two loads for one key. Under a cache stampede this is 300 identical queries, and the map's thread-safety guarantee is not violated at any point. |
| 5 | cache.put("user:9", vA) [atomic call] | · | cache=vA queries=2 |
| 6 | · | cache.put("user:9", vB) [atomic call] | cache=vB queries=2 |
| 7 | --- fixed: one compound operation --- | · | cache=empty queries=0 |
| 8 | cache.computeIfAbsent("user:9", load) [atomic] | · | cache=vA queries=1 |
| 9 | · | cache.computeIfAbsent("user:9", load) -> vA [atomic] | cache=vA queries=1 |
Documenting it, and what to demand of others
Because thread safety is a contract, undocumented thread safety is not thread safety — it is an implementation detail that will change in a minor version. A type that is safe today because it happens to hold a lock, with nothing written down, is a type whose maintainer may replace that lock next quarter and break you.
A usable statement names four things: which operations are atomic, which sequences are not and need external synchronization, what iteration or snapshot semantics apply, and what the object promises about visibility of writes made by other threads. "Thread-safe" alone answers none of those, and is the reason this misconception is so durable.
When you write the safe wrapper yourself, the same rules apply and one extra: do not let a reference escape. A class that synchronizes every method and then returns its internal list has published mutable state that no lock protects, and the caller will iterate it outside the lock. Return a copy, an immutable view, or nothing. See Safe Publication: Handing Over a Finished Object and Shared Mutable State.
1class Registry:2 def __init__(self):3 self._lock = threading.Lock()4 self._items: list[Item] = []5 6 def add(self, item):7 with self._lock:8 self._items.append(item)9 10 def items(self):11 with self._lock:12 return self._items # the reference escapes the lock13 14# Caller iterates outside the lock while another thread appends.15for it in registry.items(): # RuntimeError, or a torn view16 ...1class Registry:2 """Thread-safe. add() and snapshot() are individually atomic.3 A sequence of calls is NOT atomic: use with_lock() if you need one.4 snapshot() returns an immutable copy taken under the lock."""5 6 def __init__(self):7 self._lock = threading.Lock()8 self._items: list[Item] = []9 10 def add(self, item):11 with self._lock:12 self._items.append(item)13 14 def snapshot(self) -> tuple[Item, ...]:15 with self._lock:16 return tuple(self._items) # a copy, not the internal list17 18 @contextlib.contextmanager19 def with_lock(self): # for sequences the caller needs atomic20 with self._lock:21 yield self._itemsThe first class is fully locked and fully broken: the lock is released before the caller iterates, and the caller is iterating the live list. The second returns a snapshot taken under the lock, and — crucially — documents that multi-call sequences are the caller's problem, plus provides the tool to solve them.
Key points
- Thread safety is a documented contract about permitted concurrent usage, not the presence of locks.
- Immutable types and confined types are thread-safe with no synchronization at all; lock-free types are thread-safe with no mutual exclusion.
- A thread-safe method does not make a sequence of calls atomic. Check-then-act across two safe calls is a race.
- Most types are conditionally thread-safe, and the condition is usually undocumented — treat every multi-call sequence as unprotected until proven otherwise.
- A class that synchronizes every method and then returns its internal collection has published unprotected mutable state.
The loop, answered
Every field is required, which is why no lesson here can recommend concurrency without naming the interleaving that breaks it, the complexity it adds, and the simpler thing to consider first.
- • Read the type's documentation for which operations are atomic and what it says about sequences, iteration and visibility.
- • List your usages of the type, and mark every place you make two or more calls whose intermediate state matters.
- • For each such sequence, either find a compound operation the type provides, or wrap the sequence in your own lock.
- • Check whether any method hands out a reference to internal mutable state; if so, the type's safety ends at that return statement.
- • When writing a safe type, state the contract explicitly: atomic operations, non-atomic sequences, iteration semantics and visibility.
- • Check-then-act: H1 sees key absent; H2 sees key absent; H1 computes and puts; H2 computes and puts — two expensive loads, and the caller of H1 holds a value the cache no longer stores.
- • Compound operation: H1 calls computeIfAbsent and the type holds its own lock across check and insert; H2 blocks inside the call and receives H1's value — one load, one value.
- • Escaped reference: H1 calls items() which returns the internal list under a lock and then releases it; H1 iterates while H2 appends — the iterator sees a structurally modified collection and throws, or silently skips.
- • Compound increment: H1 reads counter (7); H2 reads counter (7); H1 writes 8; H2 writes 8 — the field access may be atomic and the read-modify-write is not. See The Atomicity Illusion.
- • Two safe objects, one invariant: H1 debits accountA atomically, is preempted, and H2 reads the total across both accounts before H1 credits accountB — each object is thread-safe and the cross-object invariant is broken.
- • Visibility: H1 mutates an object stored in a thread-safe map without going through the map; H2 reads it from the map and may see the old field values — the map guarded the reference, never the referent.
- • A thread-safe type guarantees each documented operation is atomic and that its own internal invariants hold under concurrent calls.
- • It guarantees the visibility of writes made through its own operations to subsequent callers of those operations.
- • It does NOT guarantee atomicity across two or more calls, which is the single most common misuse.
- • It does NOT guarantee your application invariants, which it has never been told about.
- • It does NOT guarantee anything about objects it stores. A thread-safe map holding mutable values protects the mapping, not the values.
- • It does NOT guarantee iteration is consistent unless it says so — fail-fast, weakly consistent and snapshot are three different and incompatible behaviours.
- • It does NOT guarantee anything after a reference to internal state escapes.
- • It does NOT compose: two thread-safe objects give you no guarantee about an invariant spanning both.
- • A fully synchronized type serializes every operation, so under high concurrency it is a global lock with a nicer name.
- • Fine-grained or striped locking preserves concurrency across keys, and contention concentrates on hot keys rather than on the type.
- • Lock-free thread-safe types move contention to cache lines and CAS retries rather than to waiting, which changes the metric you watch, not whether contention exists.
- • Caller-side locking around sequences reintroduces coarse serialization on top of a fine-grained type, which is correct and frequently the reason a concurrent collection performs no better than a plain locked one.
- • Snapshot iteration trades contention for allocation: no lock held while iterating, one copy per snapshot.
- • Check-then-act race across two individually safe calls — duplicate work, lost updates, or two callers disagreeing about the stored value.
- • Lost update from a read-modify-write built out of atomic reads and atomic writes.
- • ConcurrentModification or torn iteration when a returned internal collection is iterated outside the lock.
- • Cross-object invariant violation, where each object is safe and the relationship between them is not.
- • Stale reads of a mutable object retrieved from a thread-safe container and then mutated outside it.
- • Deadlock from caller-side locking around a type that also locks internally, when the two orders disagree.
- • A silent regression when a dependency's undocumented internal locking is removed in a minor version.
- • Thread-safe types genuinely help when the usage is single-call — a counter, a registry of independent entries, a cache with compound operations.
- • They help by encapsulating the invariant with the data, so no caller can forget the lock for a single operation.
- • Compound operations (computeIfAbsent, putIfAbsent, atomic upserts) help exactly where the trap is, and are the correct first reach.
- • Explicit documentation of the contract helps most of all, because it converts a runtime race into a review-time question.
- • When the label is treated as a guarantee that any usage is safe, which is where the check-then-act bugs come from.
- • When a fully synchronized type is used at high concurrency and becomes a serialization point that no metric attributes to it.
- • When a thread-safe container is used to hold mutable objects and the mutation happens outside the container.
- • When caller-side locking is layered over internal locking without a lock order, which turns a race into a deadlock.
- • Count of expensive operations per key against the number of distinct keys — the direct detector for the duplicate-work failure.
- • Lock wait time inside the type, if it exposes it; a "concurrent" collection with high internal wait is not buying you concurrency.
- • Duplicate-work or cache-stampede counters, which surface the check-then-act failure without needing to reproduce the schedule.
- • A race detector or thread sanitizer run against the sequence, which will flag unsynchronized access to the referents even when the container is safe. See Race Detectors: What They Find, and What They Structurally Cannot.
- • Static review count: how many two-call sequences exist against each shared type. This is a code-review metric and it finds more bugs here than any runtime tool.
- • The caller must now reason about which sequences need protection, which is invisible in the code and only present in documentation.
- • Layering caller locks over internal locks introduces an ordering obligation between locks you own and locks you do not.
- • Writing the contract down means committing to it across versions, which is a real maintenance burden and the reason so few libraries do it.
- • Snapshot semantics have to be chosen and stated: copying costs allocation, weak consistency costs predictability, fail-fast costs availability.
- • Immutability, which is thread-safe at every rung with no contract to read. See Immutability as a Concurrency Strategy.
- • Confinement: keep the object in one thread or one task and pass messages, so concurrency never touches it. See Message Passing.
- • A compound operation provided by the type, which converts the unsafe sequence into a single guaranteed one.
- • A single owning actor per entity, making sequences atomic by construction. See The Actor Model.
- • An explicit lock owned by your code over your invariant, which is honest: the invariant is yours, so the lock should be too. See Finding the Critical Section.
if (balance >= 100) withdraw(100) — drive it until it overdraws
balance = 100
withdraw(amount): # both tasks run this concurrently
b = read(balance) # 1
if b >= amount: # 2 <- decided on a value that may already be stale
debit(amount) # 3| # | Withdrawal A (100) | Withdrawal B (100) | State |
|---|---|---|---|
| 1 | rA ← read balance | · | balance=100 paidOut=0 |
| 2 | if rA >= 100 | · | balance=100 paidOut=0 |
| 3 | debit 100 | · | balance=0 paidOut=100 |
Two increments, twenty schedules: find the one that loses an update
| # | Task A — counter++ | Task B — counter++ | State |
|---|---|---|---|
| 1 | rA ← counter | · | counter=0 rA=0 rB=0 |
| 2 | rA ← rA + 1 | · | counter=0 rA=1 rB=0 |
| 3 | counter ← rA | · | counter=1 rA=1 rB=0 |
| 4 | · | rB ← counter | counter=1 rA=1 rB=1 |
| 5 | · | rB ← rB + 1 | counter=1 rA=1 rB=2 |
| 6 | · | counter ← rB | counter=2 rA=1 rB=2 |
What people believe, and what is true
Thread-safe means it has locks.
It means the documented contract permits concurrent use. Immutable types have no locks and are maximally thread-safe; confined types are safe by never being shared; lock-free types are safe with atomics. Locks are one implementation of the contract, not the contract.
If every method is synchronized, the class is safe.
Not if a method returns internal mutable state, and not for any sequence of calls. A fully synchronized class that returns its internal list is unsafe in the most ordinary usage there is — iterating it.
Using a concurrent collection removes the need to think about synchronization.
It removes it for single operations and relocates it to sequences. The bug moves from inside the collection to the three lines around it, where no library can help you.
If the type is thread-safe, the objects it holds are protected too.
The container guards the mapping. Mutating a stored object goes straight past the container's lock, and other threads may see stale or torn field values.
Go deeper
Overview
Thread-safe means the documentation says concurrent use is correct, in the ways it describes. It does not mean any usage at all is correct, and it does not imply locks.
Practical
Find every place you call two methods in a row and depend on nothing happening in between. Each one is an unprotected critical section. Use a compound operation, or take your own lock over the sequence.
Advanced
Write the contract for types you own: atomic operations, non-atomic sequences, iteration semantics, visibility. Never let a reference to internal mutable state escape a synchronized method.
Internals
Thread safety has two halves — mutual exclusion and visibility. A type that serializes operations but does not establish the right happens-before edges can still let a reader observe a stale value. This is why the contract must speak about visibility and not only about atomicity. See Happens-Before: The Edge That Makes a Write Visible.