bpo-39947: Add PyThreadState_GetFrame() function (GH-19092)

Add PyThreadState_GetFrame() function: get the current frame
of a Python thread state.

6 files changed, 33 insertions, 5 deletions

diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index a4ec0e3852..294c1b9f72 100644
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -1072,6 +1072,18 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
    to :c:func:`PyThreadState_Clear`.
 
 
+.. c:function:: PyFrameObject* PyThreadState_GetFrame(PyThreadState *tstate)
+
+   Get the current frame of the Python thread state *tstate*. It can be
+   ``NULL`` if no frame is currently executing.
+
+   See also :c:func:`PyEval_GetFrame`.
+
+   *tstate* must not be ``NULL``.
+
+   .. versionadded:: 3.9
+
+
 .. c:function:: PyInterpreterState* PyThreadState_GetInterpreter(PyThreadState *tstate)
 
    Get the interpreter of the Python thread state *tstate*.
diff --git a/Doc/c-api/reflection.rst b/Doc/c-api/reflection.rst
index 1d86de66ed..4d3d25e662 100644
--- a/Doc/c-api/reflection.rst
+++ b/Doc/c-api/reflection.rst
@@ -5,29 +5,31 @@
 Reflection
 ==========
 
-.. c:function:: PyObject* PyEval_GetBuiltins()
+.. c:function:: PyObject* PyEval_GetBuiltins(void)
 
    Return a dictionary of the builtins in the current execution frame,
    or the interpreter of the thread state if no frame is currently executing.
 
 
-.. c:function:: PyObject* PyEval_GetLocals()
+.. c:function:: PyObject* PyEval_GetLocals(void)
 
    Return a dictionary of the local variables in the current execution frame,
    or ``NULL`` if no frame is currently executing.
 
 
-.. c:function:: PyObject* PyEval_GetGlobals()
+.. c:function:: PyObject* PyEval_GetGlobals(void)
 
    Return a dictionary of the global variables in the current execution frame,
    or ``NULL`` if no frame is currently executing.
 
 
-.. c:function:: PyFrameObject* PyEval_GetFrame()
+.. c:function:: PyFrameObject* PyEval_GetFrame(void)
 
    Return the current thread state's frame, which is ``NULL`` if no frame is
    currently executing.
 
+   See also :c:func:`PyThreadState_GetFrame`.
+
 
 .. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame)
 
diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst
index ac5d317d33..3e30f84c2c 100644
--- a/Doc/whatsnew/3.9.rst
+++ b/Doc/whatsnew/3.9.rst
@@ -427,6 +427,9 @@ Build and C API Changes
 
 * New :c:func:`PyThreadState_GetInterpreter` and
   :c:func:`PyInterpreterState_Get` functions to get the interpreter.
+  New :c:func:`PyThreadState_GetFrame` function to get the current frame of a
+  Python thread state.
+  (Contributed by Victor Stinner in :issue:`39947`.)
 
 * Add ``--with-platlibdir`` option to the ``configure`` script: name of the
   platform-specific library directory, stored in the new :attr:`sys.platlibdir`
diff --git a/Include/pystate.h b/Include/pystate.h
index 70d3bdc9a7..5866fef3d0 100644
--- a/Include/pystate.h
+++ b/Include/pystate.h
@@ -89,7 +89,8 @@ PyAPI_FUNC(int) PyThreadState_SetAsyncExc(unsigned long, PyObject *);
 
 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03090000
 /* New in 3.9 */
-PyAPI_FUNC(PyInterpreterState *) PyThreadState_GetInterpreter(PyThreadState *tstate);
+PyAPI_FUNC(PyInterpreterState*) PyThreadState_GetInterpreter(PyThreadState *tstate);
+PyAPI_FUNC(struct _frame*) PyThreadState_GetFrame(PyThreadState *tstate);
 #endif
 
 typedef
diff --git a/Misc/NEWS.d/next/C API/2020-03-20-14-55-09.bpo-39947.W7uCJ3.rst b/Misc/NEWS.d/next/C API/2020-03-20-14-55-09.bpo-39947.W7uCJ3.rst
new file mode 100644
index 0000000000..33988489a6
--- /dev/null
+++ b/Misc/NEWS.d/next/C API/2020-03-20-14-55-09.bpo-39947.W7uCJ3.rst
@@ -0,0 +1,2 @@
+Add :c:func:`PyThreadState_GetFrame` function: get the current frame of a
+Python thread state.
diff --git a/Python/pystate.c b/Python/pystate.c
index 621318f4b5..eea666b7e5 100644
--- a/Python/pystate.c
+++ b/Python/pystate.c
@@ -1007,6 +1007,14 @@ PyThreadState_GetInterpreter(PyThreadState *tstate)
 }
 
 
+struct _frame*
+PyThreadState_GetFrame(PyThreadState *tstate)
+{
+    assert(tstate != NULL);
+    return _PyThreadState_GetFrame(tstate);
+}
+
+
 /* Asynchronously raise an exception in a thread.
    Requested by Just van Rossum and Alex Martelli.
    To prevent naive misuse, you must write your own extension