Add some more terms for disambiguation.

Author: ZeroIntensity

Doc/c-api/dict.rst

@@ -127,7 +127,7 @@ Dictionary Objects
       Prefer the :c:func:`PyDict_GetItemWithError` function instead.
 
    .. versionchanged:: 3.10
-      Calling this API without an active :term:`thread state` had been allowed for historical
+      Calling this API without an :term:`attached thread state` had been allowed for historical
       reason. It is no longer allowed.
 
 

Doc/c-api/exceptions.rst

@@ -413,7 +413,7 @@ Querying the error indicator
    own a reference to the return value, so you do not need to :c:func:`Py_DECREF`
    it.
 
-   The caller must have an active :term:`thread state`.
+   The caller must have an :term:`attached thread state`.
 
    .. note::
 
@@ -675,7 +675,7 @@ Signal Handling
 
    .. note::
       This function is async-signal-safe.  It can be called without
-      an active :term:`thread state` and from a C signal handler.
+      an :term:`attached thread state` and from a C signal handler.
 
 
 .. c:function:: int PyErr_SetInterruptEx(int signum)
@@ -702,7 +702,7 @@ Signal Handling
 
    .. note::
       This function is async-signal-safe.  It can be called without
-      an active :term:`thread state` and from a C signal handler.
+      an :term:`attached thread state` and from a C signal handler.
 
    .. versionadded:: 3.10
 

Doc/c-api/init.rst

@@ -573,7 +573,7 @@ Initializing and finalizing the interpreter
    This is similar to :c:func:`Py_AtExit`, but takes an explicit interpreter and
    data pointer for the callback.
 
-   A :term:`thread state` must be active for *interp*.
+   There must be an :term:`attached thread state` for *interp*.
 
    .. versionadded:: 3.13
 
@@ -1206,7 +1206,7 @@ code, or when embedding the Python interpreter:
 
 .. c:function:: PyThreadState* PyEval_SaveThread()
 
-   Detach the active :term:`thread state` (if it has been created) and
+   Detach the :term:`active thread state` (if it has been created) and
    return it.
 
 
@@ -1228,7 +1228,7 @@ code, or when embedding the Python interpreter:
 
 .. c:function:: PyThreadState* PyThreadState_Get()
 
