gh-138122: Add incomplete sample detection and fix generator frame unwinding

Add PyThreadState.entry_frame to track the bottommost frame in each thread.
The profiler validates unwinding reached this frame, rejecting incomplete
samples caused by race conditions or errors. Also fix unwinding to skip
suspended generator frames which have NULL previous pointers.

Author: pablogsal

Include/cpython/pystate.h

@@ -135,6 +135,11 @@ struct _ts {
     /* Pointer to currently executing frame. */
     struct _PyInterpreterFrame *current_frame;
 
+    /* Pointer to the entry/bottommost frame of the current call stack.
+     * This is the frame that was entered when starting execution.
+     * Used by profiling/sampling to detect incomplete stack traces. */
+    struct _PyInterpreterFrame *entry_frame;
+
     Py_tracefunc c_profilefunc;
     Py_tracefunc c_tracefunc;
     PyObject *c_profileobj;

Include/internal/pycore_debug_offsets.h

@@ -102,6 +102,7 @@ typedef struct _Py_DebugOffsets {
         uint64_t next;
         uint64_t interp;
         uint64_t current_frame;
+        uint64_t entry_frame;
         uint64_t thread_id;
         uint64_t native_thread_id;
         uint64_t datastack_chunk;
@@ -272,6 +273,7 @@ typedef struct _Py_DebugOffsets {
         .next = offsetof(PyThreadState, next), \
         .interp = offsetof(PyThreadState, interp), \
         .current_frame = offsetof(PyThreadState, current_frame), \
+        .entry_frame = offsetof(PyThreadState, entry_frame), \
         .thread_id = offsetof(PyThreadState, thread_id), \
         .native_thread_id = offsetof(PyThreadState, native_thread_id), \
         .datastack_chunk = offsetof(PyThreadState, datastack_chunk), \

Misc/NEWS.d/next/Core_and_Builtins/2025-11-24-16-07-57.gh-issue-138122.m3EF9E.rst

@@ -0,0 +1,11 @@
+Fix profiler stack unwinding to skip generator frames with NULL previous
+pointers. Generator frames at yield points are suspended objects that don't
+link to callers via normal frame chains, causing incomplete stack traces.
+The profiler now correctly skips these frames during stack unwinding.
+
+Add incomplete sample detection to prevent corrupted profiling data. The
+interpreter now tracks the entry frame (bottommost frame) in each thread's
+``PyThreadState.entry_frame``, which the profiler uses to validate that
+stack unwinding reached the expected bottom. Samples that fail to unwind
+completely (due to race conditions, memory corruption, or other errors)
+are now rejected rather than being included as spurious single-frame stacks.

Modules/_remote_debugging_module.c

@@ -2254,15 +2254,22 @@ is_frame_valid(
     }
 
     void* frame = (void*)frame_addr;
+    char owner = GET_MEMBER(char, frame, unwinder->debug_offsets.interpreter_frame.owner);
 
-    if (GET_MEMBER(char, frame, unwinder->debug_offsets.interpreter_frame.owner) == FRAME_OWNED_BY_INTERPRETER) {
+    if (owner == FRAME_OWNED_BY_INTERPRETER) {
         return 0;  // C frame
     }
 
-    if (GET_MEMBER(char, frame, unwinder->debug_offsets.interpreter_frame.owner) != FRAME_OWNED_BY_GENERATOR
-        && GET_MEMBER(char, frame, unwinder->debug_offsets.interpreter_frame.owner) != FRAME_OWNED_BY_THREAD) {
-        PyErr_Format(PyExc_RuntimeError, "Unhandled frame owner %d.\n",
-                    GET_MEMBER(char, frame, unwinder->debug_offsets.interpreter_frame.owner));
+    // Reject generator frames with NULL previous pointer - can't unwind past them
+    if (owner == FRAME_OWNED_BY_GENERATOR) {
+        uintptr_t previous = GET_MEMBER(uintptr_t, frame, unwinder->debug_offsets.interpreter_frame.previous);
+        if (previous == 0) {
+            return 0;  // Generator frame with no caller - skip it
+        }
+    }
+
+    if (owner != FRAME_OWNED_BY_GENERATOR && owner != FRAME_OWNED_BY_THREAD) {
+        PyErr_Format(PyExc_RuntimeError, "Unhandled frame owner %d.\n", owner);
         set_exception_cause(unwinder, PyExc_RuntimeError, "Unhandled frame owner type in async frame");
         return -1;
     }
@@ -2475,14 +2482,17 @@ process_frame_chain(
     uintptr_t initial_frame_addr,
     StackChunkList *chunks,
     PyObject *frame_info,
-    uintptr_t gc_frame)
+    uintptr_t gc_frame,
+    uintptr_t entry_frame_addr)
 {
     uintptr_t frame_addr = initial_frame_addr;
     uintptr_t prev_frame_addr = 0;
+    uintptr_t last_frame_addr = 0;  // Track the last frame we processed
     const size_t MAX_FRAMES = 1024;
     size_t frame_count = 0;
 
     while ((void*)frame_addr != NULL) {
+        last_frame_addr = frame_addr;  // Remember this frame before moving to next
         PyObject *frame = NULL;
         uintptr_t next_frame_addr = 0;
         uintptr_t stackpointer = 0;
@@ -2564,6 +2574,17 @@ process_frame_chain(
         frame_addr = next_frame_addr;
     }
 
+    // Validate we reached the entry frame if it's set
+    if (entry_frame_addr != 0 && last_frame_addr != 0) {
+        if (last_frame_addr != entry_frame_addr) {
+            // We didn't reach the expected bottom frame - incomplete sample
+            PyErr_Format(PyExc_RuntimeError,
+                "Incomplete sample: reached frame 0x%lx but expected entry frame 0x%lx",
+                last_frame_addr, entry_frame_addr);
+            return -1;
+        }
+    }
+
     return 0;
 }
 
@@ -2806,7 +2827,13 @@ unwind_stack_for_thread(
         goto error;
     }
 
-    if (process_frame_chain(unwinder, frame_addr, &chunks, frame_info, gc_frame) < 0) {
+    // Read entry_frame for validation
+    uintptr_t entry_frame_addr = 0;
+    if (unwinder->debug_offsets.thread_state.entry_frame != 0) {
+        entry_frame_addr = GET_MEMBER(uintptr_t, ts, unwinder->debug_offsets.thread_state.entry_frame);
+    }
+
+    if (process_frame_chain(unwinder, frame_addr, &chunks, frame_info, gc_frame, entry_frame_addr) < 0) {
         set_exception_cause(unwinder, PyExc_RuntimeError, "Failed to process frame chain");
         goto error;
     }

Python/ceval.c

@@ -1234,6 +1234,10 @@ _PyEval_EvalFrameDefault(PyThreadState *tstate, _PyInterpreterFrame *frame, int
     entry.frame.previous = tstate->current_frame;
     frame->previous = &entry.frame;
     tstate->current_frame = frame;
+    /* Track entry frame for profiling/sampling */
+    if (entry.frame.previous == NULL) {
+        tstate->entry_frame = &entry.frame;
+    }
     entry.frame.localsplus[0] = PyStackRef_NULL;
 #ifdef _Py_TIER2
     if (tstate->current_executor != NULL) {
@@ -1300,6 +1304,10 @@ _PyEval_EvalFrameDefault(PyThreadState *tstate, _PyInterpreterFrame *frame, int
     assert(frame->owner == FRAME_OWNED_BY_INTERPRETER);
     /* Restore previous frame and exit */
     tstate->current_frame = frame->previous;
+    /* Clear entry frame if we're returning to no frame */
+    if (tstate->current_frame == NULL) {
+        tstate->entry_frame = NULL;
+    }
     return NULL;
 }
 #ifdef _Py_TIER2

Python/pystate.c

@@ -1483,6 +1483,7 @@ init_threadstate(_PyThreadStateImpl *_tstate,
     tstate->gilstate_counter = 1;
 
     tstate->current_frame = NULL;
+    tstate->entry_frame = NULL;
     tstate->datastack_chunk = NULL;
     tstate->datastack_top = NULL;
     tstate->datastack_limit = NULL;