test(callgrind-utils): add Python fixture with runtime obj-skip

Profile a Python workload (recursion.py) live under the in-repo Callgrind,
mirroring pytest-codspeed: a ctypes-loaded shim (clgctl.c) fires
CALLGRIND_START/STOP and adds libpython + the python executable to the
obj-skip list at runtime via CALLGRIND_ADD_OBJ_SKIP. Callgrind never names
Python-level frames, so the test asserts structure rather than a golden
snapshot: the START shim is captured and the Python runtime is folded out.

Author: not-matthias

callgrind-utils/testdata/clgctl.c

@@ -0,0 +1,28 @@
+// Callgrind client-request shim for the Python fixture (`recursion.py`).
+//
+// The CALLGRIND_* client requests are inline-asm sequences, so they can't be
+// issued from pure Python. The Python fixture loads this shared library via
+// `ctypes` and calls these entry points to drive instrumentation, mirroring
+// what pytest-codspeed's instrument-hooks does: skip the Python runtime objects
+// at runtime, then START/ZERO around the measured region and STOP after.
+//
+// Build (shared, against the in-repo client-request headers):
+//   cc -g -O0 -shared -fPIC -I callgrind -I include ...
+
+#include <callgrind.h>
+
+// Add an object file to Callgrind's obj-skip list at runtime. Matching is exact
+// against the mapped object path, so the caller passes a realpath (same as
+// instrument-hooks' `callgrind_add_obj_skip`).
+void clg_add_obj_skip(const char *path) {
+    CALLGRIND_ADD_OBJ_SKIP(path);
+}
+
+void clg_start(void) {
+    CALLGRIND_START_INSTRUMENTATION;
+    CALLGRIND_ZERO_STATS;
+}
+
+void clg_stop(void) {
+    CALLGRIND_STOP_INSTRUMENTATION;
+}

callgrind-utils/testdata/recursion.py

@@ -0,0 +1,59 @@
+# Python counterpart to recursion.c: the same fib/square/compute shape, driven
+# the way CodSpeed drives a benchmark. Instrumentation is off at startup (run
+# with --instr-atstart=no) and turned on around the measured region via the
+# clgctl shim, whose compiled path is passed as argv[1].
+#
+# Before starting, we skip the Python runtime objects (libpython + the python
+# executable) from Callgrind at runtime, exactly as pytest-codspeed's
+# instrument-hooks does in _callgrind_skip_python_runtime: the interpreter's own
+# C frames are folded into their callers so they don't obfuscate the graph.
+# Matching is by exact realpath, since Callgrind keys obj-skip on the mapped
+# object path.
+import ctypes
+import os
+import sys
+import sysconfig
+
+clgctl = ctypes.CDLL(sys.argv[1])
+
+
+def skip_python_runtime():
+    ldlibrary = sysconfig.get_config_var("LDLIBRARY")
+    libdir = sysconfig.get_config_var("LIBDIR")
+    libpython = next(
+        (
+            p
+            for p in (
+                os.path.join(libdir, ldlibrary) if ldlibrary and libdir else None,
+                os.path.join(sys.prefix, "lib", ldlibrary) if ldlibrary else None,
+            )
+            if p and os.path.exists(p)
+        ),
+        None,
+    )
+    for path in (libpython, sys.executable):
+        if path:
+            clgctl.clg_add_obj_skip(os.path.realpath(path).encode())
+
+
+def fib(n):
+    if n < 2:
+        return n
+    return fib(n - 1) + fib(n - 2)
+
+
+def square(n):
+    return n * n
+
+
+def compute(n):
+    return fib(n) + square(n)
+
+
+skip_python_runtime()
+
+clgctl.clg_start()
+sink = compute(8)
+clgctl.clg_stop()
+
+assert sink == 85, sink

callgrind-utils/tests/python_callgraph.rs

