aowlspt_regview.h

Source: abi/aowlspt_regview.h — 174 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.

 aowlspt_regview.h -- A READ-ONLY VIEW OF THE SHARED REGION'S PARTICIPANT
TABLE, for the F3 profiler widget.

INCLUDED FROM `region.nim` ONLY, and only AFTER that file's own
`#define AOWL_REGION_HOST` / `#include "aowlspt_region.h"`. It is therefore
looking at `g_region` itself -- the same table the dispatcher writes on every
frame -- through the header's own `aowl_region_status`.

WHY THIS IS A SEPARATE FILE FROM `aowlspt_widget.h`
--------------------------------------------------
The whole host is ONE translation unit: `aowlhost.nim` `include`s
`debugui.nim`, `region.nim` and the rest, and they all become one C file, in
that order. `region.nim` is the single place that defines AOWL_REGION_HOST.
An earlier include of `aowlspt_region.h` from `debugui.nim`'s side -- in
CLIENT mode, since the define is not set there -- would set the include guard
first, and `region.nim`'s host-mode include would then expand to NOTHING:
the registry, the dispatcher and every `aowl_region_*` function would silently
disappear from the build. That is not hypothetical; it is what the first
attempt did, and it surfaced as nine `implicit declaration of aowl_region_*`
errors in code nobody had touched.

So the ordering is load-bearing and is enforced, not merely documented: this
file REFUSES TO COMPILE unless AOWL_REGION_HOST is already defined.

WHY THERE IS NO SECOND TIMER ANYWHERE
------------------------------------
Everything the profiler widget shows is ALREADY being computed. The region
dispatcher times each participant's callback, compares it against the budget
that participant declared at registration, counts overruns, counts faults,
and counts the frames it skipped it for. Reading that costs nothing and adds
nothing to the frame; instrumenting it a second time would both double the
cost and measure a different thing. And a second DETOUR to collect it would
overwrite the first's trampoline, which is the standing rule here.

WHAT CROSSES THE LINE is scalars and a `const char*` -- never the struct. The
widget side (`aowlspt_widget.h`) has matching `extern` declarations and no
knowledge of `AowlRegionStatus`'s layout at all.

Constants

• AOWLSPT_REGVIEW_H

Functions

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