python · ncoghlan · Mar 19, 2022 · Mar 19, 2022 · Mar 19, 2022 · Mar 19, 2022
diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
@@ -949,13 +949,13 @@ Porting to Python 3.11
   * ``f_lineno``: use :c:func:`PyFrame_GetLineNumber`
   * ``f_locals``: use ``PyObject_GetAttrString((PyObject*)frame, "f_locals")``.
   * ``f_stackdepth``: removed.
-  * ``f_state``: no public API (renamed to ``f_frame.f_state``).
+  * ``f_state``: no public API.
   * ``f_trace``: no public API.
   * ``f_trace_lines``: use ``PyObject_GetAttrString((PyObject*)frame, "f_trace_lines")``
     (it also be modified).
   * ``f_trace_opcodes``: use ``PyObject_GetAttrString((PyObject*)frame, "f_trace_opcodes")``
     (it also be modified).
-  * ``f_localsplus``: no public API (renamed to ``f_frame.localsplus``).
+  * ``f_localsplus``: no public API.
   * ``f_valuestack``: removed.
 
   The Python frame object is now created lazily. A side effect is that the

diff --git a/Include/cpython/ceval.h b/Include/cpython/ceval.h
@@ -22,7 +22,7 @@ PyAPI_FUNC(PyObject *) _PyEval_GetBuiltinId(_Py_Identifier *);
    flag was set, else return 0. */
 PyAPI_FUNC(int) PyEval_MergeCompilerFlags(PyCompilerFlags *cf);
 
-PyAPI_FUNC(PyObject *) _PyEval_EvalFrameDefault(PyThreadState *tstate, struct _PyInterpreterFrame *f, int exc);
+PyAPI_FUNC(PyObject *) _PyEval_EvalFrameDefault(PyThreadState *tstate, struct _Py_frame *f, int exc);
 
 PyAPI_FUNC(void) _PyEval_SetSwitchInterval(unsigned long microseconds);
 PyAPI_FUNC(unsigned long) _PyEval_GetSwitchInterval(void);

@@ -48,7 +48,7 @@ typedef struct _PyCFrame {
      */
     int use_tracing;
     /* Pointer to the currently executing frame (it can be NULL) */
-    struct _PyInterpreterFrame *current_frame;
+    struct _Py_frame *current_frame;
     struct _PyCFrame *previous;
 } _PyCFrame;
 
@@ -260,7 +260,7 @@ PyAPI_FUNC(void) PyThreadState_DeleteCurrent(void);
 
 /* Frame evaluation API */
 
-typedef PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, struct _PyInterpreterFrame *, int);
+typedef PyObject* (*_PyFrameEvalFunction)(PyThreadState *tstate, struct _Py_frame *, int);
 
 PyAPI_FUNC(_PyFrameEvalFunction) _PyInterpreterState_GetEvalFrameFunc(
     PyInterpreterState *interp);

