Skip to content

Commit 8f433ee

Browse files
committed
Address Sam's feedback
1 parent bd7b731 commit 8f433ee

File tree

1 file changed

+25
-32
lines changed

1 file changed

+25
-32
lines changed

Doc/glossary.rst

Lines changed: 25 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -135,11 +135,12 @@ Glossary
135135
:exc:`StopAsyncIteration` exception. Introduced by :pep:`492`.
136136

137137
atomic operation
138-
An operation that completes as a single indivisible unit without
139-
interruption from other threads. Atomic operations are critical for
140-
:term:`thread-safe` programming because they cannot be observed in a
141-
partially completed state by other threads. See also
142-
:term:`race condition` and :term:`data race`.
138+
An operation that appears to execute as a single, indivisible step: no
139+
other thread can observe it half-done, and its effects become visible all
140+
at once. Python does not guarantee that ordinary high-level statements
141+
are atomic (for example, ``x += 1`` performs multiple bytecode operations
142+
and is not atomic). Atomicity is only guaranteed where explicitly
143+
documented. See also :term:`race condition` and :term:`data race`.
143144

144145
attached thread state
145146

@@ -365,15 +366,6 @@ Glossary
365366
:keyword:`async with` keywords. These were introduced
366367
by :pep:`492`.
367368

368-
critical section
369-
A section of code that accesses shared resources and must not be
370-
executed by multiple threads simultaneously. Critical sections are
371-
typically protected using :term:`locks <lock>` or other
372-
:term:`synchronization primitives <synchronization primitive>` to
373-
ensure :term:`thread-safe` access. Critical section are purely a concept
374-
in the C API and are not exposed in Python. See also :term:`lock` and
375-
:term:`race condition`.
376-
377369
CPython
378370
The canonical implementation of the Python programming language, as
379371
distributed on `python.org <https://www.python.org>`_. The term "CPython"
@@ -406,14 +398,15 @@ Glossary
406398
:term:`thread-safe`.
407399

408400
deadlock
409-
A situation where two or more threads are unable to proceed because
410-
each is waiting for the other to release a resource. For example,
411-
if thread A holds lock 1 and waits for lock 2, while thread B holds
412-
lock 2 and waits for lock 1, both threads will wait indefinitely. Any
413-
program that makes blocking calls using more than one lock is possibly
414-
susceptible to deadlocks. Deadlocks can be avoided by always acquiring
415-
multiple :term:`locks <lock>` in a consistent order or by using
416-
timeout-based locking. See also :term:`lock` and :term:`reentrant`.
401+
A situation in which two or more tasks (threads, processes, or coroutines)
402+
wait indefinitely for each other to release resources or complete actions,
403+
preventing any from making progress. For example, if thread A holds lock
404+
1 and waits for lock 2, while thread B holds lock 2 and waits for lock 1,
405+
both threads will wait indefinitely. In Python this often arises from
406+
acquiring multiple locks in conflicting orders or from circular
407+
join/await dependencies. Deadlocks can be avoided by always acquiring
408+
multiple :term:`locks <lock>` in a consistent order. See also
409+
:term:`lock` and :term:`reentrant`.
417410

418411
decorator
419412
A function returning another function, usually applied as a function
@@ -1133,14 +1126,14 @@ Glossary
11331126
See also :term:`regular package` and :term:`namespace package`.
11341127

11351128
parallelism
1136-
The simultaneous execution of operations on multiple processors.
1137-
True parallelism requires multiple processors or processor cores where
1138-
operations run at exactly the same time and are not just interleaved.
1139-
In Python, the :term:`free-threaded <free threading>` build enables
1140-
parallelism for multi-threaded programs that access state stored in the
1141-
interpreter by disabling the :term:`global interpreter lock`. The
1142-
:mod:`multiprocessing` module also enables parallelism by using separate
1143-
processes. See also :term:`concurrency`.
1129+
Executing multiple operations at the same time (e.g. on multiple CPU
1130+
cores). In Python builds with the
1131+
:term:`global interpreter lock (GIL) <global interpreter lock>`, only one
1132+
thread runs Python bytecode at a time, so taking advantage of multiple
1133+
CPU cores typically involves multiple processes
1134+
(e.g. :mod:`multiprocessing`) or native extensions that release the GIL.
1135+
In :term:`free-threaded <free-threading>` Python, multiple Python threads
1136+
can run Python code simultaneously on different cores.
11441137

11451138
parameter
11461139
A named entity in a :term:`function` (or method) definition that
@@ -1545,8 +1538,8 @@ Glossary
15451538
information.
15461539

15471540
thread-safe
1548-
Code that functions correctly when accessed by multiple threads
1549-
concurrently. Thread-safe code uses appropriate
1541+
A module, function, or class that behaves correctly when used by multiple
1542+
threads concurrently. Thread-safe code uses appropriate
15501543
:term:`synchronization primitives <synchronization primitive>` like
15511544
:term:`locks <lock>` to protect shared mutable state, or is designed
15521545
to avoid shared mutable state entirely. In the

0 commit comments

Comments
 (0)