-   Return the active :term:`thread state`. If there is no active :term:`thread state` (such
+   Return the :term:`active thread state`. If there is no :term:`active 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``).
 
@@ -1278,7 +1278,7 @@ with sub-interpreters:
    unique call to :c:func:`PyGILState_Ensure` must save the handle for its call
    to :c:func:`PyGILState_Release`.
 
-   When the function returns, there will be an active :term:`thread state`
+   When the function returns, there will be an :term:`attached thread state`
    and the thread will be able to call arbitrary Python code.  Failure is a fatal error.
 
    .. note::
@@ -1418,7 +1418,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
 
 .. c:function:: void PyThreadState_DeleteCurrent(void)
 
-   Destroy the active :term:`thread state` and detach it.
+   Destroy the :term:`active thread state` and detach it.
    The current :term:`thread state` must have been reset with a previous call
    to :c:func:`PyThreadState_Clear`.
 
@@ -1482,7 +1482,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
    Issue a fatal error if there no current Python thread state or no current
    interpreter. It cannot return NULL.
 
-   The caller must have an active :term:`thread state`.
+   The caller must have an :term:`attached thread state`.
 
    .. versionadded:: 3.9
 
@@ -1492,7 +1492,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
    Return the interpreter's unique ID.  If there was any error in doing
    so then ``-1`` is returned and an error is set.
 
-   The caller must have an active :term:`thread state`.
+   The caller must have an :term:`attached thread state`.
 
    .. versionadded:: 3.7
 
@@ -1552,7 +1552,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
    Asynchronously raise an exception in a thread. The *id* argument is the thread
    id of the target thread; *exc* is the exception object to be raised. This
    function does not steal any references to *exc*. To prevent naive misuse, you
-   must write your own C extension to call this.  Must be called with an active :term:`thread state`.
+   must write your own C extension to call this.  Must be called with an :term:`attached thread state`.
    Returns the number of thread states modified; this is normally one, but will be
    zero if the thread id isn't found.  If *exc* is ``NULL``, the pending
    exception (if any) for the thread is cleared. This raises no exceptions.
@@ -2084,14 +2084,14 @@ Python-level trace functions in previous versions.
 
    See also the :func:`sys.setprofile` function.
 
-   The caller must have an active :term:`thread state`.
+   The caller must have an :term:`attached thread state`.
 
 .. c:function:: void PyEval_SetProfileAllThreads(Py_tracefunc func, PyObject *obj)
 
    Like :c:func:`PyEval_SetProfile` but sets the profile function in all running threads
    belonging to the current interpreter instead of the setting it only on the current thread.
 
-   The caller must have an active :term:`thread state`.
+   The caller must have an :term:`attached thread state`.
 
    As :c:func:`PyEval_SetProfile`, this function ignores any exceptions raised while
    setting the profile functions in all threads.
@@ -2110,14 +2110,14 @@ Python-level trace functions in previous versions.
 
    See also the :func:`sys.settrace` function.
 
-   The caller must have an active :term:`thread state`.
+   The caller must have an :term:`attached thread state`.
 
 .. c:function:: void PyEval_SetTraceAllThreads(Py_tracefunc func, PyObject *obj)
 
    Like :c:func:`PyEval_SetTrace` but sets the tracing function in all running threads
    belonging to the current interpreter instead of the setting it only on the current thread.
 
-   The caller must have an active :term:`thread state`.
+   The caller must have an :term:`attached thread state`.
 
    As :c:func:`PyEval_SetTrace`, this function ignores any exceptions raised while
    setting the trace functions in all threads.

Doc/c-api/init_config.rst

@@ -1893,7 +1893,7 @@ Some options are read from the :mod:`sys` attributes. For example, the option
    * ``list[str]``
    * ``dict[str, str]``
 
-   The caller must have an active :term:`thread state`. The function cannot
+   The caller must have an :term:`attached thread state`. The function cannot
    be called before Python initialization nor after Python finalization.
 
    .. versionadded:: 3.14
@@ -1916,7 +1916,7 @@ Some options are read from the :mod:`sys` attributes. For example, the option
    * Return a new reference on success.
    * Set an exception and return ``NULL`` on error.
 
-   The caller must have an active :term:`thread state`. The function cannot
+   The caller must have an :term:`attached thread state`. The function cannot
    be called before Python initialization nor after Python finalization.
 
    .. versionadded:: 3.14
@@ -1931,7 +1931,7 @@ Some options are read from the :mod:`sys` attributes. For example, the option
    * Raise a :exc:`ValueError` if the option is read-only (cannot be set).
    * Raise a :exc:`TypeError` if *value* has not the proper type.
 
-   The caller must have an active :term:`thread state`. The function cannot
+   The caller must have an :term:`attached thread state`. The function cannot
    be called before Python initialization nor after Python finalization.
 
    .. versionadded:: 3.14

Doc/c-api/memory.rst

@@ -110,12 +110,12 @@ The three allocation domains are:
 
 * Raw domain: intended for allocating memory for general-purpose memory
   buffers where the allocation *must* go to the system allocator or where the
-  allocator can operate without an active :term:`thread state`. The memory
+  allocator can operate without an :term:`attached thread state`. The memory
   is requested directly from the system. See :ref:`Raw Memory Interface <raw-memoryinterface>`.
 
 * "Mem" domain: intended for allocating memory for Python buffers and
   general-purpose memory buffers where the allocation must be performed with
-  an active :term:`thread state`. The memory is taken from the Python private heap.
+  an :term:`attached thread state`. The memory is taken from the Python private heap.
   See :ref:`Memory Interface <memoryinterface>`.
 
 * Object domain: intended for allocating memory for Python objects. The
@@ -506,7 +506,7 @@ Customize Memory Allocators
          :c:func:`Py_InitializeFromConfig` to install a custom memory
          allocator. There are no restrictions over the installed allocator
          other than the ones imposed by the domain (for instance, the Raw
-         Domain allows the allocator to be called without an active :term:`thread state`).
+         Domain allows the allocator to be called without an :term:`attached thread state`).
          See :ref:`the section on allocator domains <allocator-domains>` for more
          information.
 

Doc/c-api/module.rst

@@ -708,7 +708,7 @@ since multiple such modules can be created from a single definition.
    mechanisms (either by calling it directly, or by referring to its
    implementation for details of the required state updates).
 
-   The caller must have an active :term:`thread state`.
+   The caller must have an :term:`attached thread state`.
 
    Return ``-1`` with an exception set on error, ``0`` on success.
 
@@ -719,6 +719,6 @@ since multiple such modules can be created from a single definition.
    Removes the module object created from *def* from the interpreter state.
    Return ``-1`` with an exception set on error, ``0`` on success.
 
-   The caller must have an active :term:`thread state`.
+   The caller must have an :term:`attached thread state`.
 
    .. versionadded:: 3.3

Doc/c-api/perfmaps.rst

@@ -16,7 +16,7 @@ kernel/git/torvalds/linux.git/tree/tools/perf/Documentation/jit-interface.txt>`_
 In Python, these helper APIs can be used by libraries and features that rely
 on generating machine code on the fly.
 
-Note that holding an active :term:`thread state` is not required for these APIs.
+Note that holding an :term:`attached thread state` is not required for these APIs.
 
 .. c:function:: int PyUnstable_PerfMapState_Init(void)
 

Doc/c-api/time.rst

@@ -56,7 +56,7 @@ range.
 system time.)
 
 As any other C API (unless otherwise specified), the functions must be called
