gh-148925: Add signal-safe PyUnstable_* APIs for call-stack iteration

Add four new public APIs for walking the Python call stack without
allocating memory, changing reference counts, or acquiring the GIL,
making them safe to call from signal handlers and custom memory
allocator hooks:

- PyUnstable_ThreadState_GetInterpreterFrame(tstate): returns the
  innermost complete interpreter frame, skipping entry trampolines
  and pre-RESUME frames automatically.
- PyUnstable_InterpreterFrame_GetNextComplete(frame): returns the
  next complete calling frame, skipping incomplete frames.  Mirrors
  PyFrame_GetBack semantics without allocating.
- PyUnstable_InterpreterFrame_GetCodeSafe(frame): returns a borrowed
  reference to the code object, or NULL if freed memory is detected.
- PyUnstable_InterpreterFrame_GetLineSafe(frame): returns the current
  line number, validating the instruction offset rather than asserting,
  safe when the frame may be partially torn down.

All four use _Py_NO_SANITIZE_THREAD to suppress intentional racy reads
and heuristics (_PyMem_IsPtrFreed) to detect freed memory.

Switch tracemalloc and the fatal error traceback printer to use the
new APIs instead of internal helpers.  Add tests in
Lib/test/test_capi/test_misc.py and test helpers in
Modules/_testinternalcapi.c.

Author: danielsn

Doc/c-api/frame.rst

@@ -226,11 +226,31 @@ Unless using :pep:`523`, you will not need this.
 
 .. c:function:: PyObject* PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);
 
-    Return a :term:`strong reference` to the code object for the frame.
+   Return a :term:`strong reference` to the code object for the frame.
+   Does not raise an exception.
+
+   If allocation and reference count changes are not permitted (for example,
+   from a signal handler or a custom memory allocator), use
+   :c:func:`PyUnstable_InterpreterFrame_GetCodeSafe` instead.
 
    .. versionadded:: 3.12
 
 
+.. c:function:: PyObject* PyUnstable_InterpreterFrame_GetCodeSafe(struct _PyInterpreterFrame *frame);
+
+   Return a :term:`borrowed reference` to the code object for the frame.
+   The reference is valid as long as the frame is alive.
+
+   Use this instead of :c:func:`PyUnstable_InterpreterFrame_GetCode` when
+   allocation and reference count changes are not permitted (for example,
+   from a signal handler or a custom memory allocator).  Does not allocate
+   memory, does not change any reference counts, does not acquire or release
+   the GIL, and does not raise an exception.  Uses heuristics to detect freed
+   memory — not 100% reliable in the presence of concurrent deallocation.
+
+   .. versionadded:: 3.15
+
+
 .. c:function:: int PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);
 
    Return the byte offset into the last executed instruction.
@@ -243,3 +263,53 @@ Unless using :pep:`523`, you will not need this.
    Return the currently executing line number, or -1 if there is no line number.
 
    .. versionadded:: 3.12
+
+
+.. c:function:: int PyUnstable_InterpreterFrame_GetLineSafe(struct _PyInterpreterFrame *frame)
+
+   Return the currently executing line number, or ``-1`` if there is no line
+   number or the frame is invalid.  Does not raise an exception.
+
+   Unlike :c:func:`PyUnstable_InterpreterFrame_GetLine`, validates the code
+   object and instruction offset before accessing the line table rather than
+   asserting them, making it safe to call when the frame state may be
+   partially torn down.
+
+   .. versionadded:: 3.15
+
+
+.. c:function:: struct _PyInterpreterFrame* PyUnstable_ThreadState_GetInterpreterFrame(PyThreadState *tstate)
+
+   Return the innermost complete interpreter frame of *tstate*, or ``NULL`` if
+   the thread has no complete frame or freed memory is detected.  Incomplete
+   frames (interpreter entry trampolines and frames that have not yet begun
+   executing) are skipped automatically.
+
+   Does not allocate memory, does not raise an exception, and does not acquire
+   or release the GIL.  Safe to call from a signal handler; racy reads from
+   other threads are intentional.  Uses heuristics to detect freed memory —
+   not 100% reliable in the presence of concurrent deallocation.
+
+   To iterate over the full call stack, call
+   :c:func:`PyUnstable_InterpreterFrame_GetNextComplete` repeatedly on the
+   returned frame until it returns ``NULL``.
+
+   .. versionadded:: 3.15
+
+
+.. c:function:: struct _PyInterpreterFrame* PyUnstable_InterpreterFrame_GetNextComplete(struct _PyInterpreterFrame *frame)
+
+   Return the next (calling) complete frame, or ``NULL`` if *frame* is the
+   outermost complete frame or freed memory is detected.  Incomplete frames are
+   skipped automatically.
+
+   Does not allocate memory, does not raise an exception, and does not acquire
+   or release the GIL.  Safe to call from a signal handler; racy reads from
+   other threads are intentional.  Uses heuristics to detect freed memory —
+   not 100% reliable in the presence of concurrent deallocation.
+
+   Unlike :c:func:`PyFrame_GetBack`, this function never allocates memory,
+   making it safe to call from a custom memory allocator hook without risking
+   re-entrant allocation.
+
+   .. versionadded:: 3.15

