pulp::audio::AudioProcessLoadMeasurer Class Reference

Measures the CPU load of an audio processing callback. More...

#include <load_measurer.hpp>

Public Member Functions
	AudioProcessLoadMeasurer () noexcept
	Reads the platform timebase once, here, so begin() and end() never query it.
	AudioProcessLoadMeasurer (LoadClockRatio ratio) noexcept
	Uses ratio to convert clock ticks to nanoseconds.
LoadClockRatio	clock_ratio () const noexcept
	The tick-to-nanosecond ratio captured at construction.
void	begin (int num_frames, float sample_rate) noexcept
	Call at the start of the audio callback.
void	end () noexcept
	Call at the end of the audio callback.
float	load () const noexcept
	Current smoothed CPU load (0.0 = idle, 1.0 = full buffer, >1.0 = overrun).
float	peak_load () const noexcept
	Peak load since last reset.
float	last_load () const noexcept
	Last raw load sample.
std::int64_t	last_elapsed_ns () const noexcept
	Most recent measured callback duration, in nanoseconds (0 before the first valid window).
std::uint64_t	callback_count () const noexcept
	Number of valid callback windows measured since the last reset.
std::uint64_t	overload_count () const noexcept
	Number of valid callback windows whose raw load reached the overload threshold.
AudioProcessLoadSnapshot	snapshot () const noexcept
	Latest telemetry snapshot. Safe to poll from UI/diagnostic threads.
void	reset_peak () noexcept
	Reset peak load tracker.
void	reset () noexcept
	Reset all state.
void	set_smoothing (float alpha) noexcept
	Set smoothing factor (0 = no smoothing, 1 = no averaging).
void	set_overload_threshold (float load) noexcept
	Set the raw-load threshold that increments overload_count().

Static Public Member Functions
static std::uint64_t	read_ticks () noexcept
	One raw read of the measurer's monotonic clock, in its own ticks (convert spans with clock_ratio()).

Detailed Description

Measures the CPU load of an audio processing callback.

Call begin() at the start and end() at the end of your process() method. The load is the fraction of available time consumed by processing.

The audio-thread hot path performs fixed arithmetic and relaxed atomic stores only. It does not allocate, lock, or block. Polling threads may read load(), peak_load(), or snapshot() concurrently; multi-field snapshots are latest-value telemetry and may mix adjacent callbacks.

void MyPlugin::process(BufferView& buffer) {
    load_measurer_.begin(buffer.num_frames(), sample_rate_);
    // ... DSP work ...
    load_measurer_.end();
    float cpu = load_measurer_.load(); // 0.0 to 1.0+
}

Constructor & Destructor Documentation

AudioProcessLoadMeasurer() [1/2]

pulp::audio::AudioProcessLoadMeasurer::AudioProcessLoadMeasurer ( )

inlinenoexcept

Reads the platform timebase once, here, so begin() and end() never query it.

Construct the measurer off the audio thread.

AudioProcessLoadMeasurer() [2/2]

pulp::audio::AudioProcessLoadMeasurer::AudioProcessLoadMeasurer ( LoadClockRatio ratio )

inlineexplicitnoexcept

Uses ratio to convert clock ticks to nanoseconds.

A test can inject a known ratio; production code uses the default constructor.

Member Function Documentation

begin()

void pulp::audio::AudioProcessLoadMeasurer::begin ( int num_frames, float sample_rate )

inlinenoexcept

Call at the start of the audio callback.

Parameters

num_frames	Number of samples in this buffer.
sample_rate	Current sample rate in Hz.

callback_count()

std::uint64_t pulp::audio::AudioProcessLoadMeasurer::callback_count ( ) const

inlinenoexcept

Number of valid callback windows measured since the last reset.

clock_ratio()

LoadClockRatio pulp::audio::AudioProcessLoadMeasurer::clock_ratio ( ) const

inlinenoexcept

The tick-to-nanosecond ratio captured at construction.

end()

void pulp::audio::AudioProcessLoadMeasurer::end ( )

inlinenoexcept

Call at the end of the audio callback.

last_elapsed_ns()

std::int64_t pulp::audio::AudioProcessLoadMeasurer::last_elapsed_ns ( ) const

inlinenoexcept

Most recent measured callback duration, in nanoseconds (0 before the first valid window).

Cheap relaxed read; safe to poll while the audio thread runs.

last_load()

float pulp::audio::AudioProcessLoadMeasurer::last_load ( ) const

inlinenoexcept

Last raw load sample.

load()

float pulp::audio::AudioProcessLoadMeasurer::load ( ) const

inlinenoexcept

Current smoothed CPU load (0.0 = idle, 1.0 = full buffer, >1.0 = overrun).

overload_count()

std::uint64_t pulp::audio::AudioProcessLoadMeasurer::overload_count ( ) const

inlinenoexcept

Number of valid callback windows whose raw load reached the overload threshold.

peak_load()

float pulp::audio::AudioProcessLoadMeasurer::peak_load ( ) const

inlinenoexcept

Peak load since last reset.

read_ticks()

std::uint64_t pulp::audio::AudioProcessLoadMeasurer::read_ticks ( )

inlinestaticnoexcept

One raw read of the measurer's monotonic clock, in its own ticks (convert spans with clock_ratio()).

Apple targets read mach_absolute_time(); others read steady_clock in nanoseconds.

reset()

void pulp::audio::AudioProcessLoadMeasurer::reset ( )

inlinenoexcept

Reset all state.

reset_peak()

void pulp::audio::AudioProcessLoadMeasurer::reset_peak ( )

inlinenoexcept

Reset peak load tracker.

set_overload_threshold()

void pulp::audio::AudioProcessLoadMeasurer::set_overload_threshold ( float load )

inlinenoexcept

Set the raw-load threshold that increments overload_count().

Default is 1.0, meaning the callback consumed the full buffer budget.

set_smoothing()

void pulp::audio::AudioProcessLoadMeasurer::set_smoothing ( float alpha )

inlinenoexcept

Set smoothing factor (0 = no smoothing, 1 = no averaging).

Default is 0.1 (responsive but stable).

snapshot()

AudioProcessLoadSnapshot pulp::audio::AudioProcessLoadMeasurer::snapshot ( ) const

inlinenoexcept

Latest telemetry snapshot. Safe to poll from UI/diagnostic threads.

---

The documentation for this class was generated from the following file:

• /home/runner/work/pulp/pulp/core/audio/include/pulp/audio/load_measurer.hpp