Raxol.Performance.CycleProfiler (Raxol v2.6.0)

Profiles TEA update/view/render cycle timings.

Records per-cycle timing breakdowns in a CircularBuffer, computes rolling statistics, and detects slow cycles that exceed the budget threshold.

Usage

Raxol.start_link(MyApp, profiler: true)
Raxol.start_link(MyApp, profiler: [max_entries: 2000, slow_threshold_us: 33_333])

CycleProfiler.stats()        # => %{update: %{...}, render: %{...}}
CycleProfiler.slow_cycles()  # => [%RenderTiming{...}]
CycleProfiler.export(path)   # => :ok
CycleProfiler.reset()        # => :ok

Zero cost when disabled -- the Dispatcher and Engine check for nil pid before calling any recording functions.

Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

counts(pid \\ __MODULE__)

Returns the total and slow cycle counts.

export(pid \\ __MODULE__, path)

Exports profiling data to a file (Erlang term format).

record_render(pid \\ __MODULE__, timing)

Records a render cycle timing. Called by the Engine.

record_update(pid \\ __MODULE__, timing)

Records an update cycle timing. Called by the Dispatcher.

reset(pid \\ __MODULE__)

Resets all recorded data.

slow_cycles(pid \\ __MODULE__)

Returns render cycles that exceeded the slow threshold.

start_link(opts \\ [])

Starts the cycle profiler.

stats(pid \\ __MODULE__)

Returns computed statistics for update and render cycles.

subscribe(pid \\ __MODULE__)

Subscribes the calling process to slow-cycle notifications.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

counts(pid \\ MODULE)

@spec counts(pid() | atom()) :: %{total: non_neg_integer(), slow: non_neg_integer()}

Returns the total and slow cycle counts.

export(pid \\ MODULE, path)

@spec export(pid() | atom(), Path.t()) :: :ok | {:error, term()}

Exports profiling data to a file (Erlang term format).

record_render(pid \\ MODULE, timing)

@spec record_render(pid() | atom(), map()) :: :ok

Records a render cycle timing. Called by the Engine.

record_update(pid \\ MODULE, timing)

@spec record_update(pid() | atom(), map()) :: :ok

Records an update cycle timing. Called by the Dispatcher.

reset(pid \\ MODULE)

@spec reset(pid() | atom()) :: :ok

Resets all recorded data.

slow_cycles(pid \\ MODULE)

@spec slow_cycles(pid() | atom()) :: [map()]

Returns render cycles that exceeded the slow threshold.

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the cycle profiler.

stats(pid \\ MODULE)

@spec stats(pid() | atom()) :: map()

Returns computed statistics for update and render cycles.