aowlspt_splprof.h

Source: abi/aowlspt_splprof.h — 187 lines, 21 file-scope functions.

What this header owns

Reproduced verbatim from the header's own banner comment — these notes are frequently the only written record of why the subsystem is shaped the way it is.

 aowlspt_splprof.h -- THE PHASE METER FOR `splRebrandDrain`, and nothing else.

WHY IT EXISTS. The drain profiler priced the whole rider at
`splRebrandDrain = 1152.2us/frame (2.9% of frame, 5765 calls, max 194373.3us)`.
A 194 MILLISECOND single call inside a rider whose own walk carries an 18ms
slice means the stall is in a phase the slice does not cover. One row cannot
say which. This adds the DISJOINT, EXHAUSTIVE decomposition of that one row.

WHAT IT HOOKS: NOTHING. It is a pair of QPC reads around statements that
already run. No detour, no name resolved, no game pointer dereferenced, no
guard opened -- so it cannot nest inside `aowl_p_p_seh`. The TOTAL bracket
sits in `splRebrandDrainTick`, strictly OUTSIDE `cSplTickGuarded`; every
phase bracket sits INSIDE the already-open guard and opens none of its own.

GATING. Active only while the drain profiler itself is on (`aowl_dp_enabled`).
It adds no flag, and with `drainProfiler` off every entry point here is a
single predicted compare and a return.

UNITS. Every number this file produces is NANOSECONDS internally and is
printed as MICROSECONDS with `us` attached by the Nim side. There is no
unitless duration anywhere in its output.

HONESTY RULES, all of them learned by getting this wrong:

 1. DISJOINT AND EXHAUSTIVE. The phases partition the guarded body. The
    reporter prints `accounted=X of Y us (Z%)` and then an explicit
    `UNEXPLAINED` line for the remainder. The remainder is never folded into
    a phase and never quietly dropped.
 2. A POSITIVE CONTROL, on the same clock, through the same bracket. Without
    it "the meter is lying" cannot be ruled out.
 3. NEVER PRINT A SENTINEL AS A VALUE. `-1` means "not measured" and the Nim
    side renders it `n/a`.
 4. "NEVER RAN" IS NOT "CHEAP". Every phase carries a call count, and a phase
    with zero calls is reported as `never ran`, never as `0.0us`.
 5. THE TAIL IS A SEPARATE QUESTION FROM THE MEAN. A 1.15ms mean with a 194ms
    max is mostly-idle-occasionally-catastrophic, so this counts calls over
    an explicit threshold AND records which phase dominated each of them.

Constants

• AOWLSPT_SPLPROF_H
• AOWL_SP_CHEAP
• AOWL_SP_CTRL
• AOWL_SP_CTRL_ITERS
• AOWL_SP_DESCEND
• AOWL_SP_DIAG
• AOWL_SP_MHEAD
• AOWL_SP_MTOG
• AOWL_SP_MWARN
• AOWL_SP_PRE
• AOWL_SP_ROOTS
• AOWL_SP_SCAN
• AOWL_SP_SLOTS
• AOWL_SP_SLOW_NS

Functions

Signature	Line
int64_t aowl_sp_now(void)	94
int64_t aowl_sp_delta_ns(int64_t t0)	103
void aowl_sp_add(int32_t slot, int64_t t0)	114
void aowl_sp_call_begin(void)	126
void aowl_sp_call_end(int64_t t0)	136
void aowl_sp_control(void)	160
int64_t aowl_sp_ns(int32_t i)	170
int64_t aowl_sp_calls(int32_t i)	171
int64_t aowl_sp_max(int32_t i)	172
int64_t aowl_sp_subtick(int32_t i)	173
int64_t aowl_sp_slow_by(int32_t i)	174
int64_t aowl_sp_total_ns(void)	175
int64_t aowl_sp_total_calls(void)	176
int64_t aowl_sp_total_max(void)	177
int64_t aowl_sp_slow_calls(void)	178
int64_t aowl_sp_slow_ns(void)	179
int64_t aowl_sp_slow_unexp(void)	180
int64_t aowl_sp_dropped(void)	181
int64_t aowl_sp_slow_ns_threshold(void)	182
int32_t aowl_sp_slots(void)	183
int32_t aowl_sp_ctrl_slot(void)	184