Thread Safety and Races in Python

### What the GIL actually promises The Global Interpreter Lock is a single interpreter-wide mutex that a thread must hold to run Python bytecode in CPython's default build. It exists to protect the interpreter's own data — reference counts, container internals, the allocator — not the invariants of your program. The common mis-reading is "only one thread runs at a time, therefore my code is thread-safe". The unit of serialization is a *bytecode instruction*, not a *line of source*, and almost every interesting update spans several instructions. ### Decomposing the increment On CPython 3.14, a module-level `counter += 1` inside a loop disassembles to this: ``` LOAD_GLOBAL 2 (counter) LOAD_SMALL_INT 1 BINARY_OP 13 (+=) STORE_GLOBAL 1 (counter) JUMP_BACKWARD 18 ``` The value is read by `LOAD_GLOBAL` and published by `STORE_GLOBAL`, and everything between those two instructions is a window. If another thread runs in that window, the interleaving ``` thread A: load counter -> 10 thread B: load counter -> 10 thread B: add, store -> 11 thread A: add, store -> 11 ``` is legal, and two increments advance the counter by one. That is the **lost update**: a read-modify-write where the value read is stale by the time it is written. ### Why the result is a wrong number, not a crash Under the GIL you cannot get a torn integer, corrupt the dict holding the global, or break a reference count — those are exactly what the GIL protects. That is what makes this bug dangerous: it produces a plausible but wrong number, silently, only under load. A counter of processed items reads 998,412 instead of 1,000,000, and nobody notices until a reconciliation job disagrees. ### Why the textbook demo may print the exact total on 3.14 Run the classic demo — four threads, a few hundred thousand `counter += 1` iterations each — on CPython 3.14 and you will very likely see the exact expected total, even with sixteen threads and sixteen million increments. This surprises people who learned the example a decade ago, and the explanation matters more than the folklore. CPython does not test for a pending thread switch after every instruction; it checks at a few designated points, chiefly the back edge of a loop and the `RESUME` at the top of a called function. In the disassembly above there is no such check between `LOAD_GLOBAL` and `STORE_GLOBAL`: the only check in the loop body sits at `JUMP_BACKWARD`, *after* the store. So the switch lands between iterations, not inside the statement, and no update is lost. The moment anything runs Python code between the read and the write, the check reappears inside the window and the updates vanish: ```python def one(): return 1 counter = counter + one() # the call is a switch point, mid-window ``` Four threads doing that lose roughly half their increments. This is the crucial lesson to carry away: **the demo printing an exact total proves nothing about safety.** The window's exposure depends on the exact shape of the code — a function call, a property, a `__add__` on a user class, a logging call, a comparison against an object with a Python-level `__eq__`. A refactor that adds any of those turns a correct-looking loop into a racy one, with no change to the line you are staring at. ### Reproducing it deliberately ```python import sys, threading sys.setswitchinterval(1e-6) # switch more often, to widen the demo counter = 0 def one(): return 1 def bump(n): global counter for _ in range(n): counter = counter + one() threads = [threading.Thread(target=bump, args=(300_000,)) for _ in range(4)] for t in threads: t.start() for t in threads: t.join() print(counter, "of", 1_200_000) ``` `sys.setswitchinterval` lowers the interval at which a waiting thread requests the GIL, so the switch points are hit far more often; it does not create the race, it only makes it obvious. ### A nuance worth knowing Not every `+=` is equally exposed. `shared_list += [item]` calls the list's in-place concatenation, which mutates the existing list and returns *the same object*; the store that follows merely rebinds the name to the object it already held, so nothing is lost. `n += 1` on an `int` is different because integers are immutable: the addition produces a *new* object and the store is the only thing that publishes it, so a stale read becomes a stale write. The rule is not "avoid `+=`" but "any update whose new value depends on a previously read value must be serialized". ### The three real fixes 1. **A lock around the whole read-modify-write.** Wrap the increment in `with counter_lock:` so load, add and store form one critical section. Correct and obvious; the cost is contention when the counter is hot. 2. **Message passing.** Workers push results into a `queue.Queue` and one consumer owns the total, so there is no shared mutable state left to race on. 3. **Confinement.** Give each thread a plain local counter and sum the per-thread values after `join()`. Usually the fastest and the easiest to reason about: the shared write happens once per thread, after the work is done. ### What "thread-safe" means here A workable definition: an operation is thread-safe if no interleaving of other threads can produce a result that no sequential execution could produce. Under that definition the GIL buys almost nothing at the application level. Interviewers ask this question because a candidate who believes the GIL confers thread safety will write racy counters, racy caches and racy check-then-act code — and, on 3.14, will point at a demo that printed the right number as proof they were fine. ### Version note This is CPython 3.14's default build. The free-threaded build became officially supported in 3.14 (PEP 779); with no GIL the threads genuinely run at once, so the same read-modify-write loses updates without needing any switch point in the window at all.