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

Doc/c-api/index.rst

@@ -17,6 +17,7 @@ document the API functions in detail.
    veryhigh.rst
    refcounting.rst
    exceptions.rst
+   traceback.rst
    extension-modules.rst
    utilities.rst
    abstract.rst

Doc/c-api/traceback.rst

@@ -0,0 +1,96 @@
+.. highlight:: c
+
+
+.. _traceback:
+
+**********
+Tracebacks
+**********
+
+The functions below collect Python stack frames into a caller-supplied array of
+:c:type:`PyUnstable_FrameInfo` structs.  Because they do not acquire or release
+the GIL or allocate heap memory, they can be called from signal handlers and
+are suitable for low-overhead observability tools such as sampling profilers
+and tracers.
+
+.. c:function:: int PyUnstable_CollectCallStack(PyThreadState *tstate, PyUnstable_FrameInfo *frames, int max_frames)
+
+   Collect up to *max_frames* frames from *tstate* into the caller-supplied
+   *frames* array and return the number of frames written (0..*max_frames*).
+   Returns ``-1`` if *frames* is NULL, *tstate* is freed, or *tstate* has no
+   current Python frame.
+
+   Filenames and function names are ASCII-encoded (non-ASCII characters are
+   backslash-escaped) and truncated to 500 characters; if truncated, the
+   corresponding ``filename_truncated`` or ``name_truncated`` field is set
+   to ``1``.
+
+   In crash scenarios such as signal handlers for SIGSEGV, where the
+   interpreter may be in an inconsistent state, the function might produce
+   incomplete output or it may even crash itself.
+
+   The caller does not need to hold an attached thread state, nor does *tstate*
+   need to be attached.
+
+   This function does not acquire or release the GIL, modify reference counts,
+   or allocate heap memory.
+
+   .. versionadded:: next
+
+.. c:function:: void PyUnstable_PrintCallStack(int fd, const PyUnstable_FrameInfo *frames, int n_frames, int write_header)
+
+   Write a traceback collected by :c:func:`PyUnstable_CollectCallStack` to
+   *fd*.  The format looks like::
+
+      Stack (most recent call first):
+        File "foo/bar.py", line 42 in myfunc
+        File "foo/bar.py", line 99 in caller
+
+   Pass *write_header* as ``1`` to emit the ``Stack (most recent call first):``
+   header line, or ``0`` to omit it.  Truncated filenames and function names
+   are followed by ``...``.
+
+   This function only reads the caller-supplied *frames* array and does not
+   access interpreter state.  It is async-signal-safe: it does not acquire or
+   release the GIL, modify reference counts, or allocate heap memory, and its
+   only I/O is via :c:func:`!write`.
+
+   .. versionadded:: next
+
+.. c:type:: PyUnstable_FrameInfo
+
+   A plain-data struct representing a single Python stack frame, suitable for
+   use in crash-handling code.  Populated by
+   :c:func:`PyUnstable_CollectCallStack`.
+
+   .. c:member:: int lineno
+
+      The line number, or ``-1`` if unknown.
+
+   .. c:member:: int filename_truncated
+
+      ``1`` if :c:member:`filename` was truncated, ``0`` otherwise.
+
+   .. c:member:: int name_truncated
+
+      ``1`` if :c:member:`name` was truncated, ``0`` otherwise.
+
+   .. c:member:: char filename[Py_UNSTABLE_FRAMEINFO_STRSIZE]
+
+      The source filename, ASCII-encoded with ``backslashreplace`` and
+      null-terminated.  Empty string if unavailable.
+
+   .. c:member:: char name[Py_UNSTABLE_FRAMEINFO_STRSIZE]
+
+      The function name, ASCII-encoded with ``backslashreplace`` and
+      null-terminated.  Empty string if unavailable.
+
+   .. versionadded:: next
+
+.. c:macro:: Py_UNSTABLE_FRAMEINFO_STRSIZE
+
+   The size in bytes of the :c:member:`PyUnstable_FrameInfo.filename` and
+   :c:member:`PyUnstable_FrameInfo.name` character arrays (``501``): up to
+   500 content bytes plus a null terminator.
+
+   .. versionadded:: next

