Contents: concurrent C and free-threaded CPython¶

This index covers the primer in reading order and links to every chapter section. Chapters 1–8 explain general concurrent C concepts; chapters 9–13 explain CPython's mechanisms; chapter 14 brings them together into a decision guide.

For targeted lookup, start with the topic index below. For edits, read the linked section in context and check related chapters before adding an explanation that may already exist. Section links are preferable to line numbers, which change as the guide is edited.

For definitions of concurrency terms, see the glossary. For external books, articles, talks, and references, see further reading.

Topic index¶

Detailed chapter contents¶

01. The basic problem: shared mutable memory¶

Introduces conflicting accesses, logical races, related fields, and the separate pointer-lifetime problem.

• A simple shared variable
• Data races and race conditions are different
• Shared state is often larger than one variable
• Pointer access and object lifetime are separate problems
• Start by identifying the shared state

02. The C abstract machine and undefined behavior¶

Explains why correctness depends on the C rules, not observed machine instructions or tests on one CPU.

• The compiler does not execute the source literally
• Undefined behavior removes the normal requirements
• An ordinary C data race is undefined behavior
• Hardware atomicity is not C atomicity
• volatile does not provide synchronization
• Source order alone does not synchronize threads
• Object lifetime is also part of correctness
• Use a defined synchronization rule

03. The C memory model¶

Defines ordering relationships and gives the complete release/acquire publication example and proof.

• sequenced-before orders operations within a thread
• synchronizes-with connects threads
• happens-before combines the ordering
• Publishing data with release and acquire
• Atomicity and ordering are different guarantees
• Each atomic object has a modification order
• Compiler and CPU ordering are different layers
• AMD64 and ARM64 provide different hardware ordering
• Use the model to explain why an access is safe

04. Atomic operations¶

Explains atomic operations and memory orders using C11 examples, then maps them to CPython's interfaces.

• Atomic objects require atomic access
• Loads and stores transfer individual values
• Read-modify-write is one indivisible operation
• Exchange replaces a value
• Compare-exchange updates conditionally
• Relaxed ordering provides atomicity only
• Release publishes earlier work
• Acquire observes published work
• Acquire-release combines both directions
• Sequential consistency provides a stronger default
• Use CPython's atomic API in interpreter code
• Fences order without carrying the value operation
• Atomics do not solve object lifetime
• Choose atomics for a complete, explainable protocol

05. Synchronization¶

Teaches mutex-based protection of complete operations, lock ownership and ordering, and waiting primitives.

• A mutex provides mutual exclusion and ordering
• Name the state protected by each mutex
• Protect invariants, not individual accesses
• Locks do not preserve facts after unlock
• Locking has ownership rules
• Multiple mutexes require a lock order
• Condition variables wait for state changes
• Events represent persistent notification state
• Spin locks trade sleeping for repeated polling
• Synchronization does not imply fairness
• Prefer locks for related state
• Review a synchronization rule as a whole

06. Concurrency and performance¶

Covers coherence, contention, false sharing, instruction costs, and structural ways to reduce sharing.

• CPU cores communicate through a cache-coherence system
• Coherence works at cache-line granularity
• Contended writes move cache-line ownership
• Atomic does not mean inexpensive
• Mutexes have fast and contended paths
• Atomics and locks can both serialize execution
• Keep mutex-protected regions focused
• Sharding reduces shared writes
• Per-thread state can eliminate synchronization
• Read-mostly data benefits from immutable snapshots
• Memory allocation and layout affect scaling
• Optimize only after identifying the bottleneck

07. Lock-free algorithms¶

Develops progress guarantees, CAS and linearization, optimistic validation, ABA, and reclamation obligations. The advanced versioned-snapshot example is explicitly not lock-free.

• Lock-free describes system-wide progress
• CAS commits a conditional change
• The linearization point defines when an operation takes effect
• Optimistic operations read, validate, and retry
• Advanced example: optimistic reads need a precise protocol
• CAS can fail repeatedly under contention
• Multi-field state needs one commit mechanism
• ABA defeats value-only validation
• Removal and reclamation are separate operations
• Reference counting alone may be too late
• Safe reclamation delays freeing
• Lock-free code needs a complete proof

08. Safe memory reclamation¶