Include/cpython/pyframe.h

@@ -25,9 +25,20 @@ PyAPI_FUNC(PyObject*) PyFrame_GetVarString(PyFrameObject *frame, const char *nam
 struct _PyInterpreterFrame;
 
 /* Returns the code object of the frame (strong reference).
- * Does not raise an exception. */
+ * Does not raise an exception.
+ * If allocation and reference count changes are not permitted, use
+ * PyUnstable_InterpreterFrame_GetCodeSafe instead. */
 PyAPI_FUNC(PyObject *) PyUnstable_InterpreterFrame_GetCode(struct _PyInterpreterFrame *frame);
 
+/* Returns the code object of the frame as a borrowed reference.
+ * The reference is valid as long as the frame is alive.
+ * Use instead of PyUnstable_InterpreterFrame_GetCode when allocation and
+ * reference count changes are not permitted (e.g. from a signal handler or
+ * a custom memory allocator).  Does not allocate, does not change any
+ * reference counts, does not acquire or release the GIL, does not raise an
+ * exception.  Uses heuristics to detect freed memory; not 100% reliable. */
+PyAPI_FUNC(PyObject *) PyUnstable_InterpreterFrame_GetCodeSafe(struct _PyInterpreterFrame *frame);
+
 /* Returns a byte offset into the last executed instruction.
  * Does not raise an exception. */
 PyAPI_FUNC(int) PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame *frame);