@@ -0,0 +1,174 @@
+//! Structural test over the Python fixture (`testdata/recursion.py`).
+//!
+//! Unlike the C snapshot tests, a live Python run can't be a golden snapshot:
+//! Callgrind sees the CPython interpreter's C frames (version- and
+//! platform-specific), never the Python functions. The fixture drives Callgrind
+//! the way pytest-codspeed does: at runtime it adds the Python runtime objects
+//! (libpython + the python executable) to the obj-skip list via the
+//! `CALLGRIND_ADD_OBJ_SKIP` client request, so the interpreter's own frames are
+//! folded into their callers and don't obfuscate the graph. This test profiles
+//! the fixture live and asserts structural properties: instrumentation started
+//! at the shim, and the runtime obj-skip removed the interpreter.
+//!
+//! Requires a built `./vg-in-place` at the repo root and `cc`. Silently skips
+//! when `python3` is not on PATH (mirrors the `.vgtest` `prereq` guards).
+use std::io::Cursor;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use callgrind_utils::model::{CallGraph, ParseOptions};
+
+/// Repo root: this crate lives at `<repo>/callgrind-utils`.
+fn repo_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .expect("crate has a parent directory")
+        .to_path_buf()
+}
+
+fn vg_in_place() -> PathBuf {
+    let path = repo_root().join("vg-in-place");
+    assert!(
+        path.is_file(),
+        "vg-in-place not found at {} - build Valgrind in place first",
+        path.display()
+    );
+    path
+}
+
+fn have_python3() -> bool {
+    Command::new("python3")
+        .arg("--version")
+        .output()
+        .map(|o| o.status.success())
+        .unwrap_or(false)
+}
+
+/// The basenames of the objects `recursion.py` adds to the obj-skip list:
+/// libpython and the python executable, resolved exactly as the fixture does
+/// (realpath, then basename, matching Callgrind's normalized object names).
+fn skipped_runtime_objects() -> Vec<String> {
+    let script = "\
+import os, sys, sysconfig
+ld = sysconfig.get_config_var('LDLIBRARY')
+libdir = sysconfig.get_config_var('LIBDIR')
+cands = [os.path.join(libdir, ld) if ld and libdir else None,
+         os.path.join(sys.prefix, 'lib', ld) if ld else None]
+lp = next((p for p in cands if p and os.path.exists(p)), None)
+for p in (lp, sys.executable):
+    if p:
+        print(os.path.basename(os.path.realpath(p)))
+";
+    let out = Command::new("python3")
+        .arg("-c")
+        .arg(script)
+        .output()
+        .expect("run python3 to resolve runtime objects");
+    assert!(out.status.success(), "python3 obj resolution failed");
+    String::from_utf8(out.stdout)
+        .expect("utf8")
+        .lines()
+        .map(str::to_owned)
+        .collect()
+}
+
+/// Compile the Callgrind client-request shim the Python fixture loads via
+/// `ctypes`, as a shared library against the in-repo `callgrind.h`.
+fn compile_clgctl() -> PathBuf {
+    let repo = repo_root();
+    let src = Path::new(env!("CARGO_MANIFEST_DIR")).join("testdata/clgctl.c");
+    let lib = Path::new(env!("CARGO_TARGET_TMPDIR")).join("libclgctl.so");
+
+    let status = Command::new("cc")
+        .args(["-g", "-O0", "-shared", "-fPIC"])
+        .arg("-I")
+        .arg(repo.join("callgrind"))
+        .arg("-I")
+        .arg(repo.join("include"))
+        .arg("-o")
+        .arg(&lib)
+        .arg(&src)
+        .status()
+        .unwrap_or_else(|e| panic!("failed to spawn cc for clgctl: {e}"));
+    assert!(
+        status.success(),
+        "cc failed for {} ({status})",
+        src.display()
+    );
+    lib
+}
+
+/// Profile `testdata/recursion.py` with the in-repo Callgrind and return the
+/// `.out` contents. `--instr-atstart=no` pairs with the shim's client requests
+/// so only the measured region is profiled; the fixture adds the obj-skips
+/// itself, so no `--obj-skip` is passed on the command line.
+fn run_python(clgctl: &Path) -> String {
+    let script = Path::new(env!("CARGO_MANIFEST_DIR")).join("testdata/recursion.py");
+    let out_file = Path::new(env!("CARGO_TARGET_TMPDIR")).join("python.callgrind.out");
+
+    let status = Command::new(vg_in_place())
+        .arg("--tool=callgrind")
+        .arg("--instr-atstart=no")
+        .arg(format!("--callgrind-out-file={}", out_file.display()))
+        .arg("python3")
+        .arg(&script)
+        .arg(clgctl)
+        .status()
+        .unwrap_or_else(|e| panic!("failed to spawn vg-in-place: {e}"));
+    assert!(status.success(), "vg-in-place exited with {status}");
+    std::fs::read_to_string(&out_file).unwrap_or_else(|e| panic!("read {}: {e}", out_file.display()))
+}
+
+#[test]
+fn python_runtime_is_obj_skipped() {
+    if !have_python3() {
+        eprintln!("skipping python_runtime_is_obj_skipped: python3 not on PATH");
+        return;
+    }
+
+    let skipped = skipped_runtime_objects();
+    assert!(
+        !skipped.is_empty(),
+        "expected at least the python executable to be skipped"
+    );
+
+    let clgctl = compile_clgctl();
+    let raw = run_python(&clgctl);
+    let graph = CallGraph::parse(Cursor::new(raw.as_str()), &ParseOptions::default())
+        .expect("parse python callgrind output");
+
+    assert!(!graph.nodes().is_empty(), "expected a non-empty node set");
+    assert!(!graph.edges().is_empty(), "expected a non-empty edge set");
+
+    // The shim that fired START is captured, so instrumentation began exactly
+    // where the fixture asked, and it is wired into the graph (not dropped as
+    // an orphan root): the seeder reconstructed the native stack at the OFF->ON
+    // transition.
+    assert!(
+        graph.nodes().iter().any(|n| n.function == "clg_start"),
+        "clg_start (instrumentation shim) missing from graph"
+    );
+    assert!(
+        graph
+            .edges()
+            .iter()
+            .any(|e| e.caller.function == "clg_start" || e.callee.function == "clg_start"),
+        "clg_start has no edges - START frame was not captured"
+    );
+
+    // The runtime obj-skip folded the Python runtime out: no node belongs to
+    // libpython or the python executable, and the interpreter loop is gone.
+    for obj in &skipped {
+        assert!(
+            graph.nodes().iter().all(|n| &n.object != obj),
+            "obj-skip failed: {obj} still present as a node object"
+        );
+    }
+    assert!(
+        !graph
+            .nodes()
+            .iter()
+            .any(|n| n.function.starts_with("_PyEval_EvalFrameDefault")),
+        "interpreter loop _PyEval_EvalFrameDefault should have been obj-skipped"
+    );
+}