Grokking Concurrency in Python
Vote

0% completed

​

What the GIL Protects

What the GIL Is For

One Line, Several Steps

Four Shared Updates, Measured

What You Must Protect Yourself

In Production

Key Takeaways

Practice Questions

What the GIL Protects
What the GIL Protects

The global interpreter lock makes two promises to a threaded program. CPython's counts of the references to each object are never corrupted, and a built-in object such as a list is never left half changed. It makes no promise about the steps in your own code, so counter += 1 can still lose an update.

Many engineers believe that the GIL makes Python code thread-safe, meaning safe to run from several threads at once. Harvest's counters show that it does not.

What the GIL Is For

A reference count is a number stored in every Python object that records how many references point to it; CPython frees the object when the count reaches zero. Every assignment and function call changes reference counts. CPython also has its own memory allocator, and built-in types keep internal structures, such as the table inside a dict.

If two threads changed one reference count at the same moment, one change could be lost, and CPython could free an object that is still in use. The GIL stops this: a thread must hold it to run Python code, so only one thread at a time can touch this internal state.

The GIL protects the interpreter's own state, not the meaning of your data. It does not guarantee that a series of steps in your code runs without another thread running in between. In one measurement below, four threads lost 60 percent of their updates to a shared total with the GIL on for the whole run.

What the GIL guards
What the GIL guards

One Line, Several Steps

Bytecode is the list of small instructions that CPython's interpreter executes, one instruction at a time; CPython compiles each function into bytecode before running it. The standard library module dis prints that list. This function marks one page as indexed:

def page_done(): global pages_indexed pages_indexed += 1

The demos in this lesson ran on Python 3.15.2 on a cloud virtual machine running Linux with 2 virtual CPUs (one physical core). Here is the bytecode of page_done:

Output:

$ python3.15 show_bytecode.py 7 RESUME 0 9 LOAD_GLOBAL 0 (pages_indexed) LOAD_SMALL_INT 1 BINARY_OP 13 (+=) STORE_GLOBAL 0 (pages_indexed) LOAD_COMMON_CONSTANT 7 (None) RETURN_VALUE

The single line became four instructions: read the value, load 1, add, and write the result back. An operation is atomic when no other thread can observe it half done or run in the middle of it. The Python documentation treats each bytecode instruction as atomic on the standard build, but the line as a whole is not, because another thread can run between its instructions.

A lost update happens when two threads read the same old value, each computes a new value from it, and the second write replaces the first. Thread A reads 41 and is switched out. Thread B reads 41 and stores 42. Thread A resumes and also stores 42, so two updates raised the total by one.

Two threads, one update lost
Two threads, one update lost

Four Shared Updates, Measured

The program counters.py starts four threads and runs four kinds of shared update, 1,000,000 times per thread. The first is pages_indexed += 1. The second adds a word count computed by a small Python function:

def count_words(text): return len(text.split()) # ... def add_words(): global words_seen for _ in range(ROUNDS): words_seen += count_words(LINE)

The sample line, LINE, has 8 words. The third update is the second one with a lock around it, and the fourth appends to a shared list. On the standard build, the first of three runs printed this:

Output:

$ python3.15 counters.py # run 1 GIL on, 4 threads, 1,000,000 updates each pages_indexed += 1 4,000,000 of 4,000,000 lost 0 words_seen += count_words(LINE) 12,814,208 of 32,000,000 lost 19,185,792 the same, holding a lock 32,000,000 of 32,000,000 lost 0 fingerprints.append(n) 4,000,000 of 4,000,000 lost 0

The update with a function call lost between 60 and 69 percent of its updates across the three runs. Current CPython checks whether to switch threads only at certain instructions, such as a function call or the jump back to the top of a loop. The call to count_words is one of those points, and it comes after the read of words_seen. A thread switched out there holds a stale value while the other threads add many updates, and its later write replaces all of them.

The plain increment lost nothing in all three runs, but it was not safe. No switch point falls inside it in this interpreter, which is a detail of the implementation, not a promise. The Python documentation's list of operations that are not thread-safe includes i = i+1, and the free-threaded build shows the result:

Output:

