From 64157d08219f6b7fc4b9a0838c85a735066d14bd Mon Sep 17 00:00:00 2001 From: Lysandros Nikolaou Date: Mon, 20 Oct 2025 17:06:53 +0200 Subject: [PATCH 01/14] gh-140374: Add glossary entries related to multithreading --- Doc/glossary.rst | 182 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 174 insertions(+), 8 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index c0ca0be304ebe4..bc0fbaa97f6cf6 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -134,6 +134,16 @@ Glossary iterator's :meth:`~object.__anext__` method until it raises a :exc:`StopAsyncIteration` exception. Introduced by :pep:`492`. + atomic operation + An operation that completes as a single indivisible unit without + interruption from other threads. Atomic operations are critical for + :term:`thread-safe` programming because they cannot be observed in a + partially completed state by other threads. In the + :term:`free-threaded ` build, elementary operations + should generally be assumed to be atomic unless the documentation + explicitly states otherwise. See also :term:`race condition` and + :term:`data race`. + attached thread state A :term:`thread state` that is active for the current OS thread. @@ -289,6 +299,23 @@ Glossary advanced mathematical feature. If you're not aware of a need for them, it's almost certain you can safely ignore them. + concurrency + The ability of different parts of a program to be executed out-of-order + or in partial order without affecting the outcome. This allows for + multiple tasks to make progress during overlapping time periods, though + not necessarily simultaneously. In Python, concurrency can be achieved + through :mod:`threading` (using OS threads), :mod:`asyncio` (cooperative + multitasking), or :mod:`multiprocessing` (separate processes). + See also :term:`parallelism`. + + concurrent modification + When multiple threads modify shared data at the same time without + proper synchronization. Concurrent modification can lead to + :term:`data races ` and corrupted data. In the + :term:`free-threaded ` build, built-in types like + :class:`dict`, :class:`list`, and :class:`set` use internal locks + to protect against concurrent modifications. + context This term has different meanings depending on where and how it is used. Some common meanings: @@ -343,6 +370,16 @@ Glossary :keyword:`async with` keywords. These were introduced by :pep:`492`. + critical section + A section of code that accesses shared resources and must not be + executed by multiple threads simultaneously. Critical sections are + typically protected using :term:`locks ` or other + :term:`synchronization primitives ` to + ensure :term:`thread-safe` access. In the C API, critical sections + on shared objects can be protected using :c:macro:`Py_BEGIN_CRITICAL_SECTION` + and :c:macro:`Py_END_CRITICAL_SECTION`. See also :term:`lock` and + :term:`race condition`. + CPython The canonical implementation of the Python programming language, as distributed on `python.org `_. The term "CPython" @@ -363,6 +400,24 @@ Glossary the :term:`cyclic garbage collector ` is to identify these groups and break the reference cycles so that the memory can be reclaimed. + data race + A situation where multiple threads access the same memory location + concurrently, at least one of the accesses is a write, and the threads + do not use any synchronization to control their access. Data races + lead to :term:`non-deterministic` behavior and can cause data corruption. + Proper use of :term:`locks ` and other :term:`synchronization primitives + ` prevents data races. See also + :term:`race condition` and :term:`thread-safe`. + + deadlock + A situation where two or more threads are unable to proceed because + each is waiting for the other to release a resource. For example, + if thread A holds lock 1 and waits for lock 2, while thread B holds + lock 2 and waits for lock 1, both threads will wait indefinitely. + Deadlocks can be avoided by always acquiring multiple :term:`locks ` + in a consistent order or by using timeout-based locking. See also + :term:`lock` and :term:`reentrant`. + decorator A function returning another function, usually applied as a function transformation using the ``@wrapper`` syntax. Common examples for @@ -662,6 +717,16 @@ Glossary requires the GIL to be held in order to use it. This refers to having an :term:`attached thread state`. + global state + Data that is accessible throughout a program, such as module-level + variables, class variables, or C static variables in :term:`extension modules + `. In multi-threaded programs, global state shared + between threads typically requires synchronization to avoid + :term:`race conditions `. In the + :term:`free-threaded ` build, :term:`per-module state` + is often preferred over global state for C extension modules. + See also :term:`per-module state`. + hash-based pyc A bytecode cache file that uses the hash rather than the last-modified time of the corresponding source file to determine its validity. See @@ -706,7 +771,9 @@ Glossary tuples. Such an object cannot be altered. A new object has to be created if a different value has to be stored. They play an important role in places where a constant hash value is needed, for example as a key - in a dictionary. + in a dictionary. Immutable objects are inherently :term:`thread-safe` + because their state cannot be modified after creation, eliminating concerns + about :term:`concurrent modification`. import path A list of locations (or :term:`path entries `) that are @@ -796,8 +863,9 @@ Glossary CPython does not consistently apply the requirement that an iterator define :meth:`~iterator.__iter__`. - And also please note that the free-threading CPython does not guarantee - the thread-safety of iterator operations. + And also please note that :term:`free-threaded ` + CPython does not guarantee :term:`thread-safe` behavior of iterator + operations. key function @@ -835,10 +903,11 @@ Glossary :keyword:`if` statements. In a multi-threaded environment, the LBYL approach can risk introducing a - race condition between "the looking" and "the leaping". For example, the - code, ``if key in mapping: return mapping[key]`` can fail if another + :term:`race condition` between "the looking" and "the leaping". For example, + the code, ``if key in mapping: return mapping[key]`` can fail if another thread removes *key* from *mapping* after the test, but before the lookup. - This issue can be solved with locks or by using the EAFP approach. + This issue can be solved with :term:`locks ` or by using the + :term:`EAFP` approach. See also :term:`thread-safe`. lexical analyzer @@ -857,6 +926,18 @@ Glossary clause is optional. If omitted, all elements in ``range(256)`` are processed. + lock + A :term:`synchronization primitive` that allows only one thread at a + time to access a shared resource. A thread must acquire a lock before + accessing the protected resource and release it afterward. If a thread + attempts to acquire a lock that is already held by another thread, it + will block until the lock becomes available. Python's :mod:`threading` + module provides :class:`~threading.Lock` (a basic lock) and + :class:`~threading.RLock` (a :term:`reentrant` lock). Locks are used + to prevent :term:`race conditions ` and ensure + :term:`thread-safe` access to shared data. See also + :term:`critical section`, :term:`deadlock`, and :term:`reentrant`. + loader An object that loads a module. It must define the :meth:`!exec_module` and :meth:`!create_module` methods @@ -942,8 +1023,11 @@ Glossary See :term:`method resolution order`. mutable - Mutable objects can change their value but keep their :func:`id`. See - also :term:`immutable`. + Mutable objects can change their value but keep their :func:`id`. + In multi-threaded programs, mutable objects that are shared between + threads require careful synchronization to avoid :term:`concurrent modification` + issues. See also :term:`immutable`, :term:`thread-safe`, and + :term:`concurrent modification`. named tuple The term "named tuple" applies to any type or class that inherits from @@ -1011,6 +1095,16 @@ Glossary properties, :meth:`~object.__getattribute__`, class methods, and static methods. + non-deterministic + Behavior where the outcome of a program can vary between executions with + the same inputs. In multi-threaded programs, non-deterministic behavior + often results from :term:`race conditions ` where the + relative timing or interleaving of threads affects the result. + :term:`Data races ` are a common cause of non-deterministic + bugs. Proper synchronization using :term:`locks ` and other + :term:`synchronization primitives ` helps + ensure deterministic behavior. + object Any data with state (attributes or value) and defined behavior (methods). Also the ultimate base class of any :term:`new-style @@ -1032,6 +1126,15 @@ Glossary See also :term:`regular package` and :term:`namespace package`. + parallelism + The simultaneous execution of multiple operations on different CPU cores. + True parallelism requires multiple processors or processor cores and + allows operations to run at exactly the same time, not just interleaved. + In Python, the :term:`free-threaded ` build enables + parallelism for multi-threaded programs by removing the :term:`global + interpreter lock`. The :mod:`multiprocessing` module also enables + parallelism by using separate processes. See also :term:`concurrency`. + parameter A named entity in a :term:`function` (or method) definition that specifies an :term:`argument` (or in some cases, arguments) that the @@ -1116,6 +1219,16 @@ Glossary :class:`str` or :class:`bytes` result instead, respectively. Introduced by :pep:`519`. + per-module state + State that is stored separately for each instance of a module, rather + than in :term:`global state`. For :term:`extension modules ` + written in C, per-module state helps support multiple interpreters and + is safer in :term:`free-threaded ` builds because each + module instance can have its own data without requiring global + synchronization. Per-module state is accessed through the module object + rather than through C static variables. See :ref:`isolating-extensions-howto` + for more information. See also :term:`global state`. + PEP Python Enhancement Proposal. A PEP is a design document providing information to the Python community, or describing a new @@ -1206,6 +1319,18 @@ Glossary >>> email.mime.text.__name__ 'email.mime.text' + race condition + A flaw in the design or implementation of a program where the correctness + depends on the relative timing or ordering of events, particularly in + multi-threaded programs. Race conditions can lead to + :term:`non-deterministic` behavior and bugs that are difficult to + reproduce. A :term:`data race` is a specific type of race condition + involving unsynchronized access to shared memory. The :term:`LBYL` + coding style is particularly susceptible to race conditions in + multi-threaded code. Using :term:`locks ` and other + :term:`synchronization primitives ` + helps prevent race conditions. + reference count The number of references to an object. When the reference count of an object drops to zero, it is deallocated. Some objects are @@ -1227,6 +1352,23 @@ Glossary See also :term:`namespace package`. + reentrant + A property of a function or :term:`lock` that allows it to be called or + acquired multiple times by the same thread without causing errors or a + :term:`deadlock`. + + For functions, reentrancy means the function can be safely called again + before a previous invocation has completed, which is important when + functions may be called recursively or from signal handlers. + + For locks, Python's :class:`threading.RLock` (reentrant lock) is + reentrant, meaning a thread that already holds the lock can acquire it + again without blocking. In contrast, :class:`threading.Lock` is not + reentrant - attempting to acquire it twice from the same thread will cause + a deadlock. + + See also :term:`lock` and :term:`deadlock`. + REPL An acronym for the "read–eval–print loop", another name for the :term:`interactive` interpreter shell. @@ -1331,6 +1473,17 @@ Glossary See also :term:`borrowed reference`. + synchronization primitive + A basic building block for coordinating the execution of multiple threads + to ensure :term:`thread-safe` access to shared resources. Python's + :mod:`threading` module provides several synchronization primitives + including :class:`~threading.Lock`, :class:`~threading.RLock`, + :class:`~threading.Semaphore`, :class:`~threading.Condition`, + :class:`~threading.Event`, and :class:`~threading.Barrier`. These + primitives help prevent :term:`race conditions ` and + coordinate thread execution. See also :term:`lock` and + :term:`critical section`. + t-string t-strings String literals prefixed with ``t`` or ``T`` are commonly called @@ -1383,6 +1536,19 @@ Glossary See :ref:`Thread State and the Global Interpreter Lock ` for more information. + thread-safe + Code that functions correctly when accessed by multiple threads + concurrently. Thread-safe code uses appropriate + :term:`synchronization primitives ` like + :term:`locks ` to protect shared mutable state, or is designed + to avoid shared mutable state entirely. In the + :term:`free-threaded ` build, built-in types like + :class:`dict`, :class:`list`, and :class:`set` use internal locking + to provide thread-safe operations, though this doesn't guarantee safety + for all use patterns. Code that is not thread-safe may experience + :term:`race conditions ` and :term:`data races ` + when used in multi-threaded programs. + token A small unit of source code, generated by the From 0825a98fd09bc9104d81abd3883cb8cb2f11498b Mon Sep 17 00:00:00 2001 From: Lysandros Nikolaou Date: Tue, 28 Oct 2025 13:56:46 +0100 Subject: [PATCH 02/14] Address first round of feedback --- Doc/glossary.rst | 65 +++++++++++++++++++++++++----------------------- 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index bc0fbaa97f6cf6..e8b79a3785b8b3 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -375,9 +375,8 @@ Glossary executed by multiple threads simultaneously. Critical sections are typically protected using :term:`locks ` or other :term:`synchronization primitives ` to - ensure :term:`thread-safe` access. In the C API, critical sections - on shared objects can be protected using :c:macro:`Py_BEGIN_CRITICAL_SECTION` - and :c:macro:`Py_END_CRITICAL_SECTION`. See also :term:`lock` and + ensure :term:`thread-safe` access. Critical section are purely a concept + in the C API and are not exposed in Python. See also :term:`lock` and :term:`race condition`. CPython @@ -413,10 +412,11 @@ Glossary A situation where two or more threads are unable to proceed because each is waiting for the other to release a resource. For example, if thread A holds lock 1 and waits for lock 2, while thread B holds - lock 2 and waits for lock 1, both threads will wait indefinitely. - Deadlocks can be avoided by always acquiring multiple :term:`locks ` - in a consistent order or by using timeout-based locking. See also - :term:`lock` and :term:`reentrant`. + lock 2 and waits for lock 1, both threads will wait indefinitely. Any + program that makes blocking calls using more than one lock is possibly + susceptible to deadlocks. Deadlocks can be avoided by always acquiring + multiple :term:`locks ` in a consistent order or by using + timeout-based locking. See also :term:`lock` and :term:`reentrant`. decorator A function returning another function, usually applied as a function @@ -935,8 +935,10 @@ Glossary module provides :class:`~threading.Lock` (a basic lock) and :class:`~threading.RLock` (a :term:`reentrant` lock). Locks are used to prevent :term:`race conditions ` and ensure - :term:`thread-safe` access to shared data. See also - :term:`critical section`, :term:`deadlock`, and :term:`reentrant`. + :term:`thread-safe` access to shared data. Alternative design patterns + to locks exist such as queues, producer/consumer patterns, and + thread-local state. See also :term:`critical section`, :term:`deadlock`, + and :term:`reentrant`. loader An object that loads a module. @@ -1023,11 +1025,11 @@ Glossary See :term:`method resolution order`. mutable - Mutable objects can change their value but keep their :func:`id`. - In multi-threaded programs, mutable objects that are shared between - threads require careful synchronization to avoid :term:`concurrent modification` - issues. See also :term:`immutable`, :term:`thread-safe`, and - :term:`concurrent modification`. + An :term:`object` with state that is allowed to change during the course + of the program. In multi-threaded programs, mutable objects that are + shared between threads require careful synchronization to avoid + :term:`concurrent modification` issues. See also :term:`immutable`, + :term:`thread-safe`, and :term:`concurrent modification`. named tuple The term "named tuple" applies to any type or class that inherits from @@ -1100,8 +1102,7 @@ Glossary the same inputs. In multi-threaded programs, non-deterministic behavior often results from :term:`race conditions ` where the relative timing or interleaving of threads affects the result. - :term:`Data races ` are a common cause of non-deterministic - bugs. Proper synchronization using :term:`locks ` and other + Proper synchronization using :term:`locks ` and other :term:`synchronization primitives ` helps ensure deterministic behavior. @@ -1128,12 +1129,13 @@ Glossary parallelism The simultaneous execution of multiple operations on different CPU cores. - True parallelism requires multiple processors or processor cores and - allows operations to run at exactly the same time, not just interleaved. + True parallelism requires multiple processors or processor cores where + operations run at exactly the same time and are not just interleaved. In Python, the :term:`free-threaded ` build enables - parallelism for multi-threaded programs by removing the :term:`global - interpreter lock`. The :mod:`multiprocessing` module also enables - parallelism by using separate processes. See also :term:`concurrency`. + parallelism for multi-threaded programs that access state stored in the + interpreter by disabling the :term:`global interpreter lock`. The + :mod:`multiprocessing` module also enables parallelism by using separate + processes. See also :term:`concurrency`. parameter A named entity in a :term:`function` (or method) definition that @@ -1221,13 +1223,10 @@ Glossary per-module state State that is stored separately for each instance of a module, rather - than in :term:`global state`. For :term:`extension modules ` - written in C, per-module state helps support multiple interpreters and - is safer in :term:`free-threaded ` builds because each - module instance can have its own data without requiring global - synchronization. Per-module state is accessed through the module object - rather than through C static variables. See :ref:`isolating-extensions-howto` - for more information. See also :term:`global state`. + than in :term:`global state`. Per-module state is accessed through the + module object rather than through C static variables. + See :ref:`isolating-extensions-howto` for more information. See also + :term:`global state`. PEP Python Enhancement Proposal. A PEP is a design document @@ -1320,7 +1319,7 @@ Glossary 'email.mime.text' race condition - A flaw in the design or implementation of a program where the correctness + A condition of a program where the its behavior depends on the relative timing or ordering of events, particularly in multi-threaded programs. Race conditions can lead to :term:`non-deterministic` behavior and bugs that are difficult to @@ -1359,7 +1358,9 @@ Glossary For functions, reentrancy means the function can be safely called again before a previous invocation has completed, which is important when - functions may be called recursively or from signal handlers. + functions may be called recursively or from signal handlers. Thread-unsafe + functions may be :term:`non-deterministic` if they're called reentrantly in a + multithreaded program. For locks, Python's :class:`threading.RLock` (reentrant lock) is reentrant, meaning a thread that already holds the lock can acquire it @@ -1479,7 +1480,9 @@ Glossary :mod:`threading` module provides several synchronization primitives including :class:`~threading.Lock`, :class:`~threading.RLock`, :class:`~threading.Semaphore`, :class:`~threading.Condition`, - :class:`~threading.Event`, and :class:`~threading.Barrier`. These + :class:`~threading.Event`, and :class:`~threading.Barrier`. Additionally, + the :mod:`queue` module provides multi-producer, multi-consumer queues + that are especially usedul in multithreaded programs. These primitives help prevent :term:`race conditions ` and coordinate thread execution. See also :term:`lock` and :term:`critical section`. From 3f44be0414d4d042cc71eb2050684393372e8e90 Mon Sep 17 00:00:00 2001 From: Lysandros Nikolaou Date: Tue, 28 Oct 2025 14:02:31 +0100 Subject: [PATCH 03/14] Remove references to builtins --- Doc/glossary.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index e8b79a3785b8b3..5d1992b9bfa8d8 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -311,10 +311,7 @@ Glossary concurrent modification When multiple threads modify shared data at the same time without proper synchronization. Concurrent modification can lead to - :term:`data races ` and corrupted data. In the - :term:`free-threaded ` build, built-in types like - :class:`dict`, :class:`list`, and :class:`set` use internal locks - to protect against concurrent modifications. + :term:`data races ` and corrupted data. context This term has different meanings depending on where and how it is used. From 568d201e1bce4c0f3d9f142fc2b1a749b94b1f4b Mon Sep 17 00:00:00 2001 From: Lysandros Nikolaou Date: Wed, 29 Oct 2025 11:29:14 +0100 Subject: [PATCH 04/14] Delete comment about elementary operations --- Doc/glossary.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 5d1992b9bfa8d8..5288bdebc0d30a 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -138,11 +138,8 @@ Glossary An operation that completes as a single indivisible unit without interruption from other threads. Atomic operations are critical for :term:`thread-safe` programming because they cannot be observed in a - partially completed state by other threads. In the - :term:`free-threaded ` build, elementary operations - should generally be assumed to be atomic unless the documentation - explicitly states otherwise. See also :term:`race condition` and - :term:`data race`. + partially completed state by other threads. See also + :term:`race condition` and :term:`data race`. attached thread state From 22cf4f6e20efbee42594b6baa485a83ab631f999 Mon Sep 17 00:00:00 2001 From: Lysandros Nikolaou Date: Wed, 29 Oct 2025 19:02:43 +0100 Subject: [PATCH 05/14] Address feedback; add entry for native code --- Doc/glossary.rst | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 5288bdebc0d30a..c9e0d5f8ed8c52 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -307,8 +307,9 @@ Glossary concurrent modification When multiple threads modify shared data at the same time without - proper synchronization. Concurrent modification can lead to - :term:`data races ` and corrupted data. + proper synchronization. Concurrent modification can cause + :term:`race conditions `, and might also trigger a + :term:`data race `, data corruption, or both. context This term has different meanings depending on where and how it is used. @@ -399,8 +400,10 @@ Glossary do not use any synchronization to control their access. Data races lead to :term:`non-deterministic` behavior and can cause data corruption. Proper use of :term:`locks ` and other :term:`synchronization primitives - ` prevents data races. See also - :term:`race condition` and :term:`thread-safe`. + ` prevents data races. Note that data races + can only happen in native code, but that :term:`native code` might be + exposed in a Python API. See also :term:`race condition` and + :term:`thread-safe`. deadlock A situation where two or more threads are unable to proceed because @@ -716,7 +719,8 @@ Glossary variables, class variables, or C static variables in :term:`extension modules `. In multi-threaded programs, global state shared between threads typically requires synchronization to avoid - :term:`race conditions `. In the + :term:`race conditions ` and + :term:`data races `. In the :term:`free-threaded ` build, :term:`per-module state` is often preferred over global state for C extension modules. See also :term:`per-module state`. @@ -1075,6 +1079,13 @@ Glossary See also :term:`module`. + native code + Code that is compiled to machine instructions and runs directly on the + processor, as opposed to code that is interpreted or runs in a virtual + machine. In the context of Python, native code typically refers to + C, C++, Rust of Fortran code in :term:`extension modules ` + that can be called from Python. See also :term:`extension module`. + nested scope The ability to refer to a variable in an enclosing definition. For instance, a function defined inside another function can refer to @@ -1122,7 +1133,7 @@ Glossary See also :term:`regular package` and :term:`namespace package`. parallelism - The simultaneous execution of multiple operations on different CPU cores. + The simultaneous execution of operations on multiple processors. True parallelism requires multiple processors or processor cores where operations run at exactly the same time and are not just interleaved. In Python, the :term:`free-threaded ` build enables @@ -1476,7 +1487,7 @@ Glossary :class:`~threading.Semaphore`, :class:`~threading.Condition`, :class:`~threading.Event`, and :class:`~threading.Barrier`. Additionally, the :mod:`queue` module provides multi-producer, multi-consumer queues - that are especially usedul in multithreaded programs. These + that are especially useful in multithreaded programs. These primitives help prevent :term:`race conditions ` and coordinate thread execution. See also :term:`lock` and :term:`critical section`. @@ -1541,8 +1552,8 @@ Glossary to avoid shared mutable state entirely. In the :term:`free-threaded ` build, built-in types like :class:`dict`, :class:`list`, and :class:`set` use internal locking - to provide thread-safe operations, though this doesn't guarantee safety - for all use patterns. Code that is not thread-safe may experience + to make many operations thread-safe, although thread safety is not + necessarily guaranteed. Code that is not thread-safe may experience :term:`race conditions ` and :term:`data races ` when used in multi-threaded programs. From bd7b731277a9e4475dd47a589adb753ccaaae045 Mon Sep 17 00:00:00 2001 From: Lysandros Nikolaou Date: Wed, 29 Oct 2025 19:06:04 +0100 Subject: [PATCH 06/14] Fix lint error --- Doc/glossary.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index c9e0d5f8ed8c52..5ead96628eaa8a 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -308,7 +308,7 @@ Glossary concurrent modification When multiple threads modify shared data at the same time without proper synchronization. Concurrent modification can cause - :term:`race conditions `, and might also trigger a + :term:`race conditions `, and might also trigger a :term:`data race `, data corruption, or both. context From 8f433ee0215b0aba08b188185387aaa21fbfb472 Mon Sep 17 00:00:00 2001 From: Lysandros Nikolaou Date: Thu, 6 Nov 2025 17:18:33 +0100 Subject: [PATCH 07/14] Address Sam's feedback --- Doc/glossary.rst | 57 +++++++++++++++++++++--------------------------- 1 file changed, 25 insertions(+), 32 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 5ead96628eaa8a..f32e4dd2295849 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -135,11 +135,12 @@ Glossary :exc:`StopAsyncIteration` exception. Introduced by :pep:`492`. atomic operation - An operation that completes as a single indivisible unit without - interruption from other threads. Atomic operations are critical for - :term:`thread-safe` programming because they cannot be observed in a - partially completed state by other threads. See also - :term:`race condition` and :term:`data race`. + An operation that appears to execute as a single, indivisible step: no + other thread can observe it half-done, and its effects become visible all + at once. Python does not guarantee that ordinary high-level statements + are atomic (for example, ``x += 1`` performs multiple bytecode operations + and is not atomic). Atomicity is only guaranteed where explicitly + documented. See also :term:`race condition` and :term:`data race`. attached thread state @@ -365,15 +366,6 @@ Glossary :keyword:`async with` keywords. These were introduced by :pep:`492`. - critical section - A section of code that accesses shared resources and must not be - executed by multiple threads simultaneously. Critical sections are - typically protected using :term:`locks ` or other - :term:`synchronization primitives ` to - ensure :term:`thread-safe` access. Critical section are purely a concept - in the C API and are not exposed in Python. See also :term:`lock` and - :term:`race condition`. - CPython The canonical implementation of the Python programming language, as distributed on `python.org `_. The term "CPython" @@ -406,14 +398,15 @@ Glossary :term:`thread-safe`. deadlock - A situation where two or more threads are unable to proceed because - each is waiting for the other to release a resource. For example, - if thread A holds lock 1 and waits for lock 2, while thread B holds - lock 2 and waits for lock 1, both threads will wait indefinitely. Any - program that makes blocking calls using more than one lock is possibly - susceptible to deadlocks. Deadlocks can be avoided by always acquiring - multiple :term:`locks ` in a consistent order or by using - timeout-based locking. See also :term:`lock` and :term:`reentrant`. + A situation in which two or more tasks (threads, processes, or coroutines) + wait indefinitely for each other to release resources or complete actions, + preventing any from making progress. For example, if thread A holds lock + 1 and waits for lock 2, while thread B holds lock 2 and waits for lock 1, + both threads will wait indefinitely. In Python this often arises from + acquiring multiple locks in conflicting orders or from circular + join/await dependencies. Deadlocks can be avoided by always acquiring + multiple :term:`locks ` in a consistent order. See also + :term:`lock` and :term:`reentrant`. decorator A function returning another function, usually applied as a function @@ -1133,14 +1126,14 @@ Glossary See also :term:`regular package` and :term:`namespace package`. parallelism - The simultaneous execution of operations on multiple processors. - True parallelism requires multiple processors or processor cores where - operations run at exactly the same time and are not just interleaved. - In Python, the :term:`free-threaded ` build enables - parallelism for multi-threaded programs that access state stored in the - interpreter by disabling the :term:`global interpreter lock`. The - :mod:`multiprocessing` module also enables parallelism by using separate - processes. See also :term:`concurrency`. + Executing multiple operations at the same time (e.g. on multiple CPU + cores). In Python builds with the + :term:`global interpreter lock (GIL) `, only one + thread runs Python bytecode at a time, so taking advantage of multiple + CPU cores typically involves multiple processes + (e.g. :mod:`multiprocessing`) or native extensions that release the GIL. + In :term:`free-threaded ` Python, multiple Python threads + can run Python code simultaneously on different cores. parameter A named entity in a :term:`function` (or method) definition that @@ -1545,8 +1538,8 @@ Glossary information. thread-safe - Code that functions correctly when accessed by multiple threads - concurrently. Thread-safe code uses appropriate + A module, function, or class that behaves correctly when used by multiple + threads concurrently. Thread-safe code uses appropriate :term:`synchronization primitives ` like :term:`locks ` to protect shared mutable state, or is designed to avoid shared mutable state entirely. In the From 2821203d76099823943d19a3840ae10a7d444c1b Mon Sep 17 00:00:00 2001 From: Lysandros Nikolaou Date: Thu, 6 Nov 2025 17:27:32 +0100 Subject: [PATCH 08/14] Fix missing refs --- Doc/glossary.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index f32e4dd2295849..7295b7629e0b9c 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -928,8 +928,7 @@ Glossary to prevent :term:`race conditions ` and ensure :term:`thread-safe` access to shared data. Alternative design patterns to locks exist such as queues, producer/consumer patterns, and - thread-local state. See also :term:`critical section`, :term:`deadlock`, - and :term:`reentrant`. + thread-local state. See also :term:`deadlock`, and :term:`reentrant`. loader An object that loads a module. @@ -1132,7 +1131,7 @@ Glossary thread runs Python bytecode at a time, so taking advantage of multiple CPU cores typically involves multiple processes (e.g. :mod:`multiprocessing`) or native extensions that release the GIL. - In :term:`free-threaded ` Python, multiple Python threads + In :term:`free-threaded ` Python, multiple Python threads can run Python code simultaneously on different cores. parameter @@ -1482,8 +1481,7 @@ Glossary the :mod:`queue` module provides multi-producer, multi-consumer queues that are especially useful in multithreaded programs. These primitives help prevent :term:`race conditions ` and - coordinate thread execution. See also :term:`lock` and - :term:`critical section`. + coordinate thread execution. See also :term:`lock`. t-string t-strings From 8407f36e9fa813f103e566cff1f70b0892e34d58 Mon Sep 17 00:00:00 2001 From: Lysandros Nikolaou Date: Thu, 4 Dec 2025 15:19:25 +0100 Subject: [PATCH 09/14] Remove unnecessary "ordinary" characterization --- Doc/glossary.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 4f8ae5d3c89098..f11220832d63a4 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -137,10 +137,10 @@ Glossary atomic operation An operation that appears to execute as a single, indivisible step: no other thread can observe it half-done, and its effects become visible all - at once. Python does not guarantee that ordinary high-level statements - are atomic (for example, ``x += 1`` performs multiple bytecode operations - and is not atomic). Atomicity is only guaranteed where explicitly - documented. See also :term:`race condition` and :term:`data race`. + at once. Python does not guarantee that high-level statements are atomic + (for example, ``x += 1`` performs multiple bytecode operations and is not + atomic). Atomicity is only guaranteed where explicitly documented. See + also :term:`race condition` and :term:`data race`. attached thread state From 5da539accc64424ddde831c75912107e3d2fdefa Mon Sep 17 00:00:00 2001 From: Lysandros Nikolaou Date: Thu, 4 Dec 2025 17:54:17 +0100 Subject: [PATCH 10/14] Another round of feedback --- Doc/glossary.rst | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index f11220832d63a4..56225c969e5a29 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -298,13 +298,14 @@ Glossary it's almost certain you can safely ignore them. concurrency - The ability of different parts of a program to be executed out-of-order - or in partial order without affecting the outcome. This allows for - multiple tasks to make progress during overlapping time periods, though - not necessarily simultaneously. In Python, concurrency can be achieved - through :mod:`threading` (using OS threads), :mod:`asyncio` (cooperative - multitasking), or :mod:`multiprocessing` (separate processes). - See also :term:`parallelism`. + The ability of a computer program to perform multiple tasks at the same + time. Python provides libraries for writing programs that make use of + different forms of concurrency. :mod:`asyncio` is a library for dealing + with asynchronous tasks and coroutines. :mod:`threading`` provides + access to operating system threads and :mod:`multiprocessing` to + operating system processes. Multi-core processors can execute threads and + processes on different CPU cores at the same time (see + :term:`parallelism`). concurrent modification When multiple threads modify shared data at the same time without @@ -1227,13 +1228,6 @@ Glossary :class:`str` or :class:`bytes` result instead, respectively. Introduced by :pep:`519`. - per-module state - State that is stored separately for each instance of a module, rather - than in :term:`global state`. Per-module state is accessed through the - module object rather than through C static variables. - See :ref:`isolating-extensions-howto` for more information. See also - :term:`global state`. - PEP Python Enhancement Proposal. A PEP is a design document providing information to the Python community, or describing a new From 14d8179865c524063ef54de26c326cea3a0ccd19 Mon Sep 17 00:00:00 2001 From: Lysandros Nikolaou Date: Thu, 4 Dec 2025 18:00:43 +0100 Subject: [PATCH 11/14] Fix lint errors --- Doc/glossary.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 56225c969e5a29..093429a98871f9 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -301,7 +301,7 @@ Glossary The ability of a computer program to perform multiple tasks at the same time. Python provides libraries for writing programs that make use of different forms of concurrency. :mod:`asyncio` is a library for dealing - with asynchronous tasks and coroutines. :mod:`threading`` provides + with asynchronous tasks and coroutines. :mod:`threading` provides access to operating system threads and :mod:`multiprocessing` to operating system processes. Multi-core processors can execute threads and processes on different CPU cores at the same time (see @@ -714,10 +714,7 @@ Glossary `. In multi-threaded programs, global state shared between threads typically requires synchronization to avoid :term:`race conditions ` and - :term:`data races `. In the - :term:`free-threaded ` build, :term:`per-module state` - is often preferred over global state for C extension modules. - See also :term:`per-module state`. + :term:`data races `. hash-based pyc A bytecode cache file that uses the hash rather than the last-modified From ce681dd4da8fcda772b8d721ec682cbd3562acd8 Mon Sep 17 00:00:00 2001 From: Lysandros Nikolaou Date: Thu, 11 Dec 2025 14:57:08 +0100 Subject: [PATCH 12/14] Apply suggestions from code review Co-authored-by: Daniele Parmeggiani <8658291+dpdani@users.noreply.github.com> --- Doc/glossary.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 093429a98871f9..636817767b7786 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -762,7 +762,7 @@ Glossary role in places where a constant hash value is needed, for example as a key in a dictionary. Immutable objects are inherently :term:`thread-safe` because their state cannot be modified after creation, eliminating concerns - about :term:`concurrent modification`. + about improperly synchronized :term:`concurrent modification`. import path A list of locations (or :term:`path entries `) that are @@ -1073,7 +1073,7 @@ Glossary Code that is compiled to machine instructions and runs directly on the processor, as opposed to code that is interpreted or runs in a virtual machine. In the context of Python, native code typically refers to - C, C++, Rust of Fortran code in :term:`extension modules ` + C, C++, Rust or Fortran code in :term:`extension modules ` that can be called from Python. See also :term:`extension module`. nested scope From faf9a66c337a29e4c8ddf516a174f0e411627b4f Mon Sep 17 00:00:00 2001 From: Lysandros Nikolaou Date: Thu, 11 Dec 2025 14:57:50 +0100 Subject: [PATCH 13/14] Improve concurrent modification glossary entry --- Doc/glossary.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 636817767b7786..67fea278c91959 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -308,8 +308,8 @@ Glossary :term:`parallelism`). concurrent modification - When multiple threads modify shared data at the same time without - proper synchronization. Concurrent modification can cause + When multiple threads modify shared data at the same time. Concurrent + modification without proper synchronization can cause :term:`race conditions `, and might also trigger a :term:`data race `, data corruption, or both. From 46f0d9e107aff77393a83cdeeb25edbb6419c528 Mon Sep 17 00:00:00 2001 From: Lysandros Nikolaou Date: Thu, 11 Dec 2025 15:11:59 +0100 Subject: [PATCH 14/14] Address more feedback --- Doc/glossary.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 67fea278c91959..8742e945629823 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -1016,7 +1016,7 @@ Glossary An :term:`object` with state that is allowed to change during the course of the program. In multi-threaded programs, mutable objects that are shared between threads require careful synchronization to avoid - :term:`concurrent modification` issues. See also :term:`immutable`, + :term:`race conditions `. See also :term:`immutable`, :term:`thread-safe`, and :term:`concurrent modification`. named tuple @@ -1472,9 +1472,9 @@ Glossary See also :term:`borrowed reference`. synchronization primitive - A basic building block for coordinating the execution of multiple threads - to ensure :term:`thread-safe` access to shared resources. Python's - :mod:`threading` module provides several synchronization primitives + A basic building block for coordinating (synchronizing) the execution of + multiple threads to ensure :term:`thread-safe` access to shared resources. + Python's :mod:`threading` module provides several synchronization primitives including :class:`~threading.Lock`, :class:`~threading.RLock`, :class:`~threading.Semaphore`, :class:`~threading.Condition`, :class:`~threading.Event`, and :class:`~threading.Barrier`. Additionally,