Helios Engine
A modular ECS based data-oriented C++23 game engine framework
Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | List of all members
helios::profile::Profiler Class Reference

Global profiler registry and multi-backend fan-out dispatcher. More...

#include <profiler.hpp>

Public Member Functions

void Clear () noexcept
 Clears all registered backends and resets finalization state.
void Finalize () noexcept
 Partitions zone storage and marks the profiler ready for use.
void Startup () noexcept
 Calls Startup() on all registered backends.
void Shutdown () noexcept
 Calls Shutdown() on all registered backends.
template<ProfilerBackendTrait T, typename... Args>
T & AddBackend (Args &&... args) noexcept
 Registers and owns a backend of type T.
template<ProfilerBackendTrait T>
void RemoveBackend () noexcept
 Removes a backend by type.
void RemoveBackend (BackendTypeIndex index) noexcept
 Removes a backend by type index.
template<ProfilerBackendTrait T>
T & Get () noexcept
 Gets a backend by type.
template<ProfilerBackendTrait T>
const T & Get () const noexcept
 Gets a backend by type (const).
Backend & Get (BackendTypeIndex index) noexcept
 Gets a backend by type index.
const Backend & Get (BackendTypeIndex index) const noexcept
 Gets a backend by type index (const).
template<ProfilerBackendTrait T>
T * TryGet () noexcept
 Tries to get a backend by type.
template<ProfilerBackendTrait T>
const T * TryGet () const noexcept
 Tries to get a backend by type (const).
Backend * TryGet (BackendTypeIndex index) noexcept
 Tries to get a backend by type index.
const Backend * TryGet (BackendTypeIndex index) const noexcept
 Tries to get a backend by type index (const).
template<ProfilerBackendTrait T>
bool Contains () const noexcept
 Checks whether a backend type is registered.
bool Contains (BackendTypeIndex index) const noexcept
 Checks whether a backend type index is registered.
bool Finalized () const noexcept
 Returns whether the profiler has been finalized.
template<ProfilerBackendTrait T>
size_t StorageOffset () const noexcept
 Returns the zone storage byte offset for backend type T.
size_t BackendCount () const noexcept
 Returns the number of registered backends.
void BeginZone (const ZoneSpec &spec, std::span< std::byte > storage) noexcept
 Dispatches a zone begin event to all registered backends.
void EndZone (std::span< std::byte > storage) noexcept
 Dispatches a zone end event to all registered backends.
void ZoneText (std::span< std::byte > storage, std::string_view text) noexcept
 Dispatches a zone text event to all registered backends.
void ZoneValue (std::span< std::byte > storage, uint64_t value) noexcept
 Dispatches a zone value event to all registered backends.
void ZoneName (std::span< std::byte > storage, std::string_view name) noexcept
 Dispatches a zone name event to all registered backends.
void FrameMark () noexcept
 Dispatches a frame mark event to all registered backends.
void FrameMark (CStringView name) noexcept
 Dispatches a frame mark event with a name to all registered backends.
void FrameMarkStart (CStringView name) noexcept
 Dispatches a frame mark start event to all registered backends.
void FrameMarkEnd (CStringView name) noexcept
 Dispatches a frame mark end event to all registered backends.
void Message (std::string_view text, uint32_t color) noexcept
 Dispatches a message event to all registered backends.
void SetThreadName (CStringView name) noexcept
 Dispatches a thread name event to all registered backends.
void Plot (CStringView name, double value) noexcept
 Dispatches a plot event to all registered backends.
void PlotConfig (CStringView name, PlotFormat type, bool step, bool fill, uint32_t color) noexcept
 Dispatches a plot configuration event to all registered backends.
void Alloc (const void *ptr, size_t size, std::optional< CStringView > name, int depth, std::source_location loc) noexcept
 Dispatches an allocation event to all registered backends.
void Free (const void *ptr, std::optional< CStringView > name, int depth, std::source_location loc) noexcept
 Dispatches a deallocation event to all registered backends.
void MemoryDiscard (CStringView name) noexcept
 Dispatches a memory discard event to all registered backends.
void MemoryDiscard (CStringView name, int depth) noexcept
 Dispatches a memory discard event to all registered backends.

Static Public Member Functions

static Profiler & Instance () noexcept
 Returns the singleton profiler instance.

Detailed Description

Global profiler registry and multi-backend fan-out dispatcher.

Backends are registered before Finalize() and keyed by concrete type via MultiTypeMap.