Surveys reader protection, grace periods, hazard pointers, epochs, RCU, QSBR, and destruction constraints.

• An atomic pointer does not protect its target
• Grace periods separate removal from reclamation
• Reclamation needs a defined reader scope
• Hazard pointers protect named objects
• Epoch-based reclamation groups readers
• RCU makes read-side work cheap
• QSBR reports points with no old references
• Stalled threads trade safety for memory retention
• Thread exit and detachment require cleanup
• Reclamation and destruction are different concerns
• Type-stable storage allows limited reuse
• Ordering and lifetime remain separate proofs
• Choose reclamation from the reader contract

09. CPython's concurrency model¶

Introduces the two builds, thread-state contracts, public API implications, and replacements for GIL-based assumptions.

• The GIL serializes attached threads in the traditional build
• Free threading allows several attached threads
• The free-threaded build can run with the GIL enabled
• Attached, detached, and suspended are distinct states
• Stop-the-world operations use thread-state transitions
• The GIL's old assumptions must be replaced individually
• Container safety does not make compound operations atomic
• Direct field access bypasses API synchronization
• Borrowed references need renewed scrutiny
• Reference counting is concurrency-aware
• Extension state may now be genuinely shared

10. PyMutex¶

Explains the concrete mutex API, initialization and address requirements, waiting behavior, diagnostics, and callback hazards.

• Store the mutex beside the state it protects
• A PyMutex has a stable address
• Lock and unlock delimit the invariant
• Keep complete state transitions under one acquisition
• Waiting temporarily detaches the thread state
• The implementation has fast and parked paths
• PyMutex is not recursive
• PyMutex_IsLocked() is only diagnostic
• Unlock exactly once on every path
• Define a lock order for multiple mutexes
• Avoid arbitrary Python execution while holding a direct mutex
• Do not lock ob_mutex directly
• Choose direct locking when the lock must stay held

11. CPython critical sections¶

Explains suspend-and-resume locking, lexical pairing, nesting and recursion, build contracts, and object/mutex-backed APIs.

• Use critical sections for Python object state
• The macros form a lexical block
• Each thread has a stack of critical sections
• Detachment suspends all active sections
• Restore invariants before any possible suspension
• Reacquisition does not restore old facts
• Nested single-object sections do not lock two objects reliably
• At most two object locks are supported
• Recursive entry avoids deadlock but can release outer locks
• Object locks exclude only cooperating operations
• Built-in APIs usually manage their own locking
• Use critical sections to acquire ob_mutex
• Mutex-backed critical sections support non-object state
• Critical sections are no-ops in the default build
• Recognize CPython's generated code and internal helpers
• Choose between a direct mutex and a critical section

12. Stop-the-world¶

Explains pause scopes, thread-state transitions, rare global updates, and the hazards of locks and arbitrary code during a pause.

• A pause can cover one interpreter or the runtime
• Attached threads stop at safe points
• A pause provides a global exclusion point
• Prepare before stopping, but read changing state afterward
• Do not wait for locks while threads are suspended
• Do not run arbitrary Python code while stopped
• Garbage-collection state is not proof of a pause
• Stop-the-world has a broad performance cost
• Choose a narrower mechanism when possible

13. QSBR in CPython¶

Explains CPython's reader obligations, sequences, delayed-work helpers, lifecycle and retention costs, and specialized allocator reuse.

• QSBR complements reference counting
• A quiescent state is a promise from one thread
• CPython tracks one write sequence per interpreter
• Retirement follows a fixed sequence
• Delayed frees and decrefs connect lifetime to QSBR
• Sequence advancement can be deferred
• Attached and detached states affect grace periods
• A delayed thread can retain much memory
• Allocator reuse is part of the lifetime problem
• QSBR does not provide publication ordering by itself
• QSBR is useful for read-mostly internal storage

14. Choosing a technique¶

Provides the decision order, important qualifications, combined-protocol example, and final review checklist.

• A practical decision order
• Check the qualifications before choosing
• Removing sharing needs an ownership rule
• A critical section may release its locks
• Atomic operations must match the whole operation
• Internal mechanisms have restricted scopes
• Keep ordering and lifetime as separate checks
• Give each mechanism one explicit job
• Review the complete protocol

Markdown source