bpo-45431: Rename CFrame to _PyCFrame in the C API (GH-31584)

Rename also struct _cframe to struct _PyCFrame.

Add a comment suggesting using public functions rather than using
directly the private _PyCFrame structure.

Author: vstinner

Include/cpython/pystate.h

@@ -33,7 +33,9 @@ typedef struct {
     PyCodeAddressRange bounds; // Only valid if code != NULL.
 } PyTraceInfo;
 
-typedef struct _cframe {
+// Internal structure: you should not use it directly, but use public functions
+// like PyThreadState_EnterTracing() and PyThreadState_LeaveTracing().
+typedef struct _PyCFrame {
     /* This struct will be threaded through the C stack
      * allowing fast access to per-thread state that needs
      * to be accessed quickly by the interpreter, but can
@@ -47,8 +49,8 @@ typedef struct _cframe {
     int use_tracing;
     /* Pointer to the currently executing frame (it can be NULL) */
     struct _PyInterpreterFrame *current_frame;
-    struct _cframe *previous;
-} CFrame;
+    struct _PyCFrame *previous;
+} _PyCFrame;
 
 typedef struct _err_stackitem {
     /* This struct represents a single execution context where we might
@@ -102,9 +104,9 @@ struct _ts {
        the trace/profile. */
     int tracing;
 
-    /* Pointer to current CFrame in the C stack frame of the currently,
+    /* Pointer to current _PyCFrame in the C stack frame of the currently,
      * or most recently, executing _PyEval_EvalFrameDefault. */
-    CFrame *cframe;
+    _PyCFrame *cframe;
 
     Py_tracefunc c_profilefunc;
     Py_tracefunc c_tracefunc;
@@ -196,7 +198,7 @@ struct _ts {
     _PyErr_StackItem exc_state;
 
     /* The bottom-most frame on the stack. */
-    CFrame root_cframe;
+    _PyCFrame root_cframe;
 };
 
 

Include/internal/pycore_frame.h

@@ -59,7 +59,7 @@ typedef struct _PyInterpreterFrame {
     int f_lasti;       /* Last instruction if called */
     int stacktop;     /* Offset of TOS from localsplus  */
     PyFrameState f_state;  /* What state the frame is in */
-    bool is_entry;  // Whether this is the "root" frame for the current CFrame.
+    bool is_entry;  // Whether this is the "root" frame for the current _PyCFrame.
     bool is_generator;
     PyObject *localsplus[1];
 } _PyInterpreterFrame;

Python/ceval.c

@@ -1616,15 +1616,15 @@ _PyEval_EvalFrameDefault(PyThreadState *tstate, _PyInterpreterFrame *frame, int
     int oparg;         /* Current opcode argument, if any */
     _Py_atomic_int * const eval_breaker = &tstate->interp->ceval.eval_breaker;
 
-    CFrame cframe;
+    _PyCFrame cframe;
     CallShape call_shape;
     call_shape.kwnames = NULL; // Borrowed reference. Reset by CALL instructions.
 
-    /* WARNING: Because the CFrame lives on the C stack,
+    /* WARNING: Because the _PyCFrame lives on the C stack,
      * but can be accessed from a heap allocated object (tstate)
      * strict stack discipline must be maintained.
      */
-    CFrame *prev_cframe = tstate->cframe;
+    _PyCFrame *prev_cframe = tstate->cframe;
     cframe.use_tracing = prev_cframe->use_tracing;
     cframe.previous = prev_cframe;
     tstate->cframe = &cframe;