Include/cpython/traceback.h

@@ -11,3 +11,71 @@ struct _traceback {
     int tb_lasti;
     int tb_lineno;
 };
+
+/* Buffer size for the filename and name fields in PyUnstable_FrameInfo:
+   up to 500 content bytes plus '\0' (1). */
+#define Py_UNSTABLE_FRAMEINFO_STRSIZE 501
+
+/* Structured, plain-data representation of a single Python frame.
+   PyUnstable_CollectCallStack and PyUnstable_PrintCallStack() do not
+   acquire or release the GIL or allocate heap memory, so they can be called
+   from signal handlers and are suitable for low-overhead observability tools
+   such as sampling profilers and tracers.
+
+   Populated by PyUnstable_CollectCallStack.  filename and name are
+   ASCII-encoded (non-ASCII characters are backslash-escaped) and
+   null-terminated; they are empty strings if the corresponding code
+   attribute is missing or not a unicode object.  lineno is -1 when it
+   cannot be determined.  filename_truncated and name_truncated are 1 if
+   the respective string was longer than Py_UNSTABLE_FRAMEINFO_STRSIZE-1
+   bytes and was truncated. */
+typedef struct {
+    int lineno;
+    int filename_truncated;
+    int name_truncated;
+    char filename[Py_UNSTABLE_FRAMEINFO_STRSIZE];
+    char name[Py_UNSTABLE_FRAMEINFO_STRSIZE];
+} PyUnstable_FrameInfo;
+
+/* Collect up to max_frames frames from tstate into the caller-supplied
+   frames array and return the number of frames written (0..max_frames).
+   Returns -1 if frames is NULL, tstate is freed, or tstate has no current
+   Python frame.
+
+   The filename and function names are encoded to ASCII with backslashreplace
+   and truncated to 500 characters; when truncated, the corresponding
+   filename_truncated or name_truncated field is set to 1.
+
+   In crash scenarios such as signal handlers for SIGSEGV, where the
+   interpreter may be in an inconsistent state, the function might produce
+   incomplete output or it may even crash itself.
+
+   The caller does not need to hold an attached thread state, nor does tstate
+   need to be attached.
+
+   This function does not acquire or release the GIL, modify reference counts,
+   or allocate heap memory. */
+PyAPI_FUNC(int) PyUnstable_CollectCallStack(
+    PyThreadState *tstate,
+    PyUnstable_FrameInfo *frames,
+    int max_frames);
+
+/* Write a traceback collected by PyUnstable_CollectCallStack to fd.
+   The format looks like:
+
+      Stack (most recent call first):
+        File "foo/bar.py", line 42 in myfunc
+        File "foo/bar.py", line 99 in caller
+
+   Pass write_header=1 to emit the "Stack (most recent call first):" header
+   line, or write_header=0 to omit it.
+
+   This function only reads the caller-supplied frames array and does not
+   access interpreter state.  It is async-signal-safe: it does not acquire or
+   release the GIL, modify reference counts, or allocate heap memory, and its
+   only I/O is via write(2). */
+PyAPI_FUNC(void) PyUnstable_PrintCallStack(
+    int fd,
+    const PyUnstable_FrameInfo *frames,
+    int n_frames,
+    int write_header);

Include/internal/pycore_traceback.h

@@ -14,6 +14,9 @@ PyAPI_FUNC(int) _Py_DisplaySourceLine(PyObject *, PyObject *, int, int, int *, P
 // Export for 'pyexact' shared extension
 PyAPI_FUNC(void) _PyTraceback_Add(const char *, const char *, int);
 
+#include "traceback.h"  /* PyUnstable_FrameInfo, PyUnstable_CollectCallStack,
+                           PyUnstable_PrintCallStack */
+
 /* Write the Python traceback into the file 'fd'. For example:
 
        Traceback (most recent call first):