From 4e53a837f679990fcf2b1286cbadd8dc19da5683 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 4 Oct 2025 17:30:02 +0100 Subject: [PATCH 1/6] Commit --- Doc/c-api/init.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index ccf85e627f9b5f..54943660cc3309 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1113,7 +1113,7 @@ code, or when embedding the Python interpreter: 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. - .. seealso: + .. seealso:: :c:func:`PyEval_ReleaseThread` .. note:: @@ -1124,6 +1124,12 @@ code, or when embedding the Python interpreter: The following functions use thread-local storage, and are not compatible with sub-interpreters: +.. c:type:: PyGILState_STATE + + A handle to the thread state when :c:func:`PyGILState_Ensure` was + called, and must be passed to :c:func:`PyGILState_Release` to ensure Python + is left in the same state. + .. c:function:: PyGILState_STATE PyGILState_Ensure() Ensure that the current thread is ready to call the Python C API regardless @@ -1179,7 +1185,7 @@ with sub-interpreters: Prefer :c:func:`PyThreadState_Get` or :c:func:`PyThreadState_GetUnchecked` for most cases. - .. seealso: :c:func:`PyThreadState_Get`` + .. seealso:: :c:func:`PyThreadState_Get`` .. c:function:: int PyGILState_Check() @@ -1278,11 +1284,11 @@ All of the following functions must be called after :c:func:`Py_Initialize`. must be :term:`attached ` .. 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) From 789fe329b6363dac2871ebb1d3f59acd13432fc6 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 4 Oct 2025 17:32:08 +0100 Subject: [PATCH 2/6] Commit --- Doc/tools/.nitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 0ee92dce43790b..820dfda1334f12 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 b65b0b6d162e5ef389338772d23c7c0f0f5a4adf Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 4 Oct 2025 17:33:37 +0100 Subject: [PATCH 3/6] Commit --- Doc/c-api/init.rst | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 54943660cc3309..73fbd87d26f90e 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1126,9 +1126,16 @@ with sub-interpreters: .. c:type:: PyGILState_STATE - A handle to the thread state when :c:func:`PyGILState_Ensure` was - called, and must be passed to :c:func:`PyGILState_Release` to ensure Python - is left in the same 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() From 807bcdebc58e8fe226bfb1561d325cbcd6796c39 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 4 Oct 2025 17:51:41 +0100 Subject: [PATCH 4/6] Fix seealso content --- 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 73fbd87d26f90e..7b87e50543c1f8 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1192,7 +1192,7 @@ with sub-interpreters: Prefer :c:func:`PyThreadState_Get` or :c:func:`PyThreadState_GetUnchecked` for most cases. - .. seealso:: :c:func:`PyThreadState_Get`` + .. seealso:: :c:func:`PyThreadState_Get` .. c:function:: int PyGILState_Check() From 6e4b429df2863cf20d848977b2cc446adb9f5908 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 4 Oct 2025 18:05:41 +0100 Subject: [PATCH 5/6] Additional bonus issue for Peter --- Doc/c-api/init.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 7b87e50543c1f8..d4f99d99093fa1 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1187,7 +1187,8 @@ with sub-interpreters: made on the main thread. This is mainly a helper/diagnostic function. .. note:: - This function does not account for :term:`thread states ` created + This function may return non-``NULL`` even when the :term:`thread state` + is detached. by something other than :c:func:`PyGILState_Ensure` (such as :c:func:`PyThreadState_New`). Prefer :c:func:`PyThreadState_Get` or :c:func:`PyThreadState_GetUnchecked` for most cases. From 978365829b41dd486b8ad01d38e16ccd508bedec Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sat, 4 Oct 2025 18:06:03 +0100 Subject: [PATCH 6/6] !fixup --- 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 d4f99d99093fa1..7a501ea22be64b 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1189,7 +1189,6 @@ with sub-interpreters: .. note:: This function may return non-``NULL`` even when the :term:`thread state` is detached. - by something other than :c:func:`PyGILState_Ensure` (such as :c:func:`PyThreadState_New`). Prefer :c:func:`PyThreadState_Get` or :c:func:`PyThreadState_GetUnchecked` for most cases.