Add support for Python 3.14 tail call interpreter patterns

Implement support for Python 3.14's tail call interpreter in Memray. The
changes enable Memray to correctly identify Python frame boundaries when
native stack traces contain LLVM-generated tail call functions.

Signed-off-by: Pablo Galindo Salgado <[email protected]>

Author: Copilot

.github/workflows/test_uv_python.yml

@@ -0,0 +1,58 @@
+name: UV Python Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  test_uv_python:
+    name: "Test with UV Python 3.14"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv and set Python 3.14
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+
+      - name: Create virtual environment
+        run: |
+          uv venv --python 3.14
+
+      - name: Set up system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -qy \
+            pkg-config \
+            libdebuginfod-dev \
+            libunwind-dev \
+            liblz4-dev \
+            gdb \
+            npm
+
+      - name: Install Python dependencies
+        run: |
+          uv pip install --upgrade pip cython pkgconfig
+          uv pip install -r requirements-test.txt
+
+      - name: Build package
+        run: |
+          make build-js
+          uv pip install -e .
+
+      - name: Disable ptrace security restrictions
+        run: |
+          echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
+
+      - name: Run tests
+        run: |
+          uv run pytest -vvv --log-cli-level=info tests

news/836.bugfix.rst

@@ -0,0 +1 @@
+Add support for Python 3.14's tail call interpreter. Memray now correctly identifies Python frame boundaries in native stack traces when Python 3.14 is built with the tail call interpreter enabled (``--with-tail-call-interp``), recognizing LLVM-generated tail call functions alongside traditional ``_PyEval_EvalFrameDefault`` functions.

src/memray/_memray.pyx

@@ -247,7 +247,12 @@ cdef hybrid_stack_trace(
 
     for native_frame in native_stack:
         symbol = native_frame[0]
-        if pidx >= 0 and "_PyEval_EvalFrameDefault" in symbol:
+        # Check for Python frame boundaries: traditional _PyEval_EvalFrameDefault
+        # or Python 3.14 tail call interpreter LLVM-generated functions
+        is_python_frame_boundary = "_PyEval_EvalFrameDefault" in symbol or (
+            symbol.startswith("_TAIL_CALL_") and ".llvm." in symbol
+        )
+        if pidx >= 0 and is_python_frame_boundary:
             while True:
                 # If we're not keeping all frames and we've reached the
                 # first one we want to keep, remove frames above it.
@@ -272,7 +277,8 @@ cdef hybrid_stack_trace(
         # We ran out of native frames without using up all of our Python
         # frames. We've seen this happen on stripped interpreters on Alpine
         # Linux in CI. Presumably this indicates that unwinding failed to
-        # symbolify some of the calls to _PyEval_EvalFrameDefault.
+        # symbolify some of the Python frame boundaries (_PyEval_EvalFrameDefault
+        # or Python 3.14 tail call interpreter functions).
         return python_stack
     assert hidx == -1
 
@@ -1642,7 +1648,12 @@ def get_symbolic_support():
     locations = unwindHere()
     for location in locations:
         function, file, line = location.split(":")
-        if function != "_PyEval_EvalFrameDefault":
+        # Check for Python frame boundaries: traditional _PyEval_EvalFrameDefault
+        # or Python 3.14 tail call interpreter LLVM-generated functions
+        is_python_frame_boundary = function == "_PyEval_EvalFrameDefault" or (
+            function.startswith("_TAIL_CALL_") and ".llvm." in function
+        )
+        if not is_python_frame_boundary:
             continue
         if not file:
             return SymbolicSupport.FUNCTION_NAME_ONLY

src/memray/reporters/frame_tools.py

@@ -38,6 +38,9 @@
 def _is_cpython_internal_symbol(symbol: str, file: str) -> bool:
     if "PyEval_EvalFrameEx" in symbol or "_PyEval_EvalFrameDefault" in symbol:
         is_candidate = True
+    elif symbol.startswith("_TAIL_CALL_") and ".llvm." in symbol:
+        # Python 3.14 tail call interpreter uses LLVM-generated functions
+        is_candidate = True
     elif symbol.startswith(("PyEval", "_Py")):
         is_candidate = True
     elif "vectorcall" in symbol.lower():

tests/unit/test_frame_tools.py

@@ -31,8 +31,32 @@ class TestFrameFiltering:
                 ),
                 True,
             ],
+            # Python 3.14 tail call interpreter LLVM-generated functions
+            [
+                (
+                    "_TAIL_CALL_INSTRUMENTED_CALL.llvm.10282351651392433962",
+                    "/src/python/python3.14/Python/ceval.c",
+                    100,
+                ),
+                True,
+            ],
+            [
+                (
+                    "_TAIL_CALL_POP_TOP.llvm.123456789",
+                    "/src/python/python3.14/Python/ceval.c",
+                    50,
+                ),
+                True,
+            ],
             [("somefunc", "myapp.py", 100), False],
             [("function_code_fastcall", "myapp.py", 100), False],
+            # _TAIL_CALL_ pattern should not match without .llvm.
+            [
+                ("_TAIL_CALL_SOMETHING", "/src/python/python3.14/Python/ceval.c", 100),
+                False,
+            ],
+            # _TAIL_CALL_ pattern should not match in non-CPython files
+            [("_TAIL_CALL_SOMETHING.llvm.123", "myapp.py", 100), False],
         ],
     )
     def test_cpython_internal_calls(self, frame, expected):
@@ -51,6 +75,15 @@ def test_cpython_internal_calls(self, frame, expected):
                 ),
                 False,
             ],
+            # Python 3.14 tail call interpreter frames should not be interesting
+            [
+                (
+                    "_TAIL_CALL_INSTRUMENTED_CALL.llvm.10282351651392433962",
+                    "/src/python/python3.14/Python/ceval.c",
+                    100,
+                ),
+                False,
+            ],
             [
                 (
                     "PyArg_ParseTuple",