9.3. Self-describing jobque profiling

The JOBQUE_PROFILE module wraps the low-level jobque_trace_* builtins into a self-describing profiling API: named categories with colors for the op tags stamped via profile_tag, and markers — instant “unit” events such as token or frame — so saved traces carry their own legend and are navigable unit-to-unit. Files remain perfetto-compatible; the category and marker tables ride in a jobqueProfile sibling key that Perfetto ignores.

See also Jobs and threads for the underlying event tracer.

All functions and symbols are in “jobque_profile” module, use require to get access to it.

require daslib/jobque_profile

Example:

require daslib/jobque_boost
require daslib/jobque_profile

[export]
def main() {
    with_job_que() {
        let heavy = profile_category("heavy op")     // auto id + palette color
        let tok = profile_marker_id("token")
        profile_start(65536)
        for (i in range(4)) {
            profile_marker(tok, i)                   // unit boundary
            profile_tag(heavy)
            // ... dispatch work ...
        }
        profile_stop()
        profile_save("trace.json")                   // open in Perfetto or the timeline viewer
    }
}

9.3.1. Constants

PROFILE_COLOR_BLUE = 0x5e96de

PROFILE_COLOR_BLUE:uint const

PROFILE_COLOR_GREEN = 0x43b08a

PROFILE_COLOR_GREEN:uint const

PROFILE_COLOR_PURPLE = 0xac82e4

PROFILE_COLOR_PURPLE:uint const

PROFILE_COLOR_AMBER = 0xc39536

PROFILE_COLOR_AMBER:uint const

PROFILE_COLOR_CORAL = 0xe08563

PROFILE_COLOR_CORAL:uint const

PROFILE_COLOR_TEAL = 0x4fc3d0

PROFILE_COLOR_TEAL:uint const

PROFILE_COLOR_MAGENTA = 0xd678b4

PROFILE_COLOR_MAGENTA:uint const

PROFILE_COLOR_INDIGO = 0x8385e8

PROFILE_COLOR_INDIGO:uint const

9.3.2. Trace sessions

profile_save (path: string) : bool

profile_start (events_per_lane: int = 65536)

profile_stop ()

profile_save(path: string ): bool 

Write the recorded trace as perfetto-compatible JSON, including the category and marker registries. Returns false when tracing is still on or nothing was recorded.

Arguments:

path : string

profile_start(events_per_lane: int = 65536 )

Arm the per-lane trace rings (events_per_lane events each; full lanes stop recording).

Arguments:

events_per_lane : int

profile_stop()

Disarm tracing. Must be called before profile_save.

9.3.3. Categories

profile_category (id: int; name: string; color: uint = 0x0)

profile_category (name: string; color: uint = 0x0) : int

profile_tag (tag: int)

9.3.3.1. profile_category

profile_category(id: int; name: string; color: uint = 0x0 )

Register a named category for an existing tag id (color is 0xRRGGBB; 0 picks from the default palette by name hash).

Arguments:

id : int
name : string
color : uint

profile_category(name: string; color: uint = 0x0 ): int

profile_tag(tag: int )

Stamp the current op tag; subsequent chain publishes carry it (viewer color channel).

Arguments:

tag : int

9.3.4. Markers

profile_marker (id: int; arg: int = 0)

profile_marker (name: string; arg: int = 0)

profile_marker_id (name: string) : int

9.3.4.1. profile_marker

profile_marker(id: int; arg: int = 0 )

Stamp an instant unit boundary on the caller lane (no-op when tracing is off).

Arguments:

id : int
arg : int

profile_marker(name: string; arg: int = 0 )

profile_marker_id(name: string ): int 

Register/look up a marker kind (e.g. “token”, “frame”); idempotent per name.

Arguments:

name : string