Drop the phrase 'current thread state' and only use 'attached thread …

…state' in its place
python · encukou · Mar 20, 2025 · Dec 14, 2024 · Dec 14, 2024 · Dec 14, 2024
commit 9ed3a0b376066129879af38fd2671a32386bc763
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
@@ -963,8 +963,8 @@ a file, so that other Python threads can run in the meantime.

 The Python interpreter keeps some thread-specific bookkeeping information
 inside a data structure called :c:type:`PyThreadState`, known as a :term:`thread state`.
-There's also one :term:`thread-local variable <current thread state>` pointing to the
-current :c:type:`PyThreadState`: it can be retrieved using :c:func:`PyThreadState_Get`.
+Each OS thread has a thread-local pointer to a :c:type:`PyThreadState`; a thread state
+referenced by this pointer is considered to be :term:`attached <attached thread state>`.

 A thread can only have one :term:`attached thread state` at a time. An attached
 thread state is typically analogous with holding the :term:`GIL`, except on
@@ -1204,14 +1204,13 @@ code, or when embedding the Python interpreter:

 .. c:function:: PyThreadState* PyEval_SaveThread()

-   Detach the :term:`thread state <attached thread state>` and
-   return it. The :term:`current thread state` will be ``NULL`` upon
-   returning.
+   Detach the :term:`attached thread state` and return it.
+   The thread will have no :term:`thread state` upon returning.


 .. c:function:: void PyEval_RestoreThread(PyThreadState *tstate)

-   Set the :term:`current thread state` to *tstate*, which must not be ``NULL``.
+   Set the :term:`attached thread state` to *tstate*.
   The passed :term:`thread state` **should not** be :term:`attached <attached thread state>`,
   otherwise deadlock ensues. *tstate* will be attached upon returning.

@@ -1227,13 +1226,13 @@ code, or when embedding the Python interpreter:

 .. c:function:: PyThreadState* PyThreadState_Get()

-   Return the :term:`current thread state`. If the :term:`current thread state` is ``NULL``
-   (such as when inside of :c:macro:`Py_BEGIN_ALLOW_THREADS` block), then this issues a fatal
-   error (so that the caller needn't check for ``NULL``).
+   Return the :term:`attached thread state`. If the thread has no attached
+   thread state, (such as when inside of :c:macro:`Py_BEGIN_ALLOW_THREADS`
+   block), then this issues a fatal error (so that the caller needn't check
+   for ``NULL``).

   See also :c:func:`PyThreadState_GetUnchecked`.

-
 .. c:function:: PyThreadState* PyThreadState_GetUnchecked()

   Similar to :c:func:`PyThreadState_Get`, but don't kill the process with a
@@ -1247,14 +1246,11 @@ code, or when embedding the Python interpreter:

 .. c:function:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate)

-   Set the :term:`current thread state` to *tstate* (which may be ``NULL``), and return
-   the old value.
+   Set the :term:`attached thread state` to *tstate*, and return the
+   :term:`thread state` that was attached prior to calling.

