feat: add callgrind_toggle_collect helper

[not-matthias]

Expose CALLGRIND_TOGGLE_COLLECT as a wrapper next to the existing
start/stop instrumentation helpers. Unlike toggling instrumentation,
toggling collection does not flush the simulated cache, so integrations
can exclude code regions (e.g. google benchmark's PauseTiming sections)
from measurement without paying an artificial cold-cache warmup in the
measured region.

Refs COD-2033.

[greptile-apps]

Greptile Summary

This PR exposes CALLGRIND_TOGGLE_COLLECT as a public C function callgrind_toggle_collect(), complementing the existing callgrind_start_instrumentation / callgrind_stop_instrumentation wrappers. Unlike start/stop instrumentation, toggling collection leaves the simulated cache intact, making it suitable for excluding setup/teardown regions (e.g. Google Benchmark's PauseTiming sections) without incurring artificial cold-cache costs in the subsequent measured region.

• Adds the function declaration with a clear doc-comment in includes/core.h, a no-op stub for Windows/Apple, and the real CALLGRIND_TOGGLE_COLLECT expansion for Linux in both src/helpers/valgrind_wrapper.c and the distribution amalgam dist/core.c.
• The implementation follows the exact same pattern as the existing callgrind_start_instrumentation / callgrind_stop_instrumentation helpers and is fully consistent across all three changed files.

Confidence Score: 5/5

The change is a straightforward additive wrapper — three files each gain an identical, two-line function that either no-ops or forwards to a well-established Valgrind macro. No existing code paths are modified.

The three changed files are in perfect sync: the source wrapper, its distribution amalgam, and the public header all receive the same, mechanical addition. The underlying CALLGRIND_TOGGLE_COLLECT macro has been part of the Valgrind client-request API for many years, and the no-op stubs on Windows/Apple follow the exact same pattern used by every other wrapper in this file. There are no logic branches, no new state, and no modified call-sites.

No files require special attention.

Important Files Changed

Filename	Overview
includes/core.h	Adds callgrind_toggle_collect() declaration with a clear doc-comment; no Windows macro stub needed because the function is not used inline in the header.
src/helpers/valgrind_wrapper.c	Adds no-op stub in the Windows/Apple branch and CALLGRIND_TOGGLE_COLLECT expansion in the Linux branch, consistent with all existing wrappers.
dist/core.c	Distribution amalgam updated to mirror valgrind_wrapper.c; both branches are in sync with the source change.

Sequence Diagram

sequenceDiagram
    participant BenchCode as Benchmark Code
    participant IH as instrument-hooks
    participant CG as Callgrind / Valgrind

    BenchCode->>IH: callgrind_start_instrumentation()
    IH->>CG: CALLGRIND_START_INSTRUMENTATION (flushes simulated cache)

    Note over BenchCode: Measured iteration begins

    BenchCode->>IH: callgrind_toggle_collect()
    IH->>CG: CALLGRIND_TOGGLE_COLLECT (pauses cost collection, cache state preserved)

    Note over BenchCode: Excluded region (e.g. PauseTiming setup)

    BenchCode->>IH: callgrind_toggle_collect()
    IH->>CG: CALLGRIND_TOGGLE_COLLECT (resumes cost collection, no cold-cache penalty)

    Note over BenchCode: Measured iteration continues

    BenchCode->>IH: callgrind_stop_instrumentation()
    IH->>CG: CALLGRIND_STOP_INSTRUMENTATION

Loading

_{Reviews (2): Last reviewed commit: "feat: add callgrind_toggle_collect helpe..." | Re-trigger Greptile}