ripwire-perf-target

Performance targeting with ripwire

Nearest neighbours: • Repo-wide quality/health sweep (not perf-specific) → ripwire-fresh-eyes (also uses --hotspots). • Finding a specific BUG, not a slow path → ripwire-find-bug.

Trigger: a representative benchmark, flame graph, trace, or profiler has identified a slow operation, file, stack, or symbol and you need to understand where a safe optimization belongs. If you have no measurement yet, create the smallest representative benchmark/profile first; ripwire cannot infer runtime cost from source shape.

<dir> = repo root.

1. Pin the measured evidence — record the workload, baseline, profiler/trace result, and the symbol or subsystem it implicates. Keep the same workload for the after measurement.

2. Navigate the measured surface — ripwire <dir> --for="measured operation or symbol" --detail=3, then --callers=SYM, --callees=SYM, or --around=SYM as needed. This turns runtime evidence into a bounded source-reading set without pretending the graph measured execution.

3. Maintenance/change-risk context — ripwire <dir> --hotspots --legend=compact Output: <hotspots> ranked by score = churn × ccx (churn = git commit frequency over 12mo; ccx = cognitive complexity). The top= attribute names the highest-complexity function in each file. High-score files are frequently changed and structurally complex: useful evidence about optimization risk and validation scope, but structural evidence, not runtime heat. A slowdown/regression traced to a specific change, not an all-time read — use the recent-churn lens: ripwire <dir> --hotspots --legend=compact --since="2 weeks ago" (or --since=HEAD~20 for a deterministic rev) ranks by commits after that point instead of all-history, which is the right lens for "this got slower after X" rather than a static hot-function scan.

4. Static dependency + shape hypotheses — ripwire <dir> --metrics --legend=compact --top-k=50 Output: the ranked map with in= (fan-in), cx=/ccx= (complexity), cbo= (coupling between objects — how many other types this symbol touches), loc= (body size), and nest= (max nesting depth) on each symbol. in= is static dependency fan-in, not execution frequency. Use cbo/nest/loc to form code-reading hypotheses inside the already-measured surface: coupling may constrain a rewrite, nesting may hide branchy or quadratic work, and large bodies may combine unrelated work. Read nest= with its profile, never alone — it is a max, so humps= (regions reaching the nesting bar) and deep= (lines inside them, a floor) on the same row are what separate a body that sustains depth from a long flat one whose max is a single inner loop; deep/loc is the discriminator (→ ripwire-quality-bar). Confirm every suspected bottleneck with the benchmark/profile. On C-family/C# code, discount a ppalt=-carrying body: cx=/ccx=/nest=/loc=/locals= sum ALL #else/#ifdef branches, not just the one your build compiles, so a hot function that also happens to be preprocessor-heavy can look structurally worse than the code path actually executing.

4a2. Join the measured heat onto the static findings — ripwire <dir> --lint --legend=compact --with-profile=REPORT

REPORT is a RIPWIRE_PROFILE build's own stderr report (its #PROF_TSV block, verbatim). Every --lint finding whose enclosing symbol contains a PROFILE_SCOPE site gains heat_* attributes — the scope's measured calls, total_ms, and whichever counter columns that run armed (heat_l1d_mpki etc.; an ABSENT column was not measured, never zero). This is the one-command answer to "which of these cache-* rows are actually HOT": static shape × PMU weight (SYZYGY's advice mode, Hundt CGO 2006). heat_joined="0" on the root is honest — no finding sits inside a profiled scope — never an error.

4b. If the profile points at MEMORY, not compute — cheapest first, ripwire <dir> --lint --legend=compact runs the built-in cache-* pack (8 static data-layout checks, e.g. cache-gather-subscript, cache-vector-of-indirect, cache-pointer-chase-loop) as part of an ordinary lint pass — no profile required, so it is worth a look before reaching for the heavier lens below. When a specific struct is already implicated, --field-affinity[=STRUCT]

When to reach for it. The measurement already implicates a struct-heavy path and the shape of the evidence says data layout, not algorithm: cache-miss or memory-stall counters dominating the profile, a loop whose cost does not track its instruction count, a hot/cold field mix (a couple of fields read on every pass, a dozen touched only on cold paths), or a wide struct threaded through many callers. Bare = every aggregate in the repo ranked by separation cost; =STRUCT narrows to the one the profile named — prefer the narrow form, per this skill's stop rule.

Output: per struct, which fields the indexed C/C++/ObjC functions access TOGETHER, diffed against the declared field order and 64-byte cache-line geometry (Chilimbi's separation weight, PLDI 1999 — cited, not invented here). Exactly two findings fire, both with a direction defensible in one sentence: split-line (a co-accessed pair at wt="0.00", i.e. ≥64 bytes apart — no field order can put them on one line) and straddle (one co-accessed field crossing a line boundary, so every access to that ONE field touches two lines).

What it does NOT detect — the boundary matters more than the findings, because a layout change made on the wrong evidence is expensive and hard to unwind:

• Runtime frequency. fns= counts distinct indexed functions (counts_floor="1") and w= is a static call-graph reachability proxy (weighting="fanin-floor") — a struct can top the ranking and cost nothing because it is constructed once.
• False sharing. That is the inverse question (which fields to SEPARATE), and this lens has no opinion on it. It is also why no packing advice is emitted: tight packing co-locates independently written fields and can induce false sharing, so the axis is not monotonic.
• Reordering, packing, padding. No rewrite mode, no "sort by size", no hole report. Advice only.
• AoS vs SoA. Not modeled at all — there is no verdict here on changing a container's shape.
• Which instance, or what a pointer points at. No points-to analysis: an access is approximated by <function, struct type>. Only dot/arrow syntax counts, so a bare field name inside its own method is invisible, and a field name declared by two aggregates is REFUSED into amb_skipped= rather than guessed.
• True sizeof/alignment under templates, virtuals, bases and your target ABI. All geometry is an LP64 model (model="lp64-approx"); a definition the layout model refuses (modeled="0") contributes its co-access graph and no geometry finding.
• Pointer-chasing stalls — with one narrow exception, in the other direction: the same verb also classifies each C-style for loop's advance as index/chase/mixed/unknown and can flag a declared field as the traversal's chase pointer (chase="1" loops="N"). It is purely syntactic, C-family only, and range-for/while/recursion always read unknown (as_unknown=), so a zero there means "not classified", never "no chases." It ships report-only — it does not move the ranking.

This is a HYPOTHESIS GENERATOR, not a measurement — same rule as every static signal on this page. For runtime truth, go back to the counters: <validate> names the instrumented PROFILE_SCOPE whose hardware counters would confirm or refute the hypothesis (the PMC backend is src/infra/profilePmc.h — kpep on macOS, perf_event_open on Linux), bench/bench_field_ab.cpp is the A/B harness, and docs/FIELDAFFINITY.md records a worked example in which the static hypothesis was refuted under one access pattern. Confirm on hardware before changing a layout, exactly as with every other item on this list. Exit is always 0: a report, not a gate.

5. Expand measured candidates — ripwire <dir> --expand=SYM --legend=compact for the implicated symbols. Output: full body + callee signatures. Look for inner-loop allocations, redundant work, or O(N²) patterns that profiler data would confirm.

6. Re-measure — make one bounded change, rerun the same workload, and report latency/throughput plus any correctness/determinism gate. A structurally attractive refactor with no measured improvement is not a performance win.

Output

Measured baseline and workload; the profiler/trace evidence; the bounded symbol/caller/callee surface; structural hypotheses clearly labeled as non-runtime evidence; the change; and the same after measurement.