gh-108014: Add Py_IsFinalizing() function (#108032)

vstinner · serhiy-storchaka · web-flow · commit 3ff5ef2ad3d8 · 2023-08-18T12:34:41.000+02:00
Co-authored-by: Serhiy Storchaka &lt;storchaka@gmail.com&gt;
diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
@@ -373,6 +373,14 @@ Initializing and finalizing the interpreter
    :c:func:`Py_Initialize` is called again.
 
 
+.. c:function:: int Py_IsFinalizing()
+
+   Return true (non-zero) if the main Python interpreter is
+   :term:`shutting down <interpreter shutdown>`. Return false (zero) otherwise.
+
+   .. versionadded:: 3.13
+
+
 .. c:function:: int Py_FinalizeEx()
 
    Undo all initializations made by :c:func:`Py_Initialize` and subsequent use of
@@ -852,7 +860,7 @@ code, or when embedding the Python interpreter:
    .. 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.
-      You can use :c:func:`!_Py_IsFinalizing` or :func:`sys.is_finalizing` to
+      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.
 
@@ -898,7 +906,7 @@ with sub-interpreters:
    .. 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.
-      You can use :c:func:`!_Py_IsFinalizing` or :func:`sys.is_finalizing` to
+      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.
 
@@ -1180,7 +1188,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
    .. 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.
-      You can use :c:func:`!_Py_IsFinalizing` or :func:`sys.is_finalizing` to
+      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.
 
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
@@ -1121,8 +1121,8 @@ always available.
 
 .. function:: is_finalizing()
 
-   Return :const:`True` if the Python interpreter is
-   :term:`shutting down <interpreter shutdown>`, :const:`False` otherwise.
+   Return :const:`True` if the main Python interpreter is
+   :term:`shutting down <interpreter shutdown>`. Return :const:`False` otherwise.
 
    .. versionadded:: 3.5
 
diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
@@ -832,6 +832,10 @@ New Features
   not needed.
   (Contributed by Victor Stinner in :gh:`106004`.)
 
+* Add :c:func:`Py_IsFinalizing` function: check if the main Python interpreter is
+  :term:`shutting down <interpreter shutdown>`.
+  (Contributed by Victor Stinner in :gh:`108014`.)
+
 Porting to Python 3.13
 ----------------------
 
diff --git a/Include/cpython/pylifecycle.h b/Include/cpython/pylifecycle.h
@@ -81,3 +81,5 @@ PyAPI_FUNC(PyStatus) Py_NewInterpreterFromConfig(
 typedef void (*atexit_datacallbackfunc)(void *);
 PyAPI_FUNC(int) PyUnstable_AtExit(
         PyInterpreterState *, atexit_datacallbackfunc, void *);
+
+PyAPI_FUNC(int) Py_IsFinalizing(void);
diff --git a/Include/internal/pycore_pylifecycle.h b/Include/internal/pycore_pylifecycle.h
@@ -98,7 +98,6 @@ extern int _Py_FdIsInteractive(FILE *fp, PyObject *filename);
 extern const char* _Py_gitidentifier(void);
 extern const char* _Py_gitversion(void);
 
-extern int _Py_IsFinalizing(void);
 PyAPI_FUNC(int) _Py_IsInterpreterFinalizing(PyInterpreterState *interp);
 
 /* Random */
diff --git a/Misc/NEWS.d/next/C API/2023-08-16-17-16-19.gh-issue-108014.wXN3CF.rst b/Misc/NEWS.d/next/C API/2023-08-16-17-16-19.gh-issue-108014.wXN3CF.rst
@@ -0,0 +1,2 @@
+Add :c:func:`Py_IsFinalizing` function: check if the main Python interpreter is
+:term:`shutting down <interpreter shutdown>`. Patch by Victor Stinner.
diff --git a/Modules/_asynciomodule.c b/Modules/_asynciomodule.c
@@ -529,7 +529,7 @@ future_init(FutureObj *fut, PyObject *loop)
     }
     if (is_true && !_Py_IsInterpreterFinalizing(_PyInterpreterState_GET())) {
         /* Only try to capture the traceback if the interpreter is not being
-           finalized.  The original motivation to add a `_Py_IsFinalizing()`
+           finalized.  The original motivation to add a `Py_IsFinalizing()`
            call was to prevent SIGSEGV when a Future is created in a __del__
            method, which is called during the interpreter shutdown and the
            traceback module is already unloaded.
diff --git a/Python/pylifecycle.c b/Python/pylifecycle.c
@@ -129,7 +129,7 @@ _PyRuntime_Finalize(void)
 }
 
 int
-_Py_IsFinalizing(void)
+Py_IsFinalizing(void)
 {
     return _PyRuntimeState_GetFinalizing(&_PyRuntime) != NULL;
 }
diff --git a/Python/sysmodule.c b/Python/sysmodule.c
@@ -2095,7 +2095,7 @@ static PyObject *
 sys_is_finalizing_impl(PyObject *module)
 /*[clinic end generated code: output=735b5ff7962ab281 input=f0df747a039948a5]*/
 {
-    return PyBool_FromLong(_Py_IsFinalizing());
+    return PyBool_FromLong(Py_IsFinalizing());
 }
 
 #ifdef Py_STATS

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	+Add :c:func:`Py_IsFinalizing` function: check if the main Python interpreter is
	`2`	+:term:`shutting down <interpreter shutdown>`. Patch by Victor Stinner.
Original file line number	Diff line number	Diff line change
`@@ -529,7 +529,7 @@ future_init(FutureObj fut, PyObject loop)`
`529`	`529`	`}`
`530`	`530`	`if (is_true && !_Py_IsInterpreterFinalizing(_PyInterpreterState_GET())) {`
`531`	`531`	`/* Only try to capture the traceback if the interpreter is not being`
`532`		- finalized. The original motivation to add a `_Py_IsFinalizing()`
	`532`	+ finalized. The original motivation to add a `Py_IsFinalizing()`
`533`	`533`	`call was to prevent SIGSEGV when a Future is created in a __del__`
`534`	`534`	`method, which is called during the interpreter shutdown and the`
`535`	`535`	`traceback module is already unloaded.`
Original file line number	Diff line number	Diff line change
`@@ -129,7 +129,7 @@ _PyRuntime_Finalize(void)`
`129`	`129`	`}`
`130`	`130`
`131`	`131`	`int`
`132`		`-_Py_IsFinalizing(void)`
	`132`	`+Py_IsFinalizing(void)`
`133`	`133`	`{`
`134`	`134`	`return _PyRuntimeState_GetFinalizing(&_PyRuntime) != NULL;`
`135`	`135`	`}`
Original file line number	Diff line number	Diff line change
`@@ -2095,7 +2095,7 @@ static PyObject *`
`2095`	`2095`	`sys_is_finalizing_impl(PyObject *module)`
`2096`	`2096`	`/[clinic end generated code: output=735b5ff7962ab281 input=f0df747a039948a5]/`
`2097`	`2097`	`{`
`2098`		`- return PyBool_FromLong(_Py_IsFinalizing());`
	`2098`	`+ return PyBool_FromLong(Py_IsFinalizing());`
`2099`	`2099`	`}`
`2100`	`2100`
`2101`	`2101`	`#ifdef Py_STATS`