gh-117929: Restore removed PyEval_InitThreads() function (#117931)

Author: vstinner

Doc/c-api/init.rst

@@ -59,7 +59,7 @@ The following functions can be safely called before Python is initialized:
    :c:func:`Py_Initialize`: :c:func:`Py_EncodeLocale`, :c:func:`Py_GetPath`,
    :c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`,
    :c:func:`Py_GetProgramFullPath`, :c:func:`Py_GetPythonHome`,
-   and :c:func:`Py_GetProgramName`.
+   :c:func:`Py_GetProgramName` and :c:func:`PyEval_InitThreads`.
 
 
 .. _global-conf-vars:
@@ -326,6 +326,7 @@ Initializing and finalizing the interpreter
 .. c:function:: void Py_Initialize()
 
    .. index::
+      single: PyEval_InitThreads()
       single: modules (in module sys)
       single: path (in module sys)
       pair: module; builtins
@@ -841,6 +842,33 @@ code, or when embedding the Python interpreter:
       This thread's interpreter state.
 
 
+.. c:function:: void PyEval_InitThreads()
+
+   .. index::
+      single: PyEval_AcquireThread()
+      single: PyEval_ReleaseThread()
+      single: PyEval_SaveThread()
+      single: PyEval_RestoreThread()
+
+   Deprecated function which does nothing.
+
+   In Python 3.6 and older, this function created the GIL if it didn't exist.
+
+   .. versionchanged:: 3.9
+      The function now does nothing.
+
+   .. versionchanged:: 3.7
+      This function is now called by :c:func:`Py_Initialize()`, so you don't
+      have to call it yourself anymore.
+
+   .. versionchanged:: 3.2
+      This function cannot be called before :c:func:`Py_Initialize()` anymore.
+
+   .. deprecated:: 3.9
+
+   .. index:: pair: module; _thread
+
+
 .. c:function:: PyThreadState* PyEval_SaveThread()
 
    Release the global interpreter lock (if it has been created) and reset the

Doc/data/stable_abi.dat

@@ -2027,9 +2027,9 @@ Removed
   added in Python 3.8 and the old macros were deprecated in Python 3.11.
   (Contributed by Irit Katriel in :gh:`105111`.)
 
-* Remove ``PyEval_InitThreads()`` and ``PyEval_ThreadsInitialized()``
-  functions, deprecated in Python 3.9. Since Python 3.7, ``Py_Initialize()``
-  always creates the GIL: calling ``PyEval_InitThreads()`` did nothing and
+* Remove ``PyEval_ThreadsInitialized()``
+  function, deprecated in Python 3.9. Since Python 3.7, ``Py_Initialize()``
+  always creates the GIL: calling ``PyEval_InitThreads()`` does nothing and
   ``PyEval_ThreadsInitialized()`` always returned non-zero.
   (Contributed by Victor Stinner in :gh:`105182`.)
 

Doc/whatsnew/3.13.rst

@@ -107,6 +107,8 @@ PyAPI_FUNC(PyObject *) PyEval_EvalFrameEx(PyFrameObject *f, int exc);
 PyAPI_FUNC(PyThreadState *) PyEval_SaveThread(void);
 PyAPI_FUNC(void) PyEval_RestoreThread(PyThreadState *);
 
+Py_DEPRECATED(3.9) PyAPI_FUNC(void) PyEval_InitThreads(void);
+
 PyAPI_FUNC(void) PyEval_AcquireThread(PyThreadState *tstate);
 PyAPI_FUNC(void) PyEval_ReleaseThread(PyThreadState *tstate);
 

Include/ceval.h

@@ -0,0 +1,2 @@
+Restore removed :c:func:`PyEval_InitThreads` function. Patch by Victor
+Stinner.

Misc/NEWS.d/next/C API/2024-04-16-13-34-01.gh-issue-117929.HSr419.rst

@@ -702,7 +702,6 @@
     added = '3.2'
 [function.PyEval_InitThreads]
     added = '3.2'
-    abi_only = true
 [function.PyEval_ReleaseLock]
     added = '3.2'
     abi_only = true

Misc/stable_abi.toml

@@ -512,8 +512,7 @@ _PyEval_FiniGIL(PyInterpreterState *interp)
     interp->ceval.gil = NULL;
 }
 
-// Function removed in the Python 3.13 API but kept in the stable ABI.
-PyAPI_FUNC(void)
+void
 PyEval_InitThreads(void)
 {
     /* Do nothing: kept for backward compatibility */