From 3782e3a9ef7dc707a91481f3d8aa6c00d862bdfd Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 5 Sep 2024 12:15:52 +0000 Subject: [PATCH 01/21] Clarify the usage of PyGILState* for subinterpreters. --- Doc/c-api/init.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 561c8a1b879bae..6080a538148d21 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -919,8 +919,10 @@ from a C thread is:: Note that the ``PyGILState_*`` functions assume there is only one global interpreter (created automatically by :c:func:`Py_Initialize`). Python supports the creation of additional interpreters (using -:c:func:`Py_NewInterpreter`), but mixing multiple interpreters and the -``PyGILState_*`` API is unsupported. +:c:func:`Py_NewInterpreter`), but switching between interpreters via the +``PyGILState_*`` API is unsupported. With that being said, you still need +to hold the :term:`GIL` in order to _create_ a subinterpreter, even if +using a per-interpreter GIL (see :pep:`684`). .. _fork-and-threads: From 77df9e7d23393eca5686cd082c6470528140b03c Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 5 Sep 2024 12:22:31 +0000 Subject: [PATCH 02/21] Add extra sentence --- Doc/c-api/init.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 6080a538148d21..091f5a57a7dd4d 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -920,9 +920,10 @@ Note that the ``PyGILState_*`` functions assume there is only one global interpreter (created automatically by :c:func:`Py_Initialize`). Python supports the creation of additional interpreters (using :c:func:`Py_NewInterpreter`), but switching between interpreters via the -``PyGILState_*`` API is unsupported. With that being said, you still need -to hold the :term:`GIL` in order to _create_ a subinterpreter, even if -using a per-interpreter GIL (see :pep:`684`). +``PyGILState_*`` API is unsupported. With that being said, you still need +to hold the :term:`GIL` in order to _create_ a subinterpreter, even if using +a per-interpreter GIL (see :pep:`684`). The need for :c:expr:`PyGILState_STATE` +doesn't go away when creating isolated subinterpreters! .. _fork-and-threads: From bd2681f3d3da5c4f285de8b0b428ddf925f08683 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 5 Sep 2024 12:28:17 +0000 Subject: [PATCH 03/21] Switch to Sphinx type instead of expr --- 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 091f5a57a7dd4d..429421f97ccd03 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -922,7 +922,7 @@ supports the creation of additional interpreters (using :c:func:`Py_NewInterpreter`), but switching between interpreters via the ``PyGILState_*`` API is unsupported. With that being said, you still need to hold the :term:`GIL` in order to _create_ a subinterpreter, even if using -a per-interpreter GIL (see :pep:`684`). The need for :c:expr:`PyGILState_STATE` +a per-interpreter GIL (see :pep:`684`). The need for :c:type:`PyGILState_STATE` doesn't go away when creating isolated subinterpreters! From 858c499cbcf21440cc168298fa2b20727ad2d1a3 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 5 Sep 2024 12:36:23 +0000 Subject: [PATCH 04/21] Fix italics. --- 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 429421f97ccd03..6dc86d51feb953 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -921,7 +921,7 @@ interpreter (created automatically by :c:func:`Py_Initialize`). Python supports the creation of additional interpreters (using :c:func:`Py_NewInterpreter`), but switching between interpreters via the ``PyGILState_*`` API is unsupported. With that being said, you still need -to hold the :term:`GIL` in order to _create_ a subinterpreter, even if using +to hold the :term:`GIL` in order to *create* a subinterpreter, even if using a per-interpreter GIL (see :pep:`684`). The need for :c:type:`PyGILState_STATE` doesn't go away when creating isolated subinterpreters! From eb56367d6225ea63a8a0663024a0a9059daa3ac1 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 5 Sep 2024 19:44:31 -0400 Subject: [PATCH 05/21] Update Doc/c-api/init.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- Doc/c-api/init.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 6dc86d51feb953..780acfee059588 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -920,10 +920,9 @@ Note that the ``PyGILState_*`` functions assume there is only one global interpreter (created automatically by :c:func:`Py_Initialize`). Python supports the creation of additional interpreters (using :c:func:`Py_NewInterpreter`), but switching between interpreters via the -``PyGILState_*`` API is unsupported. With that being said, you still need -to hold the :term:`GIL` in order to *create* a subinterpreter, even if using -a per-interpreter GIL (see :pep:`684`). The need for :c:type:`PyGILState_STATE` -doesn't go away when creating isolated subinterpreters! +``PyGILState_*`` API is unsupported. On the other hand, *creating* +sub-interpreters (whether they have a per-interprter GIL or not in +the sense of :pep:`684`) still require to hold the :term:`GIL`. .. _fork-and-threads: From 40dbd18e0a44f1494426a520570d721284e7719f Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 5 Sep 2024 19:48:53 -0400 Subject: [PATCH 06/21] Fix typo. --- Doc/c-api/init.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 780acfee059588..a660bc765d0557 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -921,8 +921,8 @@ interpreter (created automatically by :c:func:`Py_Initialize`). Python supports the creation of additional interpreters (using :c:func:`Py_NewInterpreter`), but switching between interpreters via the ``PyGILState_*`` API is unsupported. On the other hand, *creating* -sub-interpreters (whether they have a per-interprter GIL or not in -the sense of :pep:`684`) still require to hold the :term:`GIL`. +sub-interpreters (whether they have a per-interpreter :term:`GIL` or not in +the sense of :pep:`684`) still require to hold the GIL. .. _fork-and-threads: From eedefd8cc7c32dd9195021db34b62428f9fc3199 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Thu, 5 Sep 2024 19:52:48 -0400 Subject: [PATCH 07/21] Update init.rst --- 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 a660bc765d0557..30ab0fe03f416b 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -921,7 +921,7 @@ interpreter (created automatically by :c:func:`Py_Initialize`). Python supports the creation of additional interpreters (using :c:func:`Py_NewInterpreter`), but switching between interpreters via the ``PyGILState_*`` API is unsupported. On the other hand, *creating* -sub-interpreters (whether they have a per-interpreter :term:`GIL` or not in +sub-interpreters (whether they have a per-interpreter GIL or not, in the sense of :pep:`684`) still require to hold the GIL. From 58be1c856fe901168fd3e654c2e7a76534458149 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Fri, 6 Sep 2024 12:18:12 -0400 Subject: [PATCH 08/21] Update Doc/c-api/init.rst Co-authored-by: Petr Viktorin --- Doc/c-api/init.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 30ab0fe03f416b..e7a794695dcb4b 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -920,9 +920,7 @@ Note that the ``PyGILState_*`` functions assume there is only one global interpreter (created automatically by :c:func:`Py_Initialize`). Python supports the creation of additional interpreters (using :c:func:`Py_NewInterpreter`), but switching between interpreters via the -``PyGILState_*`` API is unsupported. On the other hand, *creating* -sub-interpreters (whether they have a per-interpreter GIL or not, in -the sense of :pep:`684`) still require to hold the GIL. +``PyGILState_*`` API is unsupported. .. _fork-and-threads: From 76d90d830dd2b7dcd2cbd0f291fea94cb72a117b Mon Sep 17 00:00:00 2001 From: ZeroIntensity Date: Sat, 7 Sep 2024 10:39:46 -0400 Subject: [PATCH 09/21] Clarify usage of what interpreter you end up in with PyGILState_Ensure --- Doc/c-api/init.rst | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index e7a794695dcb4b..ead123767865f3 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -920,7 +920,9 @@ Note that the ``PyGILState_*`` functions assume there is only one global interpreter (created automatically by :c:func:`Py_Initialize`). Python supports the creation of additional interpreters (using :c:func:`Py_NewInterpreter`), but switching between interpreters via the -``PyGILState_*`` API is unsupported. +``PyGILState_*`` API is unsupported. If you call ``PyGILState_Ensure`` +in order to create a sub-interpreter, you must never try and interact +with the GIL of other interpreters. .. _fork-and-threads: @@ -1091,6 +1093,13 @@ with sub-interpreters: When the function returns, the current thread will hold the GIL and be able to call arbitrary Python code. Failure is a fatal error. + If sub-interpreters are active, this function puts you in the global + interpreter (created by :c:func:`Py_Initialize`). If you create a sub-interpreter + right after you call this function, then the current thread is switched to that + sub-interpreter, and you no longer have the :c:type:`PyGILState_STATE` of the global + interpreter. In which case, you must call :c:func:`Py_EndInterpreter` instead of + :c:func:`PyGILState_Release`. + .. note:: Calling this function from a thread when the runtime is finalizing will terminate the thread, even if the thread was not created by Python. From e7be1ad6e7042824cca587302d13c216b5472284 Mon Sep 17 00:00:00 2001 From: ZeroIntensity Date: Sat, 7 Sep 2024 10:44:11 -0400 Subject: [PATCH 10/21] More clarification. --- 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 ead123767865f3..117b6a9c4fbf15 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -922,7 +922,8 @@ supports the creation of additional interpreters (using :c:func:`Py_NewInterpreter`), but switching between interpreters via the ``PyGILState_*`` API is unsupported. If you call ``PyGILState_Ensure`` in order to create a sub-interpreter, you must never try and interact -with the GIL of other interpreters. +with the GIL of other interpreters (including trying to release the GIL +to return back to the previous interpreter). .. _fork-and-threads: From adbef3af0fc2bf34db7c067971ffa4d37b23b0f0 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sat, 7 Sep 2024 13:25:24 -0400 Subject: [PATCH 11/21] Update Doc/c-api/init.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- Doc/c-api/init.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 117b6a9c4fbf15..a5ed8c2c3f856f 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -920,10 +920,11 @@ Note that the ``PyGILState_*`` functions assume there is only one global interpreter (created automatically by :c:func:`Py_Initialize`). Python supports the creation of additional interpreters (using :c:func:`Py_NewInterpreter`), but switching between interpreters via the -``PyGILState_*`` API is unsupported. If you call ``PyGILState_Ensure`` -in order to create a sub-interpreter, you must never try and interact -with the GIL of other interpreters (including trying to release the GIL -to return back to the previous interpreter). +``PyGILState_*`` API is unsupported. Similiarly, after creating a +sub-interpreter via :c:func:`!PyGILState_Ensure`, interacting with +the GIL of other interpreters (including, but not limited to trying +to release the GIL to return back to the previous interpreter) is not +supported. .. _fork-and-threads: From 46060a7b5de504867e0200034c2f27a3e10788fc Mon Sep 17 00:00:00 2001 From: ZeroIntensity Date: Sat, 7 Sep 2024 13:28:28 -0400 Subject: [PATCH 12/21] Clarify the phrase 'current thread' --- Doc/c-api/init.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 117b6a9c4fbf15..38ceefe4a0a590 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1096,10 +1096,10 @@ with sub-interpreters: If sub-interpreters are active, this function puts you in the global interpreter (created by :c:func:`Py_Initialize`). If you create a sub-interpreter - right after you call this function, then the current thread is switched to that - sub-interpreter, and you no longer have the :c:type:`PyGILState_STATE` of the global - interpreter. In which case, you must call :c:func:`Py_EndInterpreter` instead of - :c:func:`PyGILState_Release`. + right after you call this function, then the current thread's interpreter state is + switched to of that of the sub-interpreter, and you no longer have the + :c:type:`PyGILState_STATE` of the global interpreter. In which case, you must call + :c:func:`Py_EndInterpreter` instead of :c:func:`PyGILState_Release`. .. note:: Calling this function from a thread when the runtime is finalizing From 426cb079015935e5424b87a2e5342c54f8e0d915 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sat, 7 Sep 2024 13:30:54 -0400 Subject: [PATCH 13/21] Fix typo. --- 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 bbe21a1c9ffce1..72fe02745c79a0 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1098,7 +1098,7 @@ with sub-interpreters: If sub-interpreters are active, this function puts you in the global interpreter (created by :c:func:`Py_Initialize`). If you create a sub-interpreter right after you call this function, then the current thread's interpreter state is - switched to of that of the sub-interpreter, and you no longer have the + switched to that of the sub-interpreter, and you no longer have the :c:type:`PyGILState_STATE` of the global interpreter. In which case, you must call :c:func:`Py_EndInterpreter` instead of :c:func:`PyGILState_Release`. From a83eab2c5afff7c3ee515037562552c4ddaefad9 Mon Sep 17 00:00:00 2001 From: ZeroIntensity Date: Sat, 7 Sep 2024 19:38:58 -0400 Subject: [PATCH 14/21] Clarify what PyGILState_Ensure() does for a sub-interpreter --- Doc/c-api/init.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index bbe21a1c9ffce1..a5df4be23c6d60 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1078,8 +1078,11 @@ with sub-interpreters: Ensure that the current thread is ready to call the Python C API regardless of the current state of Python, or of the global interpreter lock. 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 + matched with a call to :c:func:`PyGILState_Release`, *except* when the + thread creates a sub-interpreter with it's own :term:`GIL` (see :c:member:`PyInterpreterConfig.gil`). + In that case, the call to :c:func:`PyGILState_Release` should be replaced with :c:func:`Py_EndInterpreter`. + + In general, other thread-related APIs may be used between :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` calls as long as the thread state is restored to its previous state before the Release(). For example, normal usage of the :c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS` macros is @@ -1095,12 +1098,7 @@ with sub-interpreters: When the function returns, the current thread will hold the GIL and be able to call arbitrary Python code. Failure is a fatal error. - If sub-interpreters are active, this function puts you in the global - interpreter (created by :c:func:`Py_Initialize`). If you create a sub-interpreter - right after you call this function, then the current thread's interpreter state is - switched to of that of the sub-interpreter, and you no longer have the - :c:type:`PyGILState_STATE` of the global interpreter. In which case, you must call - :c:func:`Py_EndInterpreter` instead of :c:func:`PyGILState_Release`. + If no interpreter state has been initialized for the thread, then this function returns the state of the global interpreter (created by :c:func:`Py_Initialize`). .. note:: Calling this function from a thread when the runtime is finalizing From 6036f65e7ae07aba277381c4c216e1f951b88b47 Mon Sep 17 00:00:00 2001 From: ZeroIntensity Date: Sat, 7 Sep 2024 19:41:24 -0400 Subject: [PATCH 15/21] Add line break. --- 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 a5df4be23c6d60..e680d08bca1954 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1098,7 +1098,8 @@ with sub-interpreters: When the function returns, the current thread will hold the GIL and be able to call arbitrary Python code. Failure is a fatal error. - If no interpreter state has been initialized for the thread, then this function returns the state of the global interpreter (created by :c:func:`Py_Initialize`). + If no interpreter state has been initialized for the thread, then this function returns + the state of the global interpreter (created by :c:func:`Py_Initialize`). .. note:: Calling this function from a thread when the runtime is finalizing From edfd150a1d105ad5301abcef3b1652ccc3157f98 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sun, 8 Sep 2024 10:12:01 -0400 Subject: [PATCH 16/21] Update init.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- 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 e680d08bca1954..72c594775b0b48 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -922,7 +922,7 @@ supports the creation of additional interpreters (using :c:func:`Py_NewInterpreter`), but switching between interpreters via the ``PyGILState_*`` API is unsupported. Similiarly, after creating a sub-interpreter via :c:func:`!PyGILState_Ensure`, interacting with -the GIL of other interpreters (including, but not limited to trying +the GIL of other interpreters (including, but not limited to, trying to release the GIL to return back to the previous interpreter) is not supported. From f24b5716ecc32dcb04e8ad5a506e84f43e701efa Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sun, 8 Sep 2024 10:12:07 -0400 Subject: [PATCH 17/21] Update init.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- 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 72c594775b0b48..d999b0545290d7 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1079,7 +1079,8 @@ with sub-interpreters: of the current state of Python, or of the global interpreter lock. 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`, *except* when the - thread creates a sub-interpreter with it's own :term:`GIL` (see :c:member:`PyInterpreterConfig.gil`). + thread creates a sub-interpreter with its own GIL (see + :c:member:`PyInterpreterConfig.gil`). In that case, the call to :c:func:`PyGILState_Release` should be replaced with :c:func:`Py_EndInterpreter`. In general, other thread-related APIs may be used between :c:func:`PyGILState_Ensure` and From 93d90ad11cc1dd0784d035ae0f0444bad4483087 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Sun, 8 Sep 2024 10:12:35 -0400 Subject: [PATCH 18/21] Update init.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- 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 d999b0545290d7..e7ae58ad3b38aa 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1081,7 +1081,8 @@ with sub-interpreters: matched with a call to :c:func:`PyGILState_Release`, *except* when the thread creates a sub-interpreter with its own GIL (see :c:member:`PyInterpreterConfig.gil`). - In that case, the call to :c:func:`PyGILState_Release` should be replaced with :c:func:`Py_EndInterpreter`. + In that case, :c:func:`PyGILState_Release` should be used instead of + :c:func:`Py_EndInterpreter` to release that interpreter's GIL. In general, other thread-related APIs may be used between :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` calls as long as the thread state is restored to From cbbe23599775cf1645907981a0b3e3700737cbc3 Mon Sep 17 00:00:00 2001 From: ZeroIntensity Date: Sun, 8 Sep 2024 10:59:28 -0400 Subject: [PATCH 19/21] Swap Py_EndInterpreter and PyGILState_Release --- Doc/c-api/init.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index e7ae58ad3b38aa..f6664c02ea8633 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -1081,8 +1081,8 @@ with sub-interpreters: matched with a call to :c:func:`PyGILState_Release`, *except* when the thread creates a sub-interpreter with its own GIL (see :c:member:`PyInterpreterConfig.gil`). - In that case, :c:func:`PyGILState_Release` should be used instead of - :c:func:`Py_EndInterpreter` to release that interpreter's GIL. + In that case, :c:func:`Py_EndInterpreter` should be used instead to + release that interpreter's GIL. In general, other thread-related APIs may be used between :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` calls as long as the thread state is restored to From a432e770f40ee09be1e7b79c0bc251e27f9bfb52 Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Mon, 9 Sep 2024 14:51:56 -0400 Subject: [PATCH 20/21] Update init.rst Co-authored-by: Savannah Ostrowski --- 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 f6664c02ea8633..cc265d37098d68 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -920,7 +920,7 @@ Note that the ``PyGILState_*`` functions assume there is only one global interpreter (created automatically by :c:func:`Py_Initialize`). Python supports the creation of additional interpreters (using :c:func:`Py_NewInterpreter`), but switching between interpreters via the -``PyGILState_*`` API is unsupported. Similiarly, after creating a +``PyGILState_*`` API is unsupported. Similarly, after creating a sub-interpreter via :c:func:`!PyGILState_Ensure`, interacting with the GIL of other interpreters (including, but not limited to, trying to release the GIL to return back to the previous interpreter) is not From f11b7fc79f76c04868255d634c6c4457e47653da Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Tue, 24 Sep 2024 10:27:02 -0400 Subject: [PATCH 21/21] Remove excerpt from `PyGILState_Ensure` and shorten wording --- Doc/c-api/init.rst | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index cc265d37098d68..b3640abef846ad 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -922,7 +922,7 @@ supports the creation of additional interpreters (using :c:func:`Py_NewInterpreter`), but switching between interpreters via the ``PyGILState_*`` API is unsupported. Similarly, after creating a sub-interpreter via :c:func:`!PyGILState_Ensure`, interacting with -the GIL of other interpreters (including, but not limited to, trying +the GIL of other interpreters (such as trying to release the GIL to return back to the previous interpreter) is not supported. @@ -1078,11 +1078,7 @@ with sub-interpreters: Ensure that the current thread is ready to call the Python C API regardless of the current state of Python, or of the global interpreter lock. 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`, *except* when the - thread creates a sub-interpreter with its own GIL (see - :c:member:`PyInterpreterConfig.gil`). - In that case, :c:func:`Py_EndInterpreter` should be used instead to - release that interpreter's GIL. + matched with a call to :c:func:`PyGILState_Release` In general, other thread-related APIs may be used between :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` calls as long as the thread state is restored to