-   If there is an :term:`attached thread state` for the current
-   thread, it will be detached. Upon returning from this function,
-   *tstate* will become :term:`attached <attached thread state>` instead
-   (if it's not ``NULL``). If it is ``NULL``, then the :term:`current thread state`
-   will be ``NULL``.
+   This function is safe to call without an :term:`attached thread state`; it
+   will simply return ``NULL`` indicating that there was no prior thread state.


 The following functions use thread-local storage, and are not compatible
@@ -1263,7 +1259,7 @@ with sub-interpreters:
 .. c:function:: PyGILState_STATE PyGILState_Ensure()

   Ensure that the current thread is ready to call the Python C API regardless
-   of the current state of Python, or of the :term:`current thread state`. This may
+   of the current state of Python, or of the :term:`attached thread state`. This may
   be called as many times as desired by a thread as long as each call is
   matched with a call to :c:func:`PyGILState_Release`. In general, other
   thread-related APIs may be used between :c:func:`PyGILState_Ensure` and
@@ -1305,11 +1301,13 @@ with sub-interpreters:

 .. c:function:: PyThreadState* PyGILState_GetThisThreadState()

-   Get the :term:`current thread state` for this thread.  May return ``NULL`` if no
+   Get the :term:`attached thread state` for this thread.  May return ``NULL`` if no
   GILState API has been used on the current thread.  Note that the main thread
   always has such a thread-state, even if no auto-thread-state call has been
   made on the main thread.  This is mainly a helper/diagnostic function.

+   .. seealso: PyThreadState_Get
+

 .. c:function:: int PyGILState_Check()

@@ -1420,10 +1418,11 @@ All of the following functions must be called after :c:func:`Py_Initialize`.

 .. c:function:: void PyThreadState_DeleteCurrent(void)

-   Destroy the :term:`attached thread state` and set the :term:`current thread state`
-   to ``NULL``. The :term:`thread state <attached thread state>` must have been reset
-   with a previous call to :c:func:`PyThreadState_Clear`.
+   Detach the :term:`attached thread state` (which must have been reset
+   with a previous call to :c:func:`PyThreadState_Clear`) and then destroy it.

+   No :term:`thread state` will be :term:`attached <attached thread state>` upon
+   returning.

 .. c:function:: PyFrameObject* PyThreadState_GetFrame(PyThreadState *tstate)

@@ -1564,8 +1563,10 @@ All of the following functions must be called after :c:func:`Py_Initialize`.

 .. c:function:: void PyEval_AcquireThread(PyThreadState *tstate)

-   Set the :term:`current thread state` to *tstate*, which must not be ``NULL`` or
-   :term:`attached <attached thread state>`.
+   :term:`Attach <attached thread state>` *tstate* to the current thread,
+   which must not be ``NULL`` or already :term:`attached <attached thread state>`.
+
+   The calling thread must not already have an :term:`attached thread state`.

   .. note::
      Calling this function from a thread when the runtime is finalizing will
@@ -1588,7 +1589,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.

 .. c:function:: void PyEval_ReleaseThread(PyThreadState *tstate)

-   Reset the :term:`current thread state` to ``NULL``.
+   Detach the :term:`attached thread state`.
   The *tstate* argument, which must not be ``NULL``, is only used to check
   that it represents the :term:`attached thread state` --- if it isn't, a fatal error is
   reported.
@@ -1830,7 +1831,7 @@ function. You can create and destroy them using the following functions:

   Destroy the (sub-)interpreter represented by the given :term:`thread state`.
   The given thread state must be :term:`attached <attached thread state>`.
-   When the call returns, the :term:`current thread state` is ``NULL``.
+   When the call returns, there will be no :term:`attached thread state`.
   All thread states associated with this interpreter are destroyed.

   :c:func:`Py_FinalizeEx` will destroy all sub-interpreters that
@@ -1933,12 +1934,9 @@ pointer and a void pointer argument.
   notification recursively, but it can still be interrupted to switch
   threads if the :term:`thread state <attached thread state>` is detached.

-   This function doesn't need a current thread state to run, and it doesn't
-   need an :term:`attached thread state`.
-
-   To call this function in a subinterpreter, the caller must have an
-   :term:`attached thread state`. Otherwise, the function *func* can be scheduled to
-   be called from the wrong interpreter.
+   This function doesn't need an :term:`attached thread state`. However, to call this
+   function in a subinterpreter, the caller must have an :term:`attached thread state`.
+   Otherwise, the function *func* can be scheduled to be called from the wrong interpreter.

   .. warning::
      This is a low-level function, only useful for very special cases.

diff --git a/Doc/c-api/reflection.rst b/Doc/c-api/reflection.rst
@@ -55,7 +55,7 @@ Reflection

 .. c:function:: PyFrameObject* PyEval_GetFrame(void)

-   Return the current thread state's frame, which is ``NULL`` if no frame is
+   Return the :term:`attached thread state`'s frame, which is ``NULL`` if no frame is
   currently executing.

   See also :c:func:`PyThreadState_GetFrame`.

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
@@ -134,18 +134,24 @@ Glossary

   attached thread state

-      A :term:`thread state` that is stored in the :term:`current thread state`.
-      If no thread state is attached, then the :term:`current thread state` is ``NULL``.
-      Attempting to call Python's C API without an attached thread state will result
-      in a fatal error or an undefined behavior.
+      A :term:`thread state` that is active for the current OS thread.

-      A thread state can be attached and detached explicitly by the user, or
-      implicitly by the interpreter in between calls. For example, an attached
-      thread state is detached upon entering a :c:macro:`Py_BEGIN_ALLOW_THREADS`
-      block, and then re-attached when :c:macro:`Py_END_ALLOW_THREADS` is reached.
+      When a :term:`thread state` is attached, the OS thread has
+      access to the full Python C API and can safely invoke the
+      bytecode interpreter.

-      On most builds of Python, having an attached thread state means that the
-      caller holds the :term:`GIL` for the current interpreter.
+      Unless a function explicitly notes otherwise, attempting to call
+      the C API without an attached thread state will result in a fatal
+      error or undefined behavior.  A thread state can be attached and detached
+      explicitly by the user through the C API, or implicitly by the runtime,
+      including during blocking C calls and by the bytecode interpreter in between
+      calls.
+
+      On most builds of Python, having an attached context means that the
+      caller holds the :term:`GIL` for the current interpreter, so only
+      one OS thread can have an attached thread state at a given moment. In
+      :term:`free-threaded <free threading>` builds of Python, threads can concurrently
+      hold an attached thread state, allowing for true parallelism.

   attribute
      A value associated with an object which is usually referenced by name
@@ -348,19 +354,6 @@ Glossary
      tasks (see :mod:`asyncio`) associate each task with a context which
      becomes the current context whenever the task starts or resumes execution.

-   current thread state
-
-      A per-thread :c:data:`PyThreadState` pointer.
-
-      The pointer might be ``NULL``, in which case Python code must not
-      get executed.
-
-      If the current thread state is non-``NULL``, then the :term:`thread state`
-      that it points to is considered to be :term:`attached <attached thread state>`.
-
-      The pointer for the calling thread can be acquired via :c:func:`PyThreadState_Get` or
-      :c:func:`PyThreadState_GetUnchecked`, if it might be ``NULL``.
-
   decorator
      A function returning another function, usually applied as a function
      transformation using the ``@wrapper`` syntax.  Common examples for
@@ -1314,11 +1307,24 @@ Glossary
      :term:`bytes-like objects <bytes-like object>`.

   thread state
-      In Python's C API, a thread state is a structure that holds
-      information about the current thread, typically in the :term:`current thread state`
-      pointer. A thread state can be attached or detached. An :term:`attached thread state`
-      is required to call most of the C API, unless a function explicitly documents
-      otherwise.
+
+      The information used by the :term:`CPython` runtime to run in an OS thread.
+      For example, this includes the current exception, if any, and the
+      state of the bytecode interpreter.
+
+      Each thread state is bound to a single OS thread, but threads may have
+      many thread states available.  At most, one of them may be
+      :term:`attached <attached thread state>` at once.
+
+      An :term:`attached thread state` is required to call most
+      of Python's C API, unless a function explicitly documents otherwise.
+      The bytecode interpreter only runs under an attached thread state.
+
+      Each thread state belongs to a single interpreter, but each interpreter
+      may have many thread states, including multiple for the same OS thread.
+      Thread states from multiple interpreters may be bound to the same
+      thread, but only one can be :term:`attached <attached thread state>` in
+      that thread at any given moment.

      See :ref:`Thread State and the Global Interpreter Lock <threads>` for more
      information.