aowlspt_admprof.h

Source: abi/aowlspt_admprof.h — 223 lines, 0 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.

 THE ADMIN PHASE PROFILER -- what mod[8] spends its 6.6ms/frame on.

WHY THIS EXISTS. The host's drain profiler (abi/aowlspt_drainprof.h) measured,
live, in a phase-confirmed raid, with an honest meter (control 0.3us/call,
35ns/pair overhead = 0.0% of frame):

    INSIDE mainDrain: mod[8]=6579.2us/frame over 7096 callbacks,
                      max 43575.5us.  mainDrain total 7396.9us/frame.

mod[8] is mods/admin, and 6579.2 of 7396.9 is ~89% of ALL mod time in the
drain. There is exactly one admin callback in the drain -- `onCamTick`,
registered with `everyMain` -- so the whole of that number is inside one
function, and the only useful next measurement is INSIDE it.

This deliberately COPIES `mods/maps/sp/mapsprof.h`'s rules rather than
inventing new ones, because each of those rules was learned by getting the
measurement wrong first:

  * ONE clock: QueryPerformanceCounter, converted to nanoseconds once.
  * EVERY printed number is MICROSECONDS with `us` attached, or NANOSECONDS
    with `ns` attached. There is no unitless duration in the output. (A
    microsecond figure was read as nanoseconds once and sent a whole agent
    after a phantom.)
  * A POSITIVE CONTROL through the same bracket, in the same tick. Without
    it "the meter is lying" cannot be ruled out, and it has had to be ruled
    out three times.
  * DISJOINT and EXHAUSTIVE phases at each level, each level with its OWN
    parent bracket to subtract against, so the report says "N% is OUTSIDE
    every bracket and is UNEXPLAINED" rather than implying the phases sum to
    the total.
  * A level that sums to >= 100% of its parent is printed as BROKEN, not as
    a result. (One shipped reading 104.3% because its parent bracketed only
    one of two call sites.)
  * "0 calls, NEVER RAN" is a DIFFERENT report from "cheap".
  * A saturation sentinel is never printed as a value.
  * Below AP_MIN_TICKS the verdict is INCONCLUSIVE -- "I could not look yet"
    is not a pass (CLAUDE.md 9b).

IT IS NOT A GUARD AND OPENS NONE. Every bracket is a pair of QPC reads around
a call site that already exists. It installs no detour, resolves no name,
calls nothing in the game and dereferences nothing of the game's, and every
bracket sits strictly OUTSIDE any `aowl_p_p_seh` -- that guard is not
re-entrant (CLAUDE.md 5). It holds fixed static storage and allocates
nothing, managed or otherwise (rule 7).

FOUR LEVELS, each with its own parent:
  L0  AP_WHOLE                 the entire onCamTick body
  L1  AP_HOTKEY..AP_POS        phases of the tick        (parent AP_WHOLE)
  L2  AP_P_ARM..AP_P_MOVE      phases of posSample()     (parent AP_POS)
  L3  AP_E_FETCH..AP_E_ADD     phases of one list slot   (parent AP_P_LOOP)
  L4  AP_L_H1..AP_L_TAIL       hops inside pos_live      (parent AP_L_WHOLE)

WHY L4's PARENT IS AP_L_WHOLE AND NOT AP_E_ADD. `posSample` calls
`aowl_admin_pos_add` TWICE per sweep's worth of work: once for the LOCAL
player (bracketed AP_P_ME, at L2) and once per list entity (bracketed
AP_E_ADD, at L3). Both reach `aowl_admin_pos_live` and both fire the L4
brackets, so children of AP_E_ADD would count strictly MORE calls than their
parent and sum above it -- the exact 104.3% shape. AP_L_WHOLE brackets the
whole `pos_live` body on every return path including the early ones, so by
construction it encloses every child and has at least each child's call
count. The reporter asserts that containment OUT LOUD, so a future call site
that opens a child outside the whole announces itself by name instead of
quietly re-creating the bug.

ONE definition, ONE translation unit. The counters are process-global state,
so `static` here would give every including TU its own private copy and the
report would describe whichever TU printed it -- a plausible number from a
meter that measured a fraction of itself. `mods/admin/adm/admprof.nim` is the
ONLY TU that defines AOWL_ADMPROF_IMPL; every other includer gets prototypes.

Constants

• AOWLSPT_ADMPROF_H

Functions

None at file scope. This header is types, constants or inline macros only.