Definition at line 27 of file profiler.hpp.

Member Function Documentation

◆ AddBackend()

template<ProfilerBackendTrait T, typename... Args>
T & helios::profile::Profiler::AddBackend ( Args &&... args)
inlinenoexcept

Registers and owns a backend of type T.

Warning
Not thread-safe. Call only during single-threaded startup.
Template Parameters
TConcrete backend type
ArgsConstructor argument types
Parameters
argsArguments forwarded to T's constructor
Returns
Reference to the registered backend

Definition at line 423 of file profiler.hpp.

◆ Alloc()

void helios::profile::Profiler::Alloc ( const void * ptr,
size_t size,
std::optional< CStringView > name,
int depth,
std::source_location loc )
noexcept

Dispatches an allocation event to all registered backends.

Thread-safe after Finalize() when backends honor the dispatch contract.

Parameters
ptrPointer to the allocated memory
sizeSize of the allocated memory in bytes
nameOptional name of the allocation
depthCall stack depth of the allocation event
locSource location of the allocation event

Definition at line 262 of file profiler.cpp.

◆ BackendCount()

size_t helios::profile::Profiler::BackendCount ( ) const
inlinenodiscardnoexcept

Returns the number of registered backends.

Warning
Not thread-safe.
Returns
Backend count

Definition at line 216 of file profiler.hpp.

◆ BeginZone()

void helios::profile::Profiler::BeginZone ( const ZoneSpec & spec,
std::span< std::byte > storage )
noexcept

Dispatches a zone begin event to all registered backends.

Thread-safe after Finalize() when backends honor the dispatch contract.

Parameters
specZone specification
storageContiguous storage for backend-specific zone data

Definition at line 122 of file profiler.cpp.

◆ Clear()

void helios::profile::Profiler::Clear ( )
inlinenoexcept

Clears all registered backends and resets finalization state.

Warning
Not thread-safe. Call only when no zones are active.

Definition at line 408 of file profiler.hpp.

◆ Contains() [1/2]

template<ProfilerBackendTrait T>
bool helios::profile::Profiler::Contains ( ) const
inlinenodiscardnoexcept

Checks whether a backend type is registered.

Warning
Not thread-safe.
Template Parameters
TConcrete backend type
Returns
True if registered

Definition at line 178 of file profiler.hpp.

◆ Contains() [2/2]

bool helios::profile::Profiler::Contains ( BackendTypeIndex index) const
inlinenodiscardnoexcept

Checks whether a backend type index is registered.

Warning
Not thread-safe.
Parameters
indexBackend type index
Returns
True if registered

Definition at line 188 of file profiler.hpp.

◆ EndZone()

void helios::profile::Profiler::EndZone ( std::span< std::byte > storage)
noexcept

Dispatches a zone end event to all registered backends.

Thread-safe after Finalize() when backends honor the dispatch contract.

Parameters
storageContiguous storage for backend-specific zone data

Definition at line 134 of file profiler.cpp.

◆ Finalize()

void helios::profile::Profiler::Finalize ( )
noexcept

Partitions zone storage and marks the profiler ready for use.

Backends must be explicitly registered via AddBackend() before calling Finalize(). No backend is added automatically.

Warning
Not thread-safe. Call before worker threads start.

Definition at line 96 of file profiler.cpp.

◆ Finalized()

bool helios::profile::Profiler::Finalized ( ) const
inlinenodiscardnoexcept

Returns whether the profiler has been finalized.

Warning
Not thread-safe.
Returns
True after Finalize()

Definition at line 197 of file profiler.hpp.

◆ FrameMark() [1/2]

void helios::profile::Profiler::FrameMark ( )
noexcept

Dispatches a frame mark event to all registered backends.

Thread-safe after Finalize() when backends honor the dispatch contract.

Definition at line 181 of file profiler.cpp.

◆ FrameMark() [2/2]

void helios::profile::Profiler::FrameMark ( CStringView name)
noexcept

Dispatches a frame mark event with a name to all registered backends.

Thread-safe after Finalize() when backends honor the dispatch contract.

Parameters
nameName of the frame mark

Definition at line 191 of file profiler.cpp.

◆ FrameMarkEnd()

void helios::profile::Profiler::FrameMarkEnd ( CStringView name)
noexcept

Dispatches a frame mark end event to all registered backends.

Thread-safe after Finalize() when backends honor the dispatch contract.

Parameters
nameName of the frame mark

Definition at line 211 of file profiler.cpp.

