Drop the phrase 'current thread state' and only use 'attached thread state' in its place

Author: ZeroIntensity

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.

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`.

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.