@@ -919,8 +919,36 @@ Note that the ``PyGILState_*`` functions assume there is only one global
919919interpreter (created automatically by :c:func:`Py_Initialize`). Python
920920supports the creation of additional interpreters (using
921921:c:func:`Py_NewInterpreter`), but mixing multiple interpreters and the
922- ``PyGILState_*`` API is unsupported.
922+ ``PyGILState_*`` API is unsupported. This is because :c:func:`PyGILState_Ensure`
923+ and similar functions default to :term:`attaching <attached thread state>` a
924+ :term:`thread state` for the main interpreter, meaning that the thread can't safely
925+ interact with the calling subinterpreter.
926+
927+ Supporting subinterpreters in non-Python threads
928+ ------------------------------------------------
929+
930+ If you would like to support subinterpreters with non-Python created threads, you
931+ must use the ``PyThreadState_*`` API instead of the traditional ``PyGILState_*``
932+ API.
933+
934+ In particular, you must store the interpreter state from the calling
935+ function and pass it to :c:func:`PyThreadState_New`, which will ensure that
936+ the :term:`thread state` is targeting the correct interpreter::
937+
938+ /* The return value of PyInterpreterState_Get() from the
939+ function that created this thread. */
940+ PyInterpreterState *interp = ThreadData->interp;
941+ PyThreadState *tstate = PyThreadState_New(interp);
942+ PyThreadState_Swap(tstate);
943+
944+ /* GIL of the subinterpreter is now held.
945+ Perform Python actions here. */
946+ result = CallSomeFunction();
947+ /* evaluate result or handle exception */
923948
949+ /* Destroy the thread state. No Python API allowed beyond this point. */
950+ PyThreadState_Clear(tstate);
951+ PyThreadState_DeleteCurrent();
924952
925953.. _fork-and-threads:
926954
@@ -1097,6 +1125,10 @@ code, or when embedding the Python interpreter:
10971125 .. seealso:
10981126 :c:func:`PyEval_ReleaseThread`
10991127
1128+ .. note::
1129+ Similar to :c:func:`PyGILState_Ensure`, this function will hang the
1130+ thread if the runtime is finalizing.
1131+
11001132
11011133The following functions use thread-local storage, and are not compatible
11021134with sub-interpreters:
@@ -1123,10 +1155,10 @@ with sub-interpreters:
11231155 When the function returns, there will be an :term:`attached thread state`
11241156 and the thread will be able to call arbitrary Python code. Failure is a fatal error.
11251157
1126- ..note ::
1127- Calling this functionfrom a thread when the runtime is finalizingwill
1128- hang the thread until the programexits, even if the thread was not
1129- created by Python. Refer to
1158+ ..warning ::
1159+ Calling this function when the runtime is finalizingis unsafe. Doing
1160+ so will either hang the thread until the programends, or fully crash
1161+ the interpreter in rare cases. Refer to
11301162 :ref:`cautions-regarding-runtime-finalization` for more details.
11311163
11321164 .. versionchanged:: 3.14
@@ -1143,28 +1175,37 @@ with sub-interpreters:
11431175 Every call to :c:func:`PyGILState_Ensure` must be matched by a call to
11441176 :c:func:`PyGILState_Release` on the same thread.
11451177
1146-
11471178.. c:function:: PyThreadState* PyGILState_GetThisThreadState()
11481179
11491180 Get the :term:`attached thread state` for this thread. May return ``NULL`` if no
11501181 GILState API has been used on the current thread. Note that the main thread
11511182 always has such a thread-state, even if no auto-thread-state call has been
11521183 made on the main thread. This is mainly a helper/diagnostic function.
11531184
1154- .. seealso: :c:func:`PyThreadState_Get``
1185+ .. note::
1186+ This function does not account for :term:`thread states <thread state>` created
1187+ by something other than :c:func:`PyGILState_Ensure` (such as :c:func:`PyThreadState_New`).
1188+ Prefer :c:func:`PyThreadState_Get` or :c:func:`PyThreadState_GetUnchecked`
1189+ for most cases.
11551190
1191+ .. seealso: :c:func:`PyThreadState_Get``
11561192
11571193.. c:function:: int PyGILState_Check()
11581194
11591195 Return ``1`` if the current thread is holding the :term:`GIL` and ``0`` otherwise.
11601196 This function can be called from any thread at any time.
1161- Only if it has had itsPython thread stateinitialized and currently is
1162- holding the :term:`GIL ` will it return ``1``.
1197+ Only if it has had its:term:` thread state<attached thread state>` initialized
1198+ via :c:func:`PyGILState_Ensure ` will it return ``1``.
11631199 This is mainly a helper/diagnostic function. It can be useful
11641200 for example in callback contexts or memory allocation functions when
11651201 knowing that the :term:`GIL` is locked can allow the caller to perform sensitive
11661202 actions or otherwise behave differently.
11671203
1204+ .. note::
1205+ If the current Python process has ever created a subinterpreter, this
1206+ function will *always* return ``1``. Prefer :c:func:`PyThreadState_GetUnchecked`
1207+ for most cases.
1208+
11681209 .. versionadded:: 3.4
11691210
11701211