◆ FrameMarkStart()

void helios::profile::Profiler::FrameMarkStart ( CStringView name)
noexcept

Dispatches a frame mark start event to all registered backends.

Thread-safe after Finalize() when backends honor the dispatch contract.

Parameters
nameName of the frame mark

Definition at line 201 of file profiler.cpp.

◆ Free()

void helios::profile::Profiler::Free ( const void * ptr,
std::optional< CStringView > name,
int depth,
std::source_location loc )
noexcept

Dispatches a deallocation event to all registered backends.

Thread-safe after Finalize() when backends honor the dispatch contract.

Parameters
ptrPointer to the deallocated memory
nameOptional name of the deallocation
depthCall stack depth of the deallocation event
locSource location of the deallocation event

Definition at line 275 of file profiler.cpp.

◆ Get() [1/4]

template<ProfilerBackendTrait T>
const T & helios::profile::Profiler::Get ( ) const
inlinenodiscardnoexcept

Gets a backend by type (const).

Warning
Not thread-safe. Triggers assertion if the backend is not registered.
Template Parameters
TConcrete backend type
Returns
Const reference to the backend

Definition at line 115 of file profiler.hpp.

◆ Get() [2/4]

template<ProfilerBackendTrait T>
T & helios::profile::Profiler::Get ( )
inlinenodiscardnoexcept

Gets a backend by type.

Warning
Not thread-safe. Triggers assertion if the backend is not registered.
Template Parameters
TConcrete backend type
Returns
Reference to the backend

Definition at line 103 of file profiler.hpp.

◆ Get() [3/4]

const Backend & helios::profile::Profiler::Get ( BackendTypeIndex index) const
inlinenodiscardnoexcept

Gets a backend by type index (const).

Warning
Not thread-safe. Triggers assertion if the backend is not registered.
Parameters
indexBackend type index
Returns
Const reference to the backend

Definition at line 444 of file profiler.hpp.

◆ Get() [4/4]

Backend & helios::profile::Profiler::Get ( BackendTypeIndex index)
inlinenodiscardnoexcept

Gets a backend by type index.

Warning
Not thread-safe. Triggers assertion if the backend is not registered.
Parameters
indexBackend type index
Returns
Reference to the backend

Definition at line 438 of file profiler.hpp.

◆ Instance()

Profiler & helios::profile::Profiler::Instance ( )
inlinestaticnodiscardnoexcept

Returns the singleton profiler instance.

Returns
Reference to the profiler

Definition at line 403 of file profiler.hpp.

◆ MemoryDiscard() [1/2]

void helios::profile::Profiler::MemoryDiscard ( CStringView name)
noexcept

Dispatches a memory discard event to all registered backends.

Thread-safe after Finalize() when backends honor the dispatch contract.

Parameters
nameOptional name of the discard event

Definition at line 287 of file profiler.cpp.

◆ MemoryDiscard() [2/2]

void helios::profile::Profiler::MemoryDiscard ( CStringView name,
int depth )
noexcept

Dispatches a memory discard event to all registered backends.

Thread-safe after Finalize() when backends honor the dispatch contract.

Parameters
nameOptional name of the discard event
depthCall stack depth of the discard event

Definition at line 297 of file profiler.cpp.

◆ Message()

void helios::profile::Profiler::Message ( std::string_view text,
uint32_t color )
noexcept

Dispatches a message event to all registered backends.

Thread-safe after Finalize() when backends honor the dispatch contract.

Parameters
textText of the message
colorColor of the message

Definition at line 221 of file profiler.cpp.

◆ Plot()

void helios::profile::Profiler::Plot ( CStringView name,
double value )
noexcept

Dispatches a plot event to all registered backends.

Thread-safe after Finalize() when backends honor the dispatch contract.

Parameters
nameName of the plot
valueValue to plot

Definition at line 241 of file profiler.cpp.

◆ PlotConfig()

void helios::profile::Profiler::PlotConfig ( CStringView name,
PlotFormat type,
bool step,
bool fill,
uint32_t color )
noexcept

Dispatches a plot configuration event to all registered backends.

Thread-safe after Finalize() when backends honor the dispatch contract.

Parameters
nameName of the plot
typePlot format type
stepWhether to use step interpolation
fillWhether to fill the area under the plot line
colorColor of the plot

Definition at line 251 of file profiler.cpp.

◆ RemoveBackend() [1/2]

template<ProfilerBackendTrait T>
void helios::profile::Profiler::RemoveBackend ( )
inlinenoexcept

