diff --git a/Doc/glossary.rst b/Doc/glossary.rst index c0ca0be304ebe4..5ead96628eaa8a 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -134,6 +134,13 @@ 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. 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 +296,21 @@ 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 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. Some common meanings: @@ -343,6 +365,15 @@ 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" @@ -363,6 +394,27 @@ 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. 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 + 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`. + decorator A function returning another function, usually applied as a function transformation using the ``@wrapper`` syntax. Common examples for @@ -662,6 +714,17 @@ 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 ` 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`. + 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 +769,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 +861,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 +901,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 +924,20 @@ 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. 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. 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`. + 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 @@ -995,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 @@ -1011,6 +1102,15 @@ 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. + 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 +1132,16 @@ 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`. + 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 +1226,13 @@ 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 @@ -1206,6 +1323,18 @@ Glossary >>> email.mime.text.__name__ 'email.mime.text' + race condition + 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 + 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 +1356,25 @@ 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. 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 + 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 +1479,19 @@ 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`. Additionally, + 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`. + t-string t-strings String literals prefixed with ``t`` or ``T`` are commonly called @@ -1383,6 +1544,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 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. + token A small unit of source code, generated by the