bpo-46850: Move _PyInterpreterState_SetEvalFrameFunc() to internal C API (GH-32054)

Move the private _PyFrameEvalFunction type, and private
_PyInterpreterState_GetEvalFrameFunc() and
_PyInterpreterState_SetEvalFrameFunc() functions to the internal C
API. The _PyFrameEvalFunction callback function type now uses the
_PyInterpreterFrame type which is part of the internal C API.

Update the _PyFrameEvalFunction documentation.

Doc/c-api/init.rst

@@ -1228,18 +1228,25 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
 
    .. versionadded:: 3.8
 
-.. c:type:: PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, PyFrameObject *frame, int throwflag)
+.. c:type:: PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, _PyInterpreterFrame *frame, int throwflag)
+
+   Internal C API.
 
    Type of a frame evaluation function.
 
    The *throwflag* parameter is used by the ``throw()`` method of generators:
    if non-zero, handle the current exception.
 
+   .. versionchanged:: 3.11
+      The second parameter type becomes ``_PyInterpreterFrame``.
+
    .. versionchanged:: 3.9
       The function now takes a *tstate* parameter.
 
 .. c:function:: _PyFrameEvalFunction _PyInterpreterState_GetEvalFrameFunc(PyInterpreterState *interp)
 
+   Internal C API.
+
    Get the frame evaluation function.
 
    See the :pep:`523` "Adding a frame evaluation API to CPython".
@@ -1248,6 +1255,8 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
 
 .. c:function:: void _PyInterpreterState_SetEvalFrameFunc(PyInterpreterState *interp, _PyFrameEvalFunction eval_frame)
 
+   Internal C API.
+
    Set the frame evaluation function.
 
    See the :pep:`523` "Adding a frame evaluation API to CPython".

Doc/whatsnew/3.11.rst

@@ -1102,6 +1102,12 @@ Porting to Python 3.11
   is part of the internal C API.
   (Contributed by Victor Stinner in :issue:`46850`.)
 
+* Move the private ``_PyFrameEvalFunction`` type, and private
+  ``_PyInterpreterState_GetEvalFrameFunc()`` and
+  ``_PyInterpreterState_SetEvalFrameFunc()`` functions to the internal C API.
+  The ``_PyFrameEvalFunction`` callback function type now uses the
+  ``_PyInterpreterFrame`` type which is part of the internal C API.
+  (Contributed by Victor Stinner in :issue:`46850`.)
 
 Deprecated
 ----------

Include/cpython/pystate.h

@@ -259,16 +259,6 @@ PyAPI_FUNC(PyThreadState *) PyInterpreterState_ThreadHead(PyInterpreterState *);
 PyAPI_FUNC(PyThreadState *) PyThreadState_Next(PyThreadState *);
 PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void);
 
-/* Frame evaluation API */
-
-typedef PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, struct _PyInterpreterFrame *, int);
-
-PyAPI_FUNC(_PyFrameEvalFunction) _PyInterpreterState_GetEvalFrameFunc(
-    PyInterpreterState *interp);
-PyAPI_FUNC(void) _PyInterpreterState_SetEvalFrameFunc(
-    PyInterpreterState *interp,
-    _PyFrameEvalFunction eval_frame);
-
 PyAPI_FUNC(const PyConfig*) _PyInterpreterState_GetConfig(PyInterpreterState *interp);
 
 /* Get a copy of the current interpreter configuration.

Include/internal/pycore_interp.h

@@ -17,9 +17,9 @@ extern "C" {
 #include "pycore_dict.h"          // struct _Py_dict_state
 #include "pycore_exceptions.h"    // struct _Py_exc_state
 #include "pycore_floatobject.h"   // struct _Py_float_state
+#include "pycore_gc.h"            // struct _gc_runtime_state
 #include "pycore_genobject.h"     // struct _Py_async_gen_state
 #include "pycore_gil.h"           // struct _gil_runtime_state
-#include "pycore_gc.h"            // struct _gc_runtime_state
 #include "pycore_list.h"          // struct _Py_list_state
 #include "pycore_tuple.h"         // struct _Py_tuple_state
 #include "pycore_typeobject.h"    // struct type_cache
@@ -71,6 +71,20 @@ struct atexit_state {
 };
 
 
+/* Frame evaluation API (PEP 523) */
+
+typedef PyObject* (*_PyFrameEvalFunction) (
+    PyThreadState *tstate,
+    struct _PyInterpreterFrame *frame,
+    int throwflag);
+
+PyAPI_FUNC(_PyFrameEvalFunction) _PyInterpreterState_GetEvalFrameFunc(
+    PyInterpreterState *interp);
+PyAPI_FUNC(void) _PyInterpreterState_SetEvalFrameFunc(
+    PyInterpreterState *interp,
+    _PyFrameEvalFunction eval_frame);
+
+
 /* interpreter state */
 
 /* PyInterpreterState holds the global state for one of the runtime's

Include/internal/pycore_pystate.h

@@ -8,7 +8,7 @@ extern "C" {
 #  error "this header requires Py_BUILD_CORE define"
 #endif
 
-#include "pycore_runtime.h"   /* PyRuntimeState */
+#include "pycore_runtime.h"       // _PyRuntime
 
 
 /* Check if the current thread is the main thread.

Misc/NEWS.d/next/C API/2022-03-22-16-59-34.bpo-46850.lmEKLy.rst

@@ -0,0 +1,6 @@
+Move the private ``_PyFrameEvalFunction`` type, and private
+``_PyInterpreterState_GetEvalFrameFunc()`` and
+``_PyInterpreterState_SetEvalFrameFunc()`` functions to the internal C API. The
+``_PyFrameEvalFunction`` callback function type now uses the
+``_PyInterpreterFrame`` type which is part of the internal C API. Patch by
+Victor Stinner.