bpo-36427: Document that PyEval_RestoreThread and PyGILState_Ensure can terminate the calling thread

pablogsal · pablogsal · commit 926525dcdaa4 · 2019-03-25T22:16:17.000Z
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
@@ -855,6 +855,12 @@ code, or when embedding the Python interpreter:
    created, the current thread must not have acquired it, otherwise deadlock
    ensues.
 
+   .. warning::
+      Calling this function from a thread when the interpreter is finalizing
+      will terminate the thread, even if the thread was not created by Python.
+      You can use :c:func:`_Py_IsFinalizing` or :func:`sys.is_finalizing` to
+      check if the interpreter is in process of being finalized before calling
+      this function to avoid unwanted termination.
 
 .. c:function:: PyThreadState* PyThreadState_Get()
 
@@ -902,6 +908,12 @@ 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.
 
+   .. warning::
+      Calling this function from a thread when the interpreter is finalizing
+      will terminate the thread, even if the thread was not created by Python.
+      You can use :c:func:`_Py_IsFinalizing` or :func:`sys.is_finalizing` to
+      check if the interpreter is in process of being finalized before calling
+      this function to avoid unwanted termination.
 
 .. c:function:: void PyGILState_Release(PyGILState_STATE)
 