$ python3.15t counters.py # run 1 GIL off, 4 threads, 1,000,000 updates each pages_indexed += 1 1,599,047 of 4,000,000 lost 2,400,953 words_seen += count_words(LINE) 10,266,360 of 32,000,000 lost 21,733,640 the same, holding a lock 32,000,000 of 32,000,000 lost 0 fingerprints.append(n) 4,000,000 of 4,000,000 lost 0

Here the plain increment lost 58 to 60 percent across the three runs, because two threads ran its instructions on two virtual CPUs at the same instant.

Two lines stayed correct on both builds. The lock made each read, add, and write a single unit. Each list.append is one operation on the list's own state, which the GIL keeps consistent on the standard build. The free-threaded build uses internal locks on built-in types instead, as its documentation describes.

What You Must Protect Yourself

A single operation on a built-in object leaves that object consistent. A sequence of operations is your responsibility. These updates are sequences, even when they fit on one line:

CodeStepsSafe without a lock?
fingerprints.append(n)One operation on the listYes, the list stays consistent
pages_indexed += 1Read, add, writeNo, even when a test does not lose an update
total += f(x)Read, call, add, writeNo, and the call makes losses likely
counts[key] = counts.get(key, 0) + 1Read, add, writeNo

A lock is the general repair. Another is to avoid sharing: each thread keeps its own total, and the program adds them at the end.

In Production

Lost updates rarely raise an error; they appear as numbers that are slightly wrong.

What you seeWhat it meansHow to check
A counter in a threaded service is lower than the number of events in the logsConcurrent read, modify, and write updates overwrite each otherSearch for += and x[k] = x[k] ... on objects shared between threads
A test of shared state passes on your laptop but fails on the free-threaded build or a busier machineThe code depended on where one interpreter version switches threadsRun the test on python3.15t with several threads
A reviewer says "the GIL makes this safe"The GIL makes single operations safe, not sequencesRun dis on the line; separate read and write instructions mean another thread can run between them

Key Takeaways

  • The GIL protects CPython's own state, such as reference counts, not the correctness of your data.
  • pages_indexed += 1 compiles to separate read, add, and write instructions, and another thread can run between them.
  • With the GIL on, an update with a function call between its read and its write lost 60 to 69 percent of its updates.
  • The plain increment lost nothing on the standard build and 58 to 60 percent on the free-threaded build, so a passing test is not proof of safety.
  • Protect every shared read, modify, and write with a lock, or avoid sharing the value.

So far, the GIL has been a lock that threads hold while they run Python code. The next lesson, When the GIL Is Released, measures when a thread gives it up, and what other threads can do during that time.

Practice Questions

Try each question first, then open the answer.

1. Two threads each run hits += 1 once, starting from hits = 10. What final values are possible on the standard build?

<details> <summary>Show answer</summary>

11 or 12. If one thread finishes before the other reads, the result is 12. If both read 10 before either writes, both store 11, and one update is lost.

</details>

2. What problem would CPython have without the GIL, even in a program whose own code shares no variables?

<details> <summary>Show answer</summary>

CPython's own state could be corrupted. Modules, classes, and functions are shared by every thread, and a lost change to one of their reference counts could free an object still in use.

</details>

3. A test runs pages_indexed += 1 from 4 threads, 1,000,000 times each, on the standard build and gets exactly 4,000,000 every time. Does this prove the code is thread-safe?

<details> <summary>Show answer</summary>

No. CPython does not promise where it switches threads, and the documentation lists i = i+1 as not thread-safe. The same code lost about 60 percent of its updates on the free-threaded build.

</details>

4. Four threads update a shared dictionary with counts[key] = counts.get(key, 0) + 1. Can the dictionary be corrupted, and can the counts be wrong? Give one fix that does not use a lock.

<details> <summary>Show answer</summary>

The dictionary stays consistent, but the counts can be wrong, because the read, add, and write together are not atomic. Give each thread its own dictionary and add the dictionaries together after the threads finish.

</details>

Reading Progress

0%


Vote for new content

On This Page

What the GIL Is For

One Line, Several Steps

Four Shared Updates, Measured

What You Must Protect Yourself

In Production

Key Takeaways

Practice Questions