cpu_profiler.h File Reference

Per-instance CPU utilisation profiler gated by a global environment variable. More...

#include <atomic>
#include <cstdint>
#include "./elapsed_timer.h"
#include "./macros.h"
#include "./spin_lock.h"

Include dependency graph for cpu_profiler.h:

Go to the source code of this file.

Classes
class	vlink::CpuProfiler
	Tracks CPU active time as a percentage of total elapsed wall-clock time. More...

Namespaces
namespace	vlink

Detailed Description

Per-instance CPU utilisation profiler gated by a global environment variable.

CpuProfiler measures the fraction of wall-clock time that the CPU was actively executing work between paired begin() / end() calls. It uses two ElapsedTimer instances internally:

• cpu_active_timer_ – measures only active time (CPU time spent in the section).
• cpu_timestamp_timer_ – measures total elapsed wall-clock time since begin().

The utilisation ratio is:

utilisation (%) = (sum of active intervals / total elapsed time) * 100

Global enable gate

Profiling is gated by the environment variable VLINK_PROFILER_ENABLE. Set it to "1" to enable; "0" (default) to disable. The value is read once at first call to is_global_enabled() and cached for the process lifetime.

export VLINK_PROFILER_ENABLE=1

Typical usage

vlink::CpuProfiler profiler;
 
for (auto& item : work_items) {
    profiler.begin();
    process(item);
    profiler.end();
}
 
double pct = profiler.get();  // CPU utilisation since first begin()
double reset_pct = profiler.restart();  // returns current value and resets

Note

• begin() and end() are guarded by an internal SpinLock and are safe to call from any thread, but each profiler instance measures a single logical stream of work.
• If profiling is globally disabled, begin() / end() still execute but should be short-circuited by the caller using is_global_enabled() for maximum performance.
• CpuProfilerGuard provides a convenient RAII wrapper that calls begin() and end() automatically.