Use profiling macros to instrument the code for runtime performance profiling. More...
Macros | |
#define | KZ_LOG_CATEGORY_PROFILING |
The profiling log category. More... | |
#define | KZ_LOG_DEFAULT_CATEGORY_PROFILING_STATE |
Defines profiling log category state. More... | |
#define | KZ_PROFILING_CATEGORY_GENERIC |
The generic profiling category to profile code not specific to other profiling categories. More... | |
#define | KZ_PROFILING_DEFAULT_CATEGORY_GENERIC_STATE |
Defines generic profiling category compile time state. More... | |
#define | KZ_PROFILING_DEFAULT_SAMPLE_BUFFER_SIZE |
Default sample buffer size. More... | |
#define | KZ_PROFILING_THIS_FUNCTION_NAME |
Gets the fully qualified, if possible, name of the enclosing function. More... | |
#define | kzProfileFunction(category) |
Profiles the execution time of a function. More... | |
#define | kzProfileScope(category, scopeProfilerName) |
Profiles the execution time of a scope. More... | |
#define | kzProfileScopeExtended(category, profilerRegistry, scopeProfilerName, sampleBufferSize) |
Profiles the execution time of a scope using custom profiler registry and sample buffer size. More... | |
#define | kzProfileScopeWithSampler(category, profiler, samplerClass) |
Profiles the execution time of a scope using a sampler. More... | |
#define | kzProfileScopeWithSamplerExtended(category, profiler, samplerClass, samplerConstructorArguments) |
Profiles the execution time of a scope using a sampler with constructor arguments. More... | |
#define | kzProfilingGetDefaultRegistry() |
Gets the reference to the default profiler registry. More... | |
#define | KZ_PROFILING_ENABLED_CATEGORY |
#define | KZ_PROFILING_DISABLED_CATEGORY |
The disabled profiling category state. More... | |
#define | kzProfilingCreateCategory(compileTimeState, name, sampleBufferSize) |
Creates a new profiling category. More... | |
#define | kzProfilingRegisterCategory(category, initialRuntimeState) |
Registers a new profiling category. More... | |
#define | kzProfilingRegisterExportedCategory(exportImportDirective, category, initialRuntimeState) |
Registers a new profiling category that is exported/imported to/from shared library. More... | |
#define | kzProfilingInitializeCategory(exportImportDirective, category, initialRuntimeState) |
Initializes a profiling category. More... | |
#define | kzProfilingCategorySetRuntimeState(category, newRuntimeState) |
Sets the runtime state of a profiling category. More... | |
#define | kzProfilingSetAllCategoriesRuntimeState(newRuntimeState) |
Sets the runtime state of all profiling categories. More... | |
#define | kzProfilingGetCategoryCompileTimeState(category) |
Gets the compile-time category state. More... | |
#define | kzProfilingGetCategoryName(category) |
Gets the name of a profiling category. More... | |
#define | kzProfilingGetCategorySampleBufferSize(category) |
Gets the sample buffer size of a profiling category. More... | |
#define | kzProfilingGetCategoryRuntimeReference(category) |
Gets the runtime profiling category reference. More... | |
#define | kzProfilingIsCategoryEnabledAtRuntime(category) |
Checks whether a profiling category is enabled at runtime. More... | |
#define | kzProfilingIsCategoryEnabledAtCompileTime(category) |
Checks whether a profiling category is enabled at compile time. More... | |
Use profiling macros to instrument the code for runtime performance profiling.
The Kanzi profiling build includes profiled Kanzi libraries. Use the Kanzi profiling build to measure the performance of different parts of Kanzi engine:
Use the KANZI_PROFILING_BUILD macro to check whether the code is compiled with the Kanzi Profiling build configuration. The KANZI_PROFILING_BUILD macro is defined for the Profiling build only.
For an example on how to extract profiler samples, see kanzi::AbstractProfiler.
#define KZ_PROFILING_THIS_FUNCTION_NAME |
Gets the fully qualified, if possible, name of the enclosing function.
If you use this macro outside of the function or method body, the behavior is undefined.
#define KZ_PROFILING_DEFAULT_SAMPLE_BUFFER_SIZE |
Default sample buffer size.
#define kzProfilingGetDefaultRegistry | ( | ) |
Gets the reference to the default profiler registry.
#define kzProfileScope | ( | category, | |
scopeProfilerName | |||
) |
Profiles the execution time of a scope.
Call this macro in the beginning of the scope that you want to profile. The behavior of this macro is controlled by the profiling category you provide through the category
parameter. When the compile time state of the profiling category is disabled, this macro produces no code. Otherwise, this macro creates a static profiler object of type IntervalProfiler to store profiling samples. Provide the name for that profiler through the scopeProfilerName
parameter. The profiler is registered within the default profiler registry. To access the default profiler registry use the kzProfilingGetDefaultRegistry() macro.
The runtime state of the profiling category controls whether the profiler collects samples. If the runtime state of the category is disabled, the profiler does not collect samples.
If the profiler collects samples, every time the enclosing scope is entered this macro measures the time spent executing the scope and records the measurement in the sample of type kanzi::IntervalProfilerSampleData, which is after that added to the profiler.
The sample buffer size of the profiler is set to the value of the sample buffer size you assign to the profiling category through the category
parameter. To get the sample buffer size assigned to the profiling category, use the kzProfilingGetCategorySampleBufferSize() macro.
category | The profiling category. |
scopeProfilerName | The name of the profiler. |
To profile a scope:
#define kzProfileScopeExtended | ( | category, | |
profilerRegistry, | |||
scopeProfilerName, | |||
sampleBufferSize | |||
) |
Profiles the execution time of a scope using custom profiler registry and sample buffer size.
Call this macro in the beginning of the scope that you want to profile. The behavior of this macro is similar to the behavior of the kzProfileScope macro. This macro creates a static profiler object which is registered within the profiler registry you provide through the profilerRegistry
parameter. The sample buffer size of the profiler is set to the value you provide through the sampleBufferSize
parameter. The profiling category you provide through the category
parameter controls the behavior of this macro in the same way as it does in the kzProfileScope macro.
category | The profiling category. |
profilerRegistry | The profiler registry to which you add the profiler. |
scopeProfilerName | The name of the profiler. |
sampleBufferSize | The sample buffer size of the profiler. |
To profile the execution time of a scope using custom profiler registry and sample buffer size:
#define kzProfileFunction | ( | category | ) |
Profiles the execution time of a function.
Call this macro in the beginning of the function that you want to profile. The behavior of this macro is similar to the behavior of the kzProfileScope macro. This macro creates a static profiler object which is registered within the default profiler registry. The sample buffer size of the profiler is set to the sample buffer size assigned to the profiling category you provide through the category
parameter. The name of the profiler is set to the value given by the KZ_PROFILING_THIS_FUNCTION_NAME macro.
category | The profiling category. |
To profile the execution time of a function:
#define kzProfileScopeWithSampler | ( | category, | |
profiler, | |||
samplerClass | |||
) |
Profiles the execution time of a scope using a sampler.
Call this macro in the beginning of the scope that you want to profile. Use this macro when you want to create a profiler outside of the scope that you want to profile. Create the profiler before entering the scope and pass that profiler to this macro through the profiler
parameter. The profiling category you provide through the category
parameter controls the behavior of this macro in the same way as it does in the kzProfileScope macro. Provide the sampler class type through the samplerClass
parameter. The sampler class is used to collect samples and add them to the profiler. The kanzi::ProfilingScopeHelper uses the sampler class to collect samples and add them to the profiler. The local sampler object is created every time the enclosing scope is entered.
category | The profiling category. |
profiler | The profiler. |
samplerClass | The profiling sampler class type. |
To profile the execution time of a scope using a sampler:
#define kzProfileScopeWithSamplerExtended | ( | category, | |
profiler, | |||
samplerClass, | |||
samplerConstructorArguments | |||
) |
Profiles the execution time of a scope using a sampler with constructor arguments.
Call this macro in the beginning of the scope that you want to profile. The behavior of this macro is similar to the behavior of kzProfileScopeWithSampler. Use this macro when the constructor of the sampler class that you provide through the samplerClass
parameter requires arguments. Pass the arguments enclosed in parentheses through the samplerConstructorArguments
parameter of the macro. Note that the local sampler object is created every time the enclosing scope is entered which means that the constructor arguments you provide are passed to that local object every time the scope is entered.
category | The profiling category. |
profiler | The profiler. |
samplerClass | The profiling sampler class type. |
samplerConstructorArguments | The sampler constructor arguments enclosed in parentheses. |
To profile the execution time of a scope using a sampler with constructor arguments:
#define KZ_LOG_DEFAULT_CATEGORY_PROFILING_STATE |
Defines profiling log category state.
The profiling log category is enabled by default.
#define KZ_LOG_CATEGORY_PROFILING |
The profiling log category.
Use this log category to write profiling logs only. The KZ_LOG_DEFAULT_CATEGORY_PROFILING_STATE defines the state of this log category.
#define KZ_PROFILING_DEFAULT_CATEGORY_GENERIC_STATE |
Defines generic profiling category compile time state.
The generic profiling category is enabled by default.
#define KZ_PROFILING_CATEGORY_GENERIC |
The generic profiling category to profile code not specific to other profiling categories.
The KZ_PROFILING_DEFAULT_CATEGORY_GENERIC_STATE defines the state of this category.
#define KZ_PROFILING_ENABLED_CATEGORY |
The enabled profiling category state.
#define KZ_PROFILING_DISABLED_CATEGORY |
The disabled profiling category state.
#define kzProfilingCreateCategory | ( | compileTimeState, | |
name, | |||
sampleBufferSize | |||
) |
Creates a new profiling category.
Use the compileTimeState
parameter to set the compile-time state of the profiling category. The Profiling macros use the compile-time state of the category. The string literal you provide in name
is a unique profiling category name.
compileTimeState | The compile-time state of the profiling category: enabled (KZ_LOG_ENABLED_CATEGORY) or disabled (KZ_LOG_DISABLED_CATEGORY). |
name | Unique profiling category name. Must be string literal other than "*", which is used as wildcard name in category filter configuration. |
sampleBufferSize | The sample buffer size of the profiling category. |
To create and register a profiling category:
#define kzProfilingRegisterCategory | ( | category, | |
initialRuntimeState | |||
) |
Registers a new profiling category.
To be able to use a profiling category, you must first register it. To create a profiling category use kzProfilingCreateCategory(). This macro must be called from the global namespace scope.
If the category you provide in the category
parameter is disabled at compile time, this macro emits no code. The macro defines a unique type to control the runtime state of the profiling category. You must provide the initial runtime state of the category through the initialRuntimeState
parameter.
category | The profiling category macro to register. |
initialRuntimeState | The initial runtime state of the category: enabled (KZ_PROFILING_ENABLED_CATEGORY) or disabled (KZ_PROFILING_DISABLED_CATEGORY). |
To create and register a profiling category:
#define kzProfilingRegisterExportedCategory | ( | exportImportDirective, | |
category, | |||
initialRuntimeState | |||
) |
Registers a new profiling category that is exported/imported to/from shared library.
To be able to use a profiling category, you must first register and initialize it. To create a profiling category use kzProfilingCreateCategory(). To initialize a profiling category use kzProfilingInitializeCategory(). You must call this macro from the global namespace scope.
If the category that you provide in the category
parameter is disabled at compile time, this macro emits no code. The macro declares a unique type to control the runtime state of the profiling category. An export/import directive you provide in exportImportDirective
parameter is added to profiling category type declaration. This allows you to use a profiling category registered in DLL or shared library which is linked to your application at runtime. The export/import directive is operating system and toolchain dependent. For example MSVC provides __declspec(dllexport)/__declspec(dllimport) to export/import names.
exportImportDirective | A directive to export/import registered category to/from shared library. |
category | The profiling category macro to register. |
initialRuntimeState | The initial runtime state of the category: enabled (KZ_PROFILING_ENABLED_CATEGORY) or disabled (KZ_PROFILING_DISABLED_CATEGORY). |
To create and register an exported profiling category:
#define kzProfilingInitializeCategory | ( | exportImportDirective, | |
category, | |||
initialRuntimeState | |||
) |
Initializes a profiling category.
To be able to use a profiling category, you must first register and initialize it. To register a profiling category use kzProfilingRegisterExportedCategory(). You must call this macro exactly once from the global namespace scope in a single translation unit.
If the category that you provide in the category
parameter is disabled at compile time, this macro emits no code. The macro statically initializes the profiling category. It also defines the implementation of the unique type declared by kzProfilingRegisterExportedCategory().
exportImportDirective | A directive to export/import registered category to/from shared library. |
category | The profiling category macro to register. |
initialRuntimeState | The initial runtime state of the category: enabled (KZ_PROFILING_ENABLED_CATEGORY) or disabled (KZ_PROFILING_DISABLED_CATEGORY). |
#define kzProfilingCategorySetRuntimeState | ( | category, | |
newRuntimeState | |||
) |
Sets the runtime state of a profiling category.
If the category you provide in the category
parameter is disabled at compile time, this macro emits no code.
category | The profiling category macro. |
newRuntimeState | New runtime state of the category: enabled (KZ_PROFILING_ENABLED_CATEGORY) or disabled (KZ_PROFILING_DISABLED_CATEGORY). |
#define kzProfilingSetAllCategoriesRuntimeState | ( | newRuntimeState | ) |
Sets the runtime state of all profiling categories.
newRuntimeState | New runtime state for all categories: enabled (KZ_PROFILING_ENABLED_CATEGORY) or disabled (KZ_PROFILING_DISABLED_CATEGORY). |
#define kzProfilingGetCategoryCompileTimeState | ( | category | ) |
Gets the compile-time category state.
category | The profiling category macro to fetch state. |
category:
enabled (KZ_PROFILING_ENABLED_CATEGORY) or disabled (KZ_PROFILING_DISABLED_CATEGORY). #define kzProfilingGetCategoryName | ( | category | ) |
Gets the name of a profiling category.
category | The profiling category macro to fetch name. |
category
. #define kzProfilingGetCategorySampleBufferSize | ( | category | ) |
Gets the sample buffer size of a profiling category.
category | The profiling category macro to fetch sample buffer size. |
category
. #define kzProfilingGetCategoryRuntimeReference | ( | category | ) |
Gets the runtime profiling category reference.
The behavior of this macro is defined only if the category you provide in the category
parameter is enabled at compile time. Otherwise the behavior of this macro is undefined.
Use this macro to fetch a reference to profiling category object, associated with the profiling category you provide in the category
parameter. The profiling category object is an object of type kanzi::ProfilingCategory and is used by profiling subsystem to store of runtime category state. You can use the reference provided by this macro to get or set the runtime state of the profiling.
category | The profiling category macro to fetch category runtime reference. |
#define kzProfilingIsCategoryEnabledAtRuntime | ( | category | ) |
Checks whether a profiling category is enabled at runtime.
Use this macro to get the runtime state of the category you provide in the category
parameter. If the category is disabled at compile time, this macro is evaluated to KZ_PROFILING_DISABLED_CATEGORY. Otherwise the runtime state of the category is returned.
category | The profiling category macro to fetch status. |
#define kzProfilingIsCategoryEnabledAtCompileTime | ( | category | ) |
Checks whether a profiling category is enabled at compile time.
category | The profiling category macro to test status. |