.. _stdlib_jobque_profile:

================================
Self-describing jobque profiling
================================

.. das:module:: jobque_profile

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 :doc:`jobque` for the underlying event tracer.

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

.. code-block:: das

    require daslib/jobque_profile

Example:

.. code-block:: das

    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
        }
    }



+++++++++
Constants
+++++++++

.. _global-jobque_profile-PROFILE_COLOR_BLUE:

.. das:attribute:: PROFILE_COLOR_BLUE = 0x5e96de

PROFILE_COLOR_BLUE:uint const

.. _global-jobque_profile-PROFILE_COLOR_GREEN:

.. das:attribute:: PROFILE_COLOR_GREEN = 0x43b08a

PROFILE_COLOR_GREEN:uint const

.. _global-jobque_profile-PROFILE_COLOR_PURPLE:

.. das:attribute:: PROFILE_COLOR_PURPLE = 0xac82e4

PROFILE_COLOR_PURPLE:uint const

.. _global-jobque_profile-PROFILE_COLOR_AMBER:

.. das:attribute:: PROFILE_COLOR_AMBER = 0xc39536

PROFILE_COLOR_AMBER:uint const

.. _global-jobque_profile-PROFILE_COLOR_CORAL:

.. das:attribute:: PROFILE_COLOR_CORAL = 0xe08563

PROFILE_COLOR_CORAL:uint const

.. _global-jobque_profile-PROFILE_COLOR_TEAL:

.. das:attribute:: PROFILE_COLOR_TEAL = 0x4fc3d0

PROFILE_COLOR_TEAL:uint const

.. _global-jobque_profile-PROFILE_COLOR_MAGENTA:

.. das:attribute:: PROFILE_COLOR_MAGENTA = 0xd678b4

PROFILE_COLOR_MAGENTA:uint const

.. _global-jobque_profile-PROFILE_COLOR_INDIGO:

.. das:attribute:: PROFILE_COLOR_INDIGO = 0x8385e8

PROFILE_COLOR_INDIGO:uint const


++++++++++++++
Trace sessions
++++++++++++++

  *  :ref:`profile_save (path: string) : bool <function-jobque_profile_profile_save_string>`
  *  :ref:`profile_start (events_per_lane: int = 65536) <function-jobque_profile_profile_start_int>`
  *  :ref:`profile_stop () <function-jobque_profile_profile_stop>`

.. _function-jobque_profile_profile_save_string:

.. das:function:: 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

.. _function-jobque_profile_profile_start_int:

.. das:function:: 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

.. _function-jobque_profile_profile_stop:

.. das:function:: profile_stop()

Disarm tracing. Must be called before `profile_save`.



++++++++++
Categories
++++++++++

  *  :ref:`profile_category (id: int; name: string; color: uint = 0x0) <function-jobque_profile_profile_category_int_string_uint>`
  *  :ref:`profile_category (name: string; color: uint = 0x0) : int <function-jobque_profile_profile_category_string_uint>`
  *  :ref:`profile_tag (tag: int) <function-jobque_profile_profile_tag_int>`


profile_category
^^^^^^^^^^^^^^^^

.. _function-jobque_profile_profile_category_int_string_uint:

.. das:function:: 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

.. _function-jobque_profile_profile_category_string_uint:

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

----

.. _function-jobque_profile_profile_tag_int:

.. das:function:: profile_tag(tag: int)

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


:Arguments: * **tag** : int


+++++++
Markers
+++++++

  *  :ref:`profile_marker (id: int; arg: int = 0) <function-jobque_profile_profile_marker_int_int>`
  *  :ref:`profile_marker (name: string; arg: int = 0) <function-jobque_profile_profile_marker_string_int>`
  *  :ref:`profile_marker_id (name: string) : int <function-jobque_profile_profile_marker_id_string>`


profile_marker
^^^^^^^^^^^^^^

.. _function-jobque_profile_profile_marker_int_int:

.. das:function:: 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

.. _function-jobque_profile_profile_marker_string_int:

.. das:function:: profile_marker(name: string; arg: int = 0)

----

.. _function-jobque_profile_profile_marker_id_string:

.. das:function:: profile_marker_id(name: string) : int

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


:Arguments: * **name** : string