From 74f445f5a61588fc99b68cd35ca0b7f37a0f5eb2 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Thu, 9 Oct 2025 10:34:35 +0100 Subject: [PATCH 1/3] [3.13] gh-101100: Fix reference warnings in `c-api/init.rst` documenting `PyGILState_STATE` (GH-139572) (cherry picked from commit d2deb8fdef1ac5e54564448677cdb1522f1b776d) Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> --- Doc/c-api/init.rst | 18 ++++++++++++++++-- Doc/tools/.nitignore | 1 - 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 6a6d35d3ac568c..8f3d0b55c544f9 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1225,9 +1225,23 @@ code, or when embedding the Python interpreter: The :term:`GIL` does not need to be held, but will be held upon returning if *tstate* is non-``NULL``. + The following functions use thread-local storage, and are not compatible with sub-interpreters: +.. c:type:: PyGILState_STATE + + The type of the value returned by :c:func:`PyGILState_Ensure` and passed to + :c:func:`PyGILState_Release`. + + .. c:enumerator:: PyGILState_LOCKED + + The GIL was already held when :c:func:`PyGILState_Ensure` was called. + + .. c:enumerator:: PyGILState_UNLOCKED + + The GIL was not held when :c:func:`PyGILState_Ensure` was called. + .. c:function:: PyGILState_STATE PyGILState_Ensure() Ensure that the current thread is ready to call the Python C API regardless @@ -1372,11 +1386,11 @@ All of the following functions must be called after :c:func:`Py_Initialize`. must be held. .. versionchanged:: 3.9 - This function now calls the :c:member:`PyThreadState.on_delete` callback. + This function now calls the :c:member:`!PyThreadState.on_delete` callback. Previously, that happened in :c:func:`PyThreadState_Delete`. .. versionchanged:: 3.13 - The :c:member:`PyThreadState.on_delete` callback was removed. + The :c:member:`!PyThreadState.on_delete` callback was removed. .. c:function:: void PyThreadState_Delete(PyThreadState *tstate) diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 5974339ac28df4..8b9a88bd8a774c 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -4,7 +4,6 @@ Doc/c-api/descriptor.rst Doc/c-api/float.rst -Doc/c-api/init.rst Doc/c-api/init_config.rst Doc/c-api/intro.rst Doc/c-api/module.rst From 1461373a7ac11a356eee68fbdb860f69876ecfd5 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Date: Thu, 9 Oct 2025 10:53:39 +0100 Subject: [PATCH 2/3] Remove spurious newline --- Doc/c-api/init.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 8f3d0b55c544f9..d4e527681c54ea 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1225,7 +1225,6 @@ code, or when embedding the Python interpreter: The :term:`GIL` does not need to be held, but will be held upon returning if *tstate* is non-``NULL``. - The following functions use thread-local storage, and are not compatible with sub-interpreters: From caee81be8424f1ab7f0096b25539420829f551fe Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Thu, 9 Oct 2025 10:58:52 +0100 Subject: [PATCH 3/3] Remove the link --- Doc/c-api/init.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 8f3d0b55c544f9..1496f0ca7ae838 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1094,7 +1094,7 @@ acquire the :term:`GIL`. If any thread, other than the finalization thread, attempts to acquire the GIL during finalization, either explicitly via :c:func:`PyGILState_Ensure`, :c:macro:`Py_END_ALLOW_THREADS`, :c:func:`PyEval_AcquireThread`, or -:c:func:`PyEval_AcquireLock`, or implicitly when the interpreter attempts to +:c:func:`!PyEval_AcquireLock`, or implicitly when the interpreter attempts to reacquire it after having yielded it, the thread enters **a permanently blocked state** where it remains until the program exits. In most cases this is harmless, but this can result in deadlock if a later stage of finalization