Removes a backend by type.

Warning
Not thread-safe. Triggers assertion if finalize has been called yet. Call only when no zones are active.
Template Parameters
TConcrete backend type

Definition at line 434 of file profiler.hpp.

◆ RemoveBackend() [2/2]

void helios::profile::Profiler::RemoveBackend ( BackendTypeIndex index)
inlinenoexcept

Removes a backend by type index.

Warning
Not thread-safe. Triggers assertion if finalize has been called yet. Call only when no zones are active.
Parameters
indexBackend type index

Definition at line 415 of file profiler.hpp.

◆ SetThreadName()

void helios::profile::Profiler::SetThreadName ( CStringView name)
noexcept

Dispatches a thread name event to all registered backends.

Thread-safe after Finalize() when backends honor the dispatch contract.

Parameters
nameName of the thread

Definition at line 231 of file profiler.cpp.

◆ Shutdown()

void helios::profile::Profiler::Shutdown ( )
noexcept

Calls Shutdown() on all registered backends.

Warning
Not thread-safe. Call only during single-threaded startup.

Definition at line 86 of file profiler.cpp.

◆ Startup()

void helios::profile::Profiler::Startup ( )
noexcept

Calls Startup() on all registered backends.

Warning
Not thread-safe. Call only during single-threaded startup.

Definition at line 76 of file profiler.cpp.

◆ StorageOffset()

template<ProfilerBackendTrait T>
size_t helios::profile::Profiler::StorageOffset ( ) const
inlinenodiscardnoexcept

Returns the zone storage byte offset for backend type T.

Warning
Not thread-safe. Triggers assertion if the backend is not registered or not finalized.
Template Parameters
TConcrete backend type
Returns
Storage offset in bytes

Definition at line 207 of file profiler.hpp.

◆ TryGet() [1/4]

template<ProfilerBackendTrait T>
const T * helios::profile::Profiler::TryGet ( ) const
inlinenodiscardnoexcept

Tries to get a backend by type (const).

Warning
Not thread-safe.
Template Parameters
TConcrete backend type
Returns
Const pointer to the backend, or nullptr if not registered

Definition at line 467 of file profiler.hpp.

◆ TryGet() [2/4]

template<ProfilerBackendTrait T>
T * helios::profile::Profiler::TryGet ( )
inlinenodiscardnoexcept

Tries to get a backend by type.

Warning
Not thread-safe.
Template Parameters
TConcrete backend type
Returns
Pointer to the backend, or nullptr if not registered

Definition at line 461 of file profiler.hpp.

◆ TryGet() [3/4]

const Backend * helios::profile::Profiler::TryGet ( BackendTypeIndex index) const
inlinenodiscardnoexcept

Tries to get a backend by type index (const).

Warning
Not thread-safe.
Parameters
indexBackend type index
Returns
Const pointer to the backend, or nullptr if not registered

Definition at line 455 of file profiler.hpp.

◆ TryGet() [4/4]

Backend * helios::profile::Profiler::TryGet ( BackendTypeIndex index)
inlinenodiscardnoexcept

Tries to get a backend by type index.

Warning
Not thread-safe.
Parameters
indexBackend type index
Returns
Pointer to the backend, or nullptr if not registered

Definition at line 450 of file profiler.hpp.

◆ ZoneName()

void helios::profile::Profiler::ZoneName ( std::span< std::byte > storage,
std::string_view name )
noexcept

Dispatches a zone name event to all registered backends.

Thread-safe after Finalize() when backends honor the dispatch contract.

Parameters
storageContiguous storage for backend-specific zone data
nameName to attach to the zone

Definition at line 169 of file profiler.cpp.

◆ ZoneText()

void helios::profile::Profiler::ZoneText ( std::span< std::byte > storage,
std::string_view text )
noexcept

Dispatches a zone text event to all registered backends.

Thread-safe after Finalize() when backends honor the dispatch contract.

Parameters
storageContiguous storage for backend-specific zone data
textText to attach to the zone

Definition at line 145 of file profiler.cpp.

◆ ZoneValue()

void helios::profile::Profiler::ZoneValue ( std::span< std::byte > storage,
uint64_t value )
noexcept

Dispatches a zone value event to all registered backends.

Thread-safe after Finalize() when backends honor the dispatch contract.

Parameters
storageContiguous storage for backend-specific zone data
valueNumeric value to attach to the zone

Definition at line 157 of file profiler.cpp.