carb::profiler::IProfiler¶
Defined in carb/profiler/IProfiler.h
-
struct
carb::profiler
::
IProfiler
¶ Defines the profiler system that is associated with the Framework.
It is not recommended to use this interface directly, rather use macros provided in Profile.h, such as CARB_PROFILE_ZONE().
Event names are specified as string which can have formatting, which provides string behavior hints, but whether to use those hints is up to the profiler backend implementation.
Public Functions
-
template<typename
T
>
inline voidvalueStatic
(uint64_t mask, T value, StaticStringType valueFmt)¶ Helper functions to send a arbitrary type to the profiler.
- Template Parameters
T – The type of the parameter to send to the profiler.
- Parameters
mask – Value capture mask.
value – Value.
valueFmt – The value name format, followed by args. For valueStatic() this must be a StaticStringType from registerStaticString().
-
template<typename
T
, typename ...Args
>
inline voidvalueDynamic
(uint64_t mask, T value, const char *valueFmt, Args&&... args)¶ Helper functions to send a arbitrary type to the profiler.
- Template Parameters
T – The type of the parameter to send to the profiler.
- Parameters
mask – Value capture mask.
value – Value.
valueFmt – The value name format, followed by args. For valueStatic() this must be a StaticStringType from registerStaticString().
args – Additional arguments that correspond to printf-style format string
valueFmt
.
Public Members
-
void (*
startup
)()¶ Starts up the profiler for use.
-
void (*
shutdown
)()¶ Shuts down the profiler and cleans up resources.
-
uint64_t (*
setCaptureMask
)(const uint64_t mask)¶ Set capture mask.
Capture mask provides a way to filter out certain profiling events. Condition (eventMask & captureMask) == eventMask is evaluated, and if true, event is recorded. The default capture mask is kCaptureMaskAll
Note
Calling from multiple threads is not recommended as threads will overwrite each values. Calls to this function should be serialized.
Warning
Changing the capture mask after the profiler has been started causes undefined behavior.
- Parameters
mask – Capture mask.
- Returns
the previous Capture mask.
-
uint64_t (*
getCaptureMask
)()¶ Gets the current capture mask.
- Returns
The current capture mask
-
ZoneId (*
beginStatic
)(const uint64_t mask, StaticStringType function, StaticStringType file, int line, StaticStringType nameFmt)¶ Starts the profiling event.
This event could be a fiber-based event (i.e. could yield and resume on another thread) if tasking scheduler provides proper
startFiber
/stopFiber
calls.- Parameters
mask – Event capture mask.
function – Static string (see registerStaticString()) of the function where the profile zone is located (usually
__func__
). If supportsDynamicSourceLocations(), this may be aconst char*
casted to StaticStringType.file – Static string (see registerStaticString()) of the filename where the profile zone was started (usually
__FILE__
). If supportsDynamicSourceLocations(), this may be aconst char*
casted to StaticStringType.line – Line number in the file where the profile zone was started (usually LINE).
nameFmt – The event name format, followed by args. For beginStatic() this must be a StaticStringType from registerStaticString().
- Returns
An opaque ZoneId that should be passed to endEx().
-
ZoneId (*
beginDynamic
)(const uint64_t mask, StaticStringType function, StaticStringType file, int line, const char *nameFmt, ...)¶ Starts the profiling event.
This event could be a fiber-based event (i.e. could yield and resume on another thread) if tasking scheduler provides proper
startFiber
/stopFiber
calls.- Parameters
mask – Event capture mask.
function – Static string (see registerStaticString()) of the function where the profile zone is located (usually
__func__
). If supportsDynamicSourceLocations(), this may be aconst char*
casted to StaticStringType.file – Static string (see registerStaticString()) of the filename where the profile zone was started (usually
__FILE__
). If supportsDynamicSourceLocations(), this may be aconst char*
casted to StaticStringType.line – Line number in the file where the profile zone was started (usually LINE).
nameFmt – The event name format, followed by args. For beginStatic() this must be a StaticStringType from registerStaticString().
- Returns
An opaque ZoneId that should be passed to endEx().
-
void (*
end
)(const uint64_t mask)¶ Stops the profiling event.
This event could be a fiber-based event (i.e. could yield and resume on another thread) if tasking scheduler provides proper
startFiber
/stopFiber
calls.Warning
This call is deprecated. Please use endEx() instead. This function will not be removed but should also not be called in new code.
- Parameters
mask – Event capture mask.
-
void (*
frameStatic
)(const uint64_t mask, StaticStringType nameFmt)¶ Inserts a frame marker for the calling thread in the profiling output, for profilers that support frame markers.
Note
The name provided below must be the same for each set of frames, and called each time from the same thread. For example you might have main thread frames that all are named “frame” and GPU frames that are named “GPU
frame”. Some profilers (i.e. profiler-cpu to Tracy conversion) require that the name contain the word “frame.”
- Parameters
mask – Deprecated and ignored for frame events.
nameFmt – The frame set name format, followed by args. For frameStatic() this must be a StaticStringType from registerStaticString().
-
void (*
frameDynamic
)(const uint64_t mask, const char *nameFmt, ...)¶ Inserts a frame marker for the calling thread in the profiling output, for profilers that support frame markers.
Note
The name provided below must be the same for each set of frames, and called each time from the same thread. For example you might have main thread frames that all are named “frame” and GPU frames that are named “GPU
frame”. Some profilers (i.e. profiler-cpu to Tracy conversion) require that the name contain the word “frame.”
- Parameters
mask – Deprecated and ignored for frame events.
nameFmt – The frame set name format, followed by args. For frameStatic() this must be a StaticStringType from registerStaticString().
-
void (*
valueFloatStatic
)(const uint64_t mask, float value, StaticStringType valueFmt)¶ Send floating point value to the profiler.
- Parameters
mask – Value capture mask.
value – Value.
valueFmt – The value name format, followed by args. For valueFloatStatic() this must be a StaticStringType from registerStaticString().
-
void (*
valueFloatDynamic
)(const uint64_t mask, float value, const char *valueFmt, ...)¶ Send floating point value to the profiler.
- Parameters
mask – Value capture mask.
value – Value.
valueFmt – The value name format, followed by args. For valueFloatStatic() this must be a StaticStringType from registerStaticString().
-
void (*
valueIntStatic
)(const uint64_t mask, int32_t value, StaticStringType valueFmt)¶ Send signed integer value to the profiler.
- Parameters
mask – Value capture mask.
value – Value.
valueFmt – The value name format, followed by args. For valueIntStatic() this must be a StaticStringType from registerStaticString().
-
void (*
valueIntDynamic
)(const uint64_t mask, int32_t value, const char *valueFmt, ...)¶ Send signed integer value to the profiler.
- Parameters
mask – Value capture mask.
value – Value.
valueFmt – The value name format, followed by args. For valueIntStatic() this must be a StaticStringType from registerStaticString().
-
void (*
valueUIntStatic
)(const uint64_t mask, uint32_t value, StaticStringType valueFmt)¶ Send unsigned integer value to the profiler.
- Parameters
mask – Value capture mask.
value – Value.
valueFmt – The value name format, followed by args. For valueUIntStatic() this must be a StaticStringType from registerStaticString().
-
void (*
valueUIntDynamic
)(const uint64_t mask, uint32_t value, const char *valueFmt, ...)¶ Send unsigned integer value to the profiler.
- Parameters
mask – Value capture mask.
value – Value.
valueFmt – The value name format, followed by args. For valueUIntStatic() this must be a StaticStringType from registerStaticString().
-
void (*
nameThreadStatic
)(uint64_t tidOrZero, StaticStringType threadName)¶ Sets a threads name.
- Parameters
tidOrZero – The thread ID to name, or 0 to name the current thread.
nameFmt – The thread name format, followed by args. For nameThreadStatic() this must be a StaticStringType from registerStaticString().
-
void (*
nameThreadDynamic
)(uint64_t tidOrZero, const char *threadName, ...)¶ Sets a threads name.
- Parameters
tidOrZero – The thread ID to name, or 0 to name the current thread.
nameFmt – The thread name format, followed by args. For nameThreadStatic() this must be a StaticStringType from registerStaticString().
-
bool (*
supportsDynamicSourceLocations
)()¶ Checks if the profiler supports dynamic source locations.
Dynamic source locations allow the
file
andfunc
parameters to functions such as beginStatic() and beginDynamic() to be a transient non-literal string on the heap or stack.- Returns
true
if dynamic source locations are supported;false
if they are not supported.
-
StaticStringType (*
registerStaticString
)(const char *string)¶ Helper function for registering a static string.
Note
The profiler must copy all strings. By registering a static string, you are making a contract with the profiler that the string at the provided address will never change. This allows the string to be passed by pointer as an optimization without needing to copy the string.
Note
This function should be called only once per string. The return value should be captured in a variable and passed to the static function such as beginStatic(), frameStatic(), valueStatic(), etc.
- Parameters
string – The static string to register. This must be a string literal or otherwise a string whose address will never change.
- Returns
A StaticStringType that represents the registered static string. If the string could not be registered, kInvalidStaticString is returned.
-
void (*
allocNamedStatic
)(const uint64_t mask, const void *ptr, uint64_t size, StaticStringType name)¶ Send memory allocation event to the profiler for custom pools.
- Parameters
mask – Value capture mask.
ptr – Memory address.
size – Amount of bytes allocated.
name – Static or formatted string which contains the name of the pool.
-
void (*
allocNamedDynamic
)(const uint64_t mask, const void *ptr, uint64_t size, const char *nameFmt, ...)¶ Send memory allocation event to the profiler for custom pools.
- Parameters
mask – Value capture mask.
ptr – Memory address.
size – Amount of bytes allocated.
name – Static or formatted string which contains the name of the pool.
-
void (*
freeNamedStatic
)(const uint64_t mask, const void *ptr, StaticStringType valueFmt)¶ Send memory free event to the profiler for custom pools.
- Parameters
mask – Value capture mask.
ptr – Memory address.
name – Static or formatted string which contains the name of the pool.
-
void (*
freeNamedDynamic
)(const uint64_t mask, const void *ptr, const char *nameFmt, ...)¶ Send memory free event to the profiler for custom pools.
- Parameters
mask – Value capture mask.
ptr – Memory address.
name – Static or formatted string which contains the name of the pool.
-
void (*
allocStatic
)(const uint64_t mask, const void *ptr, uint64_t size)¶ Send memory allocation event to the profiler on the default pool.
- Parameters
mask – Value capture mask.
ptr – Memory address.
size – Amount of bytes allocated.
-
void (*
freeStatic
)(const uint64_t mask, const void *ptr)¶ Send memory free event to the profiler on the default pool.
- Parameters
mask – Value capture mask.
ptr – Memory address.
-
void (*
endEx
)(const uint64_t mask, ZoneId zoneId)¶ Stops the profiling event that was initiated by beginStatic() or beginDynamic().
- Parameters
mask – Event capture mask.
zoneId – The ZoneId returned from beginStatic() or beginDynamic().
-
void (*
emitInstantStatic
)(const uint64_t mask, StaticStringType function, StaticStringType file, int line, InstantType type, StaticStringType nameFmt)¶ Records an instant event on a thread’s timeline at the current time.
Generally not used directly; instead use the CARB_PROFILE_EVENT() macro.
- Parameters
mask – Event capture mask.
function – Static string (see registerStaticString()) of the name of the function containing this event (typically
__func__
). If supportsDynamicSourceLocations(), this may be aconst char*
casted to StaticStringType.file – Static string (see registerStaticString()) of the name of the source file containing this event (typically
__FILE__
). If supportsDynamicSourceLocations(), this may be aconst char*
casted to StaticStringType.line – The line number in
file
containing this event (typically__LINE__
).type – The type of instant event.
nameFmt – The name for the event.
-
void (*
emitInstantDynamic
)(const uint64_t mask, StaticStringType function, StaticStringType file, int line, InstantType type, const char *nameFmt, ...)¶ Records an instant event on a thread’s timeline at the current time.
Generally not used directly; instead use the CARB_PROFILE_EVENT() macro.
Note
This function is slower than using emitInstanceStatic().
- Parameters
mask – Event capture mask.
function – Static string (see registerStaticString()) of the name of the function containing this event (typically
__func__
). If supportsDynamicSourceLocations(), this may be aconst char*
casted to StaticStringType.file – Static string (see registerStaticString()) of the name of the source file containing this event (typically
__FILE__
). If supportsDynamicSourceLocations(), this may be aconst char*
casted to StaticStringType.line – The line number in
file
containing this event (typically__LINE__
).type – The type of instant event.
nameFmt – The name for the event.
... –
printf
-style varargs fornameFmt
.
-
void (*
emitFlowStatic
)(const uint64_t mask, StaticStringType function, StaticStringType file, int line, FlowType type, uint64_t id, StaticStringType name)¶ Puts a flow event on the timeline at the current line.
Generally not used directly; instead use the CARB_PROFILE_FLOW_BEGIN() and CARB_PROFILE_FLOW_END() macros.
Flow events draw an arrow from one point (the FlowType::Begin location) to another point (the FlowType::End location). These two points can be in different threads but must have a matching
id
field. Only the FlowType::Begin event must specify aname
. Theid
field is meant to be unique across profiler runs, but may be reused as long as thename
field matches across all FlowType::Begin events and events occur on the global timeline as FlowType::Begin followed by FlowType::End.A call with FlowType::Begin will automatically insert an instant event on the current thread’s timeline.
- Parameters
mask – Event capture mask.
function – Static string (see registerStaticString()) of the name of the function containing this event. If supportsDynamicSourceLocations(), this may be a
const char*
casted to StaticStringType.file – Static string (see registerStaticString()) of the name of the source file containing this event (typically
__FILE__
). If supportsDynamicSourceLocations(), this may be aconst char*
casted to StaticStringType.line – THe line number in
file
containing this event (typically__LINE__
).type – The type of flow marker.
id – A unique identifier to tie
Begin
andEnd
events together.name – The name for the flow event. Only required for FlowType::Begin; if specified for FlowType::End it must match exactly or be
nullptr
.
-
void (*
emitFlowDynamic
)(const uint64_t mask, StaticStringType function, StaticStringType file, int line, FlowType type, uint64_t id, const char *name, ...)¶ Puts a flow event on the timeline at the current line.
Generally not used directly; instead use the CARB_PROFILE_FLOW_BEGIN() and CARB_PROFILE_FLOW_END() macros.
Flow events draw an arrow from one point (the FlowType::Begin location) to another point (the FlowType::End location). These two points can be in different threads but must have a matching
id
field. Only the FlowType::Begin event must specify aname
. Theid
field is meant to be unique across profiler runs, but may be reused as long as thename
field matches across all FlowType::Begin events and events occur on the global timeline as FlowType::Begin followed by FlowType::End.A call with FlowType::Begin will automatically insert an instant event on the current thread’s timeline.
Note
This function is slower than using emitFlowStatic().
- Parameters
mask – Event capture mask.
function – Static string (see registerStaticString()) of the name of the function containing this event. If supportsDynamicSourceLocations(), this may be a
const char*
casted to StaticStringType.file – Static string (see registerStaticString()) of the name of the source file containing this event (typically
__FILE__
). If supportsDynamicSourceLocations(), this may be aconst char*
casted to StaticStringType.line – THe line number in
file
containing this event (typically__LINE__
).type – The type of flow marker.
id – A unique identifier to tie
Begin
andEnd
events together.name – The name for the flow event. Only required for FlowType::Begin; if specified for FlowType::End it must match exactly or be
nullptr
.... –
printf
-style varargs fornameFmt
.
-
GpuContextId (*
createGpuContext
)(const char *name, int64_t correlatedCpuTimestampNs, int64_t correlatedGpuTimestamp, float gpuTimestampPeriodNs, const char *graphicApi)¶ Create a new GPU profiling context that allows injecting timestamps coming from a GPU in a deferred manner.
- Parameters
name – name of the context
correlatedCpuTimestampNs – correlated GPU clock timestamp (in ns)
correlatedGpuTimestamp – correlated GPU clock timestamp (raw value)
gpuTimestampPeriodNs – is the number of nanoseconds required for a GPU timestamp query to be incremented by 1.
graphicApi – string of graphic API used [‘vulkan’/’d3d12’]
- Returns
a valid ID or kInvalidGpuContextId if creation fails
-
void (*
destroyGpuContext
)(GpuContextId contextId)¶ Destroy a previously created GPU Context.
- Parameters
contextId – id of the context, returned by createGpuContext
-
bool (*
calibrateGpuContext
)(GpuContextId contextId, int64_t correlatedCpuTimestampNs, int64_t previousCorrelatedCpuTimestampNs, int64_t correlatedGpuTimestamp)¶ Submit context calibration information that allows correlating CPU and GPU clocks.
- Parameters
contextId – id of the context, returned by createGpuContext
correlatedCpuTimestampNs – the new CPU timestamp at the time of correlation (in ns)
previousCorrelatedCpuTimestamp – the CPU timestamp at the time of previous correlation (in ns)
correlatedGpuTimestamp – the new raw GPU timestamp at the time of correlation
-
void (*
beginGpuQueryStatic
)(const uint64_t mask, StaticStringType functionName, StaticStringType fileName, int line, GpuContextId contextId, uint32_t queryId, StaticStringType name)¶ Record the beginning of a new GPU timestamp query.
- Parameters
mask – Event capture mask.
function – Static string (see registerStaticString()) of the name of the function containing this event (typically
__func__
). If supportsDynamicSourceLocations(), this may be aconst char*
casted to StaticStringType.file – Static string (see registerStaticString()) of the name of the source file containing this event (typically
__FILE__
). If supportsDynamicSourceLocations(), this may be aconst char*
casted to StaticStringType.line – The line number in
file
containing this event (typically__LINE__
).contextId – the id of the context as returned by createGpuContext
queryId – unique query id (for identification when passing to setGpuQueryValue)
name – The name for the event.
-
void (*
beginGpuQueryDynamic
)(const uint64_t mask, StaticStringType functionName, StaticStringType fileName, int line, GpuContextId contextId, uint32_t queryId, const char *nameFmt, ...)¶ Record the beginning of a new GPU timestamp query.
- Parameters
mask – Event capture mask.
function – Static string (see registerStaticString()) of the name of the function containing this event (typically
__func__
). If supportsDynamicSourceLocations(), this may be aconst char*
casted to StaticStringType.file – Static string (see registerStaticString()) of the name of the source file containing this event (typically
__FILE__
). If supportsDynamicSourceLocations(), this may be aconst char*
casted to StaticStringType.line – The line number in
file
containing this event (typically__LINE__
).contextId – the id of the context as returned by createGpuContext
queryId – unique query id (for identification when passing to setGpuQueryValue)
name – The name for the event.
-
void (*
endGpuQuery
)(const uint64_t mask, GpuContextId contextId, uint32_t queryId)¶ Record the end of a new GPU timestamp query.
- Parameters
mask – Event capture mask.
contextId – the id of the context as returned by createGpuContext
queryId – unique query id (for identification when passing to setGpuQueryValue)
-
void (*
setGpuQueryValue
)(const uint64_t mask, GpuContextId contextId, uint32_t queryId, int64_t gpuTimestamp)¶ Set the value we’ve received from the GPU for a query (begin or end) we’ve issued in the past.
- Parameters
contextId – the id of the context as returned by createGpuContext
queryId – unique query id specified at begin/end time
gpuTimestamp – raw GPU timestamp value
-
LockableId (*
createLockable
)(const uint64_t mask, const char *name, const bool isSharedLock, StaticStringType functionName, StaticStringType fileName, int line)¶ Create a lockable context which we can use to tag lock operation.
- Parameters
mask – Event capture mask. If the mask does not match the current capture mask, the lockable is not created and kInvalidLockableId is returned.
name – context name
isSharedLock – if this shared for a shared lock
functionName – Static string (see registerStaticString()) of the name of the function containing this event (typically
__func__
). If supportsDynamicSourceLocations(), this may be aconst char*
casted to StaticStringType.fileName – Static string (see registerStaticString()) of the name of the source file containing this event (typically
__FILE__
). If supportsDynamicSourceLocations(), this may be aconst char*
casted to StaticStringType.line – The line number in
file
containing this event (typically__LINE__
).
-
void (*
destroyLockable
)(LockableId lockableId)¶ Destroy a lockable context.
- Parameters
lockableId – the id of the lockable as returned by createLockable
-
void (*
lockableOperation
)(LockableId lockableId, LockableOperationType operation)¶ Record a lockable operation.
- Parameters
lockableId – the id of the lockable as returned by createLockable
operation – which lock operation to tag
-
uint64_t (*
setMaskCallback
)(MaskCallbackFn func, bool enabled)¶ Used by carb::profiler::registerProfilerForClient() and carb::profiler::deregisterProfilerForClient() to register a callback for keeping the profiler mask up to date.
- Parameters
func – The callback function to register.
enabled –
true
to register the callback,false
to unregister the callback.
- Returns
The current profiler mask.
Public Static Functions
-
static inline carb::InterfaceDesc
getInterfaceDesc
()¶ Returns information about this interface. Auto-generated by CARB_PLUGIN_INTERFACE(). *
- Returns
The carb::InterfaceDesc struct with information about this interface.
-
template<typename