@@ -36,6 +47,36 @@ PyAPI_FUNC(int) PyUnstable_InterpreterFrame_GetLasti(struct _PyInterpreterFrame
  * Does not raise an exception. */
 PyAPI_FUNC(int) PyUnstable_InterpreterFrame_GetLine(struct _PyInterpreterFrame *frame);
 
+/* Returns the currently executing line number, or -1 if there is no line
+ * number or the frame is invalid.
+ * Unlike PyUnstable_InterpreterFrame_GetLine, validates the code object and
+ * instruction offset before accessing the line table rather than asserting
+ * them, making it safe to call when the frame state may be partially torn
+ * down.  Does not raise an exception. */
+PyAPI_FUNC(int) PyUnstable_InterpreterFrame_GetLineSafe(struct _PyInterpreterFrame *frame);
+
+
+/* Returns the innermost complete interpreter frame of the thread state, or
+ * NULL if the thread has no complete frame or freed memory is detected.
+ * Skips over incomplete frames (interpreter entry trampolines and frames that
+ * have not yet begun executing) automatically.
+ * Does not allocate memory, does not acquire or release the GIL, does not
+ * raise an exception.  Safe to call from signal handlers; racy reads from
+ * other threads are intentional and suppressed (_Py_NO_SANITIZE_THREAD).
+ * Uses heuristics to detect freed memory; not 100% reliable. */
+PyAPI_FUNC(struct _PyInterpreterFrame *)
+PyUnstable_ThreadState_GetInterpreterFrame(PyThreadState *tstate);
+
+/* Returns the next (calling) complete frame, or NULL if frame is the
+ * outermost complete frame or freed memory is detected.
+ * Skips over incomplete frames automatically.
+ * Does not allocate memory, does not acquire or release the GIL, does not
+ * raise an exception.  Safe to call from signal handlers; racy reads from
+ * other threads are intentional and suppressed (_Py_NO_SANITIZE_THREAD).
+ * Uses heuristics to detect freed memory; not 100% reliable. */
+PyAPI_FUNC(struct _PyInterpreterFrame *)
+PyUnstable_InterpreterFrame_GetNextComplete(struct _PyInterpreterFrame *frame);
+
 #define PyUnstable_EXECUTABLE_KIND_SKIP 0
 #define PyUnstable_EXECUTABLE_KIND_PY_FUNCTION 1
 #define PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION 3

Lib/test/test_capi/test_misc.py

@@ -2789,6 +2789,86 @@ def test_line(self):
         firstline = self.func.__code__.co_firstlineno
         self.assertEqual(line, firstline + 2)
 
+    def test_tstate_getframe_is_current(self):
+        # PyUnstable_ThreadState_GetInterpreterFrame must return the same
+        # PyFrameObject as sys._getframe(0) when called at the same level.
+        frame_from_c = _testinternalcapi.tstate_getframe()
+        self.assertIs(frame_from_c, sys._getframe(0))
+
+    def test_getnextcomplete_matches_f_back(self):
+        # GetNextComplete must match f_back at every step, all the way to None.
+        c_frame = _testinternalcapi.tstate_getframe()
+        py_frame = sys._getframe(0)
+        while c_frame is not None:
+            self.assertIs(c_frame, py_frame)
+            c_frame = _testinternalcapi.iframe_getnextcomplete(c_frame)
+            py_frame = py_frame.f_back
+        self.assertIsNone(py_frame)
+
+    def test_stack_to_yaml(self):
+        # stack_to_yaml uses only signal-safe operations for the walk and
+        # emission (no allocation, no refcount changes, no GIL release).
+        # Verify the output is well-formed and contains the expected frames.
+        def inner():
+            return _testinternalcapi.stack_to_yaml()
+
+        yaml_str = inner()
+        self.assertIsInstance(yaml_str, str)
+
+        # Parse the YAML manually to avoid a PyYAML dependency.
+        # Format is blocks of:
+        #   - filename: <path>
+        #     name: <name>
+        #     lineno: <n>
+        frames = []
+        current = {}
+        for line in yaml_str.splitlines():
+            if line.startswith('- filename: '):
+                if current:
+                    frames.append(current)
+                current = {'filename': line[len('- filename: '):]}
+            elif line.startswith('  name: '):
+                current['name'] = line[len('  name: '):]
+            elif line.startswith('  lineno: '):
+                current['lineno'] = int(line[len('  lineno: '):])
+        if current:
+            frames.append(current)
+
+        self.assertGreater(len(frames), 1)
+        # Innermost frame is the Python function that called stack_to_yaml.
+        self.assertEqual(frames[0]['name'], 'inner')
+        # Next frame is this test method.
+        self.assertEqual(frames[1]['name'], 'test_stack_to_yaml')
+        # Every frame must have a non-empty filename and a valid lineno.
+        for f in frames:
+            self.assertTrue(f.get('filename'), f)
+            self.assertIsInstance(f.get('lineno'), int, f)
+
+    def test_getcodesafe_matches_fcode(self):
+        # GetCodeSafe must return the same code object as frame.f_code.
+        frame = _testinternalcapi.tstate_getframe()
+        self.assertIs(_testinternalcapi.iframe_getcodesafe(frame), frame.f_code)
+
+
+    def test_iframe_getlinesafe(self):
+        # Use a generator frame frozen at a yield point so that iframe_getlasti
+        # and iframe_getlinesafe both read the same (stable) instruction pointer.
+        def gen():
+            yield
+        g = gen()
+        next(g)
+        frame = g.gi_frame
+        lasti = _testinternalcapi.iframe_getlasti(frame)
+        lineno = _testinternalcapi.iframe_getlinesafe(frame)
+        if lasti >= 0:
+            expected = None
+            for start, end, ln in frame.f_code.co_lines():
+                if ln is not None and start <= lasti < end:
+                    expected = ln
+                    break
+            if expected is not None:
+                self.assertEqual(lineno, expected)
+
 
 SUFFICIENT_TO_DEOPT_AND_SPECIALIZE = 100
 

Misc/NEWS.d/next/C_API/2026-04-23-14-08-40.gh-issue-148925.qnLUh5.rst

@@ -0,0 +1,7 @@
+Add four new ``PyUnstable_*`` C API functions for signal-safe, allocation-free
+call-stack iteration: :c:func:`PyUnstable_ThreadState_GetInterpreterFrame`,
+:c:func:`PyUnstable_InterpreterFrame_GetNextComplete`,
+:c:func:`PyUnstable_InterpreterFrame_GetCodeSafe`, and
+:c:func:`PyUnstable_InterpreterFrame_GetLineSafe`.  These functions do not
+allocate memory, do not change reference counts, and do not acquire the GIL,
+making them safe to call from signal handlers and custom memory allocator hooks.