diff --git a/Include/internal/pycore_ceval.h b/Include/internal/pycore_ceval.h
@@ -47,7 +47,7 @@ extern PyObject *_PyEval_BuiltinsFromGlobals(
 
 
 static inline PyObject*
-_PyEval_EvalFrame(PyThreadState *tstate, struct _PyInterpreterFrame *frame, int throwflag)
+_PyEval_EvalFrame(PyThreadState *tstate, struct _Py_frame *frame, int throwflag)
 {
     if (tstate->interp->eval_frame == NULL) {
         return _PyEval_EvalFrameDefault(tstate, frame, throwflag);
@@ -116,7 +116,7 @@ static inline void _Py_LeaveRecursiveCall_inline(void)  {
 
 #define Py_LeaveRecursiveCall() _Py_LeaveRecursiveCall_inline()
 
-struct _PyInterpreterFrame *_PyEval_GetFrame(void);
+struct _Py_frame *_PyEval_GetFrame(void);
 
 PyObject *_Py_MakeCoro(PyFunctionObject *func);
 

diff --git a/Include/internal/pycore_frame.h b/Include/internal/pycore_frame.h
@@ -6,17 +6,66 @@ extern "C" {
 
 #include <stdbool.h>
 
+/* Starting in CPython 3.11, CPython separates the frame state between the
+ * full frame objects exposed by the Python and C runtime state introspection
+ * APIs, and internal lighter weight frame data structs, which are simple C
+ * structures owned by either the interpreter eval loop (while executing
+ * ordinary functions), by a generator or coroutine object (for frames that
+ * are able to be suspended), or by their corresponding full frame object (if
+ * a state instrospection API has been invoked and the full frame object has
+ * taken responsibility for the lifecycle of the frame data storage).
+ *
+ * This split storage eliminates a lot of allocation and deallocation of full
+ * Python objects during code execution, providing a significant speed gain
+ * over the previous approach of using full Python objects for both
+ * introspection and code execution.
+ *
+ * Field naming conventions:
+ *
+ *   * full frame object fields have an "f_*" prefix
+ *   * frame data struct fields have no prefix
+ *
+ * Naming conventions for local variables, function parameters and fields in other structs:
+ *
+ *   * "frame", and "f" may refer to either full frame objects or frame data structs
+ *     * the field naming convention usually makes the type unambiguous in code reviews
+ *   * the following alternative names are used when more clarity is needed:
+ *     * full frame objects: "frame_obj" (and variants like "frameobj" or "fobj")
+ *     * frame data structs: "fdata"
+ *   * the "iframe" name is still used in the generator & coroutine structs. It
+ *     comes from a period where frame data structs were called "interpreter frames"
+ *     (which implied a larger distinction between full frame objects and their
+ *     associated lightweight frame data structs than is actually the case).
+ *   * "current frame" should NOT be abbreviated as "cframe", as the latter typically
+ *     refers to the C stack frame data that is used to separate Python level recursion
+ *     from C level recursive calls to the eval loop f
2364
unction
+ *
+ * Function/macro parameter types:
+ *
+ *   * "PyFrame_*" functions and other public C API functions that relate to
+ *     frames accept full frame objects
+ *   * "_PyFrame_*" functions and other private C API functions that relate to
+ *     frames accept either full frame objecst or frame data structs. Check
+ *     the specific function signatures for details.
+ *
+ * Function return types:
+ *
+ *   * Public C API functions will only ever return full frame objects
+ *   * Private C API functions with an underscore prefix may return frame
+ *     data structs instead. Check the specific function signatures for details.
+ */
+
 struct _frame {
     PyObject_HEAD
     PyFrameObject *f_back;      /* previous frame, or NULL */
-    struct _PyInterpreterFrame *f_frame; /* points to the frame data */
+    struct _Py_frame *f_fdata; /* points to the frame data */
     PyObject *f_trace;          /* Trace function */
     int f_lineno;               /* Current line number. Only valid if non-zero */
     char f_trace_lines;         /* Emit per-line trace events? */
     char f_trace_opcodes;       /* Emit per-opcode trace events? */
     char f_owns_frame;          /* This frame owns the frame */
     /* The frame data, if this frame object owns the frame */
-    PyObject *_f_frame_data[1];
+    PyObject *_f_owned_fdata[1];
 };
 
 extern PyFrameObject* _PyFrame_New_NoTrack(PyCodeObject *code);
@@ -25,7 +74,7 @@ extern PyFrameObject* _PyFrame_New_NoTrack(PyCodeObject *code);
 /* other API */
 
 /* These values are chosen so that the inline functions below all
- * compare f_state to zero.
+ * compare the current frame state to zero.
  */
 enum _framestate {
     FRAME_CREATED = -2,
@@ -40,78 +89,78 @@ enum _framestate {
 typedef signed char PyFrameState;
 
 /*
-    frame->f_lasti refers to the index of the last instruction,
+    frame->lasti refers to the index of the last instruction,
     unless it's -1 in which case next_instr should be first_instr.
 */
 
-typedef struct _PyInterpreterFrame {
-    PyFunctionObject *f_func; /* Strong reference */
-    PyObject *f_globals; /* Borrowed reference */
-    PyObject *f_builtins; /* Borrowed reference */
-    PyObject *f_locals; /* Strong reference, may be NULL */
-    PyCodeObject *f_code; /* Strong reference */
+typedef struct _Py_frame {
+    PyFunctionObject *func; /* Strong reference */
+    PyObject *globals; /* Borrowed reference */
+    PyObject *builtins; /* Borrowed reference */
+    PyObject *locals; /* Strong reference, may be NULL */
+    PyCodeObject *code; /* Strong reference */
     PyFrameObject *frame_obj; /* Strong reference, may be NULL */
-    struct _PyInterpreterFrame *previous;
-    int f_lasti;       /* Last instruction if called */
+    struct _Py_frame *previous;
+    int lasti;       /* Last instruction if called */
     int stacktop;     /* Offset of TOS from localsplus  */
-    PyFrameState f_state;  /* What state the frame is in */
+    PyFrameState state;  /* What state the frame is in */
     bool is_entry;  // Whether this is the "root" frame for the current _PyCFrame.
     bool is_generator;
     PyObject *localsplus[1];
-} _PyInterpreterFrame;
+} _Py_frame;
 
-static inline int _PyFrame_IsRunnable(_PyInterpreterFrame *f) {
-    return f->f_state < FRAME_EXECUTING;
+static inline int _PyFrame_IsRunnable(_Py_frame *f) {
+    return f->state < FRAME_EXECUTING;
 }
 
-static inline int _PyFrame_IsExecuting(_PyInterpreterFrame *f) {
-    return f->f_state == FRAME_EXECUTING;
+static inline int _PyFrame_IsExecuting(_Py_frame *f) {
+    return f->state == FRAME_EXECUTING;
 }
 
-static inline int _PyFrameHasCompleted(_PyInterpreterFrame *f) {
-    return f->f_state > FRAME_EXECUTING;
+static inline int _PyFrameHasCompleted(_Py_frame *f) {
+    return f->state > FRAME_EXECUTING;
 }
 
-static inline PyObject **_PyFrame_Stackbase(_PyInterpreterFrame *f) {
-    return f->localsplus + f->f_code->co_nlocalsplus;
+static inline PyObject **_PyFrame_Stackbase(_Py_frame *f) {
+    return f->localsplus + f->code->co_nlocalsplus;
 }
 
-static inline PyObject *_PyFrame_StackPeek(_PyInterpreterFrame *f) {
-    assert(f->stacktop > f->f_code->co_nlocalsplus);
+static inline PyObject *_PyFrame_StackPeek(_Py_frame *f) {
+    assert(f->stacktop > f->code->co_nlocalsplus);
     assert(f->localsplus[f->stacktop-1] != NULL);
     return f->localsplus[f->stacktop-1];
 }
 
-static inline PyObject *_PyFrame_StackPop(_PyInterpreterFrame *f) {
-    assert(f->stacktop > f->f_code->co_nlocalsplus);
+static inline PyObject *_PyFrame_StackPop(_Py_frame *f) {
+    assert(f->stacktop > f->code->co_nlocalsplus);
     f->stacktop--;
     return f->localsplus[f->stacktop];
 }
 
-static inline void _PyFrame_StackPush(_PyInterpreterFrame *f, PyObject *value) {
+static inline void _PyFrame_StackPush(_Py_frame *f, PyObject *value) {
     f->localsplus[f->stacktop] = value;
     f->stacktop++;
 }
 
-#define FRAME_SPECIALS_SIZE ((sizeof(_PyInterpreterFrame)-1)/sizeof(PyObject *))
+#define FRAME_SPECIALS_SIZE ((sizeof(_Py_frame)-1)/sizeof(PyObject *))
 
-void _PyFrame_Copy(_PyInterpreterFrame *src, _PyInterpreterFrame *dest);
+void _PyFrame_Copy(_Py_frame *src, _Py_frame *dest);
 
 /* Consumes reference to func */
 static inline void
 _PyFrame_InitializeSpecials(
-    _PyInterpreterFrame *frame, PyFunctionObject *func,
+    _Py_frame *frame, PyFunctionObject *func,
     PyObject *locals, int nlocalsplus)
 {
-    frame->f_func = func;
-    frame->f_code = (PyCodeObject *)Py_NewRef(func->func_code);
-    frame->f_builtins = func->func_builtins;
-    frame->f_globals = func->func_globals;
-    frame->f_locals = Py_XNewRef(locals);
+    frame->func = func;
+    frame->code = (PyCodeObject *)Py_NewRef(func->func_code);
+    frame->builtins = func->func_builtins;
+    frame->globals = func->func_globals;
+    frame->locals = Py_XNewRef(locals);
     frame->stacktop = nlocalsplus;
     frame->frame_obj = NULL;
-    frame->f_lasti = -1;
-    frame->f_state = FRAME_CREATED;
+    frame->lasti = -1;
+    frame->state = FRAME_CREATED;
     frame->is_entry = false;
     frame->is_generator = false;
 }
@@ -120,33 +169,33 @@ _PyFrame_InitializeSpecials(
  * that precedes this frame.
  */
 static inline PyObject**
-_PyFrame_GetLocalsArray(_PyInterpreterFrame *frame)
+_PyFrame_GetLocalsArray(_Py_frame *frame)
 {
     return frame->localsplus;
 }
 
 static inline PyObject**
-_PyFrame_GetStackPointer(_PyInterpreterFrame *frame)
+_PyFrame_GetStackPointer(_Py_frame *frame)
 {
     return frame->localsplus+frame->stacktop;
 }
 
 static inline void
-_PyFrame_SetStackPointer(_PyInterpreterFrame *frame, PyObject **stack_pointer)
+_PyFrame_SetStackPointer(_Py_frame *frame, PyObject **stack_pointer)
 {
     frame->stacktop = (int)(stack_pointer - frame->localsplus);
 }
 
 /* For use by _PyFrame_GetFrameObject
   Do not call directly. */
 PyFrameObject *
-_PyFrame_MakeAndSetFrameObject(_PyInterpreterFrame *frame);
+_PyFrame_MakeAndSetFrameObject(_Py_frame *frame);
 
 /* Gets the PyFrameObject for this frame, lazily
  * creating it if necessary.
  * Returns a borrowed referennce */
 static inline PyFrameObject *
-_PyFrame_GetFrameObject(_PyInterpreterFrame *frame)
+_PyFrame_GetFrameObject(_Py_frame *frame)
 {
     PyFrameObject *res =  frame->frame_obj;
     if (res != NULL) {
@@ -156,7 +205,7 @@ _PyFrame_GetFrameObject(_PyInterpreterFrame *frame)
 }
 
 /* Clears all references in the frame.
- * If take is non-zero, then the _PyInterpreterFrame frame
+ * If take is non-zero, then the _Py_frame frame
  * may be transferred to the frame object it references
  * instead of being cleared. Either way
  * the caller no longer owns the references
@@ -165,21 +214,21 @@ _PyFrame_GetFrameObject(_PyInterpreterFrame *frame)
  * frames like the ones in generators and coroutines.
  */
 void
-_PyFrame_Clear(_PyInterpreterFrame * frame);
+_PyFrame_Clear(_Py_frame * frame);
 
 int
-_PyFrame_Traverse(_PyInterpreterFrame *frame, visitproc visit, void *arg);
+_PyFrame_Traverse(_Py_frame *frame, visitproc visit, void *arg);
 
 int
-_PyFrame_FastToLocalsWithError(_PyInterpreterFrame *frame);
+_PyFrame_FastToLocalsWithError(_Py_frame *frame);
 
 void
-_PyFrame_LocalsToFast(_PyInterpreterFrame *frame, int clear);
+_PyFrame_LocalsToFast(_Py_frame *frame, int clear);
 
-extern _PyInterpreterFrame *
+extern _Py_frame *
 _PyThreadState_BumpFramePointerSlow(PyThreadState *tstate, size_t size);
 
-static inline _PyInterpreterFrame *
+static inline _Py_frame *
 _PyThreadState_BumpFramePointer(PyThreadState *tstate, size_t size)
 {
     PyObject **base = tstate->datastack_top;
@@ -188,16 +237,16 @@ _PyThreadState_BumpFramePointer(PyThreadState *tstate, size_t size)
         assert(tstate->datastack_limit);
         if (top < tstate->datastack_limit) {
             tstate->datastack_top = top;
-            return (_PyInterpreterFrame *)base;
+            return (_Py_frame *)base;
         }
     }
     return _PyThreadState_BumpFramePointerSlow(tstate, size);
 }
 
-void _PyThreadState_PopFrame(PyThreadState *tstate, _PyInterpreterFrame *frame);
+void _PyThreadState_PopFrame(PyThreadState *tstate, _Py_frame *frame);
 
 /* Consume reference to func */
-_PyInterpreterFrame *
+_Py_frame *
 _PyFrame_Push(PyThreadState *tstate, PyFunctionObject *func);
 
 #ifdef __cplusplus

diff --git a/Misc/NEWS.d/next/Core and Builtins/2022-03-19-21-47-36.bpo-44800.XnGKoD.rst b/Misc/NEWS.d/next/Core and Builtins/2022-03-19-21-47-36.bpo-44800.XnGKoD.rst
@@ -0,0 +1,9 @@
+Renamed ``_PyInterpreterFrame`` as ``_Py_frame`` to emphasise its close
+association with ``PyFrameObject`` (they're conceptually the same thing, but
+split into a Python object struct and a C data struct as a performance
+optimisation).
+
+The ``f_`` prefix has been removed from all ``_Py_frame`` fields that previously
+used it, so the presence or absence of the prefix provides a way to infer
+the exact type of a frame pointer when reading an isolated snippet in a code
+diff.
diff --git a/Misc/gdbinit b/Misc/gdbinit
@@ -37,9 +37,9 @@ end
 
 define pylocals
     set $_i = 0
-    while $_i < f->f_code->co_nlocals
+    while $_i < f->code->co_nlocals
 	if f->f_localsplus + $_i != 0
-	    set $_names = f->f_code->co_varnames
+	    set $_names = f->code->co_varnames
 	    set $_name = PyUnicode_AsUTF8(PyTuple_GetItem($_names, $_i))
 	    printf "%s:\n", $_name
             pyo f->f_localsplus[$_i]
@@ -55,8 +55,8 @@ end
 # command language
 define lineno
     set $__continue = 1
-    set $__co = f->f_code
-    set $__lasti = f->f_lasti
+    set $__co = f->code
+    set $__lasti = f->lasti
     set $__sz = ((PyVarObject *)$__co->co_lnotab)->ob_size/2
     set $__p = (unsigned char *)((PyBytesObject *)$__co->co_lnotab)->ob_sval
     set $__li = $__co->co_firstlineno
@@ -84,8 +84,8 @@ document pyframev
 end
 
 define pyframe
-    set $__fn = PyUnicode_AsUTF8(f->f_code->co_filename)
-    set $__n = PyUnicode_AsUTF8(f->f_code->co_name)
+    set $__fn = PyUnicode_AsUTF8(f->code->co_filename)
+    set $__n = PyUnicode_AsUTF8(f->code->co_name)
     printf "%s (", $__fn
     lineno
     printf "): %s\n", $__n