-with an active :term:`thread state`.
+with an :term:`attached thread state`.
 
 .. c:function:: int PyTime_Monotonic(PyTime_t *result)
 
@@ -78,7 +78,7 @@ Raw Clock Functions
 -------------------
 
 Similar to clock functions, but don't set an exception on error and don't
-require the caller to have an active :term:`thread state`.
+require the caller to have an :term:`attached thread state`.
 
 On success, the functions return ``0``.
 
@@ -90,17 +90,17 @@ the ``Raw`` one failed.
 .. c:function:: int PyTime_MonotonicRaw(PyTime_t *result)
 
    Similar to :c:func:`PyTime_Monotonic`,
-   but don't set an exception on error and don't require an active :term:`thread state`.
+   but don't set an exception on error and don't require an :term:`attached thread state`.
 
 .. c:function:: int PyTime_PerfCounterRaw(PyTime_t *result)
 
    Similar to :c:func:`PyTime_PerfCounter`,
-   but don't set an exception on error and don't require an active :term:`thread state`.
+   but don't set an exception on error and don't require an :term:`attached thread state`.
 
 .. c:function:: int PyTime_TimeRaw(PyTime_t *result)
 
    Similar to :c:func:`PyTime_Time`,
-   but don't set an exception on error and don't require an active :term:`thread state`.
+   but don't set an exception on error and don't require an :term:`attached thread state`.
 
 
 Conversion functions

Doc/c-api/typeobj.rst

@@ -689,7 +689,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
       object becomes part of a refcount cycle, that cycle might be collected by
       a garbage collection on any thread).  This is not a problem for Python
       API calls, since the thread on which :c:member:`!tp_dealloc` is called
-      with an active :term:`thread state`.  However, if the object being
+      with an :term:`attached thread state`.  However, if the object being
       destroyed in turn destroys objects from some other C or C++ library, care
       should be taken to ensure that destroying those objects on the thread
       which called :c:member:`!tp_dealloc` will not violate any assumptions of

Doc/glossary.rst

@@ -36,6 +36,13 @@ Glossary
       and loaders (in the :mod:`importlib.abc` module).  You can create your own
       ABCs with the :mod:`abc` module.
 
+   active thread state
+
+      The :c:data:`PyThreadState` pointer to a :term:`thread state` for the current thread.
+      The per-thread pointer might be ``NULL``, in which case Python code should not
+      get executed. If the active thread state is non-``NULL``, then the :term:`thread state`
+      that it points to is considered to be :term:`attached <attached thread state>`.  
+
    annotate function
       A function that can be called to retrieve the :term:`annotations <annotation>`
       of an object. This function is accessible as the :attr:`~object.__annotate__`
@@ -132,6 +139,14 @@ Glossary
       iterator's :meth:`~object.__anext__` method until it raises a
       :exc:`StopAsyncIteration` exception.  Introduced by :pep:`492`.
 
+   attached thread state
+
+      A :term:`thread state` that is :term:`active <active thread state>`
+      for the current thread.
+
+      On most builds of Python, an attached thread state means that the
+      caller holds the :term:`GIL` for the current interpreter.    
+
    attribute
       A value associated with an object which is usually referenced by name
       using dotted expressions.
@@ -1288,12 +1303,7 @@ Glossary
    thread state
       In Python's C API, a thread state is a structure that holds
       information about the current thread. A thread state must be
-      active for the current thread in order to call most of the C API.
-
-      On most builds of Python, an attached thread state means that the
-      caller holds the :term:`GIL` for the current interpreter, but on
-      :term:`free-threaded <free-threading>` builds, multiple thread states
-      can be active at once.
+      :term:`active <active thread state>` for the current thread in order to call most of the C API.
 
       See :ref:`Thread State and the Global Interpreter Lock <threads>` for more
       information.