Profiling macros

Collaboration diagram for Profiling macros:

Macros
#define	KZ_LOG_CATEGORY_PROFILING
	The profiling log category.
#define	KZ_LOG_DEFAULT_CATEGORY_PROFILING_STATE
	Defines profiling log category state.
#define	KZ_PROFILING_CATEGORY_GENERIC
	The generic profiling category to profile code not specific to other profiling categories.
#define	KZ_PROFILING_DEFAULT_CATEGORY_GENERIC_STATE
	Defines generic profiling category compile time state.
#define	KZ_PROFILING_DEFAULT_SAMPLE_BUFFER_SIZE
	Default sample buffer size.
#define	KZ_PROFILING_THIS_FUNCTION_NAME
	Gets the fully qualified, if possible, name of the enclosing function.
#define	kzProfileFunction(category)
	Profiles the execution time of a function.
#define	kzProfileScope(category, scopeProfilerName)
	Profiles the execution time of a scope.
#define	kzProfileScopeExtended(category, profilerRegistry, scopeProfilerName, sampleBufferSize)
	Profiles the execution time of a scope using custom profiler registry and sample buffer size.
#define	kzProfileScopeWithSampler(category, profiler, samplerClass)
	Profiles 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.
#define	kzProfilingGetDefaultRegistry()
	Gets the reference to the default profiler registry.
#define	KZ_PROFILING_ENABLED_CATEGORY
#define	KZ_PROFILING_DISABLED_CATEGORY
	The disabled profiling category state.
#define	kzProfilingCreateCategory(compileTimeState, name, sampleBufferSize)
	Creates a new profiling category.
#define	kzProfilingRegisterCategory(category, initialRuntimeState)
	Registers a new profiling category.
#define	kzProfilingRegisterExportedCategory(exportImportDirective, category, initialRuntimeState)
	Registers a new profiling category that is exported/imported to/from shared library.
#define	kzProfilingInitializeCategory(exportImportDirective, category, initialRuntimeState)
	Initializes a profiling category.
#define	kzProfilingCategorySetRuntimeState(category, newRuntimeState)
	Sets the runtime state of a profiling category.
#define	kzProfilingSetAllCategoriesRuntimeState(newRuntimeState)
	Sets the runtime state of all profiling categories.
#define	kzProfilingGetCategoryCompileTimeState(category)
	Gets the compile-time category state.
#define	kzProfilingGetCategoryName(category)
	Gets the name of a profiling category.
#define	kzProfilingGetCategorySampleBufferSize(category)
	Gets the sample buffer size of a profiling category.
#define	kzProfilingGetCategoryRuntimeReference(category)
	Gets the runtime profiling category reference.
#define	kzProfilingIsCategoryEnabledAtRuntime(category)
	Checks whether a profiling category is enabled at runtime.
#define	kzProfilingIsCategoryEnabledAtCompileTime(category)
	Checks whether a profiling category is enabled at compile time.

Detailed Description

Use profiling macros to instrument the code for runtime performance profiling.

Kanzi profiling build

The Kanzi profiling build includes profiled Kanzi libraries. Use the Kanzi profiling build to measure the performance of different parts of Kanzi engine:

• For startup profiling, use Startup profiling
• For main loop task profiling, use Main loop profiling.

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.

Macro Definition Documentation

KZ_PROFILING_THIS_FUNCTION_NAME

#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.

Note

Some compilers do not provide a way to obtain the name of the enclosing function. When you use such a compiler, the value of this macro is undefined.

KZ_PROFILING_DEFAULT_SAMPLE_BUFFER_SIZE

#define KZ_PROFILING_DEFAULT_SAMPLE_BUFFER_SIZE

Default sample buffer size.

kzProfilingGetDefaultRegistry

#define kzProfilingGetDefaultRegistry

(

)

Gets the reference to the default profiler registry.

Returns

The reference to the default profiler registry.

kzProfileScope

#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.

Parameters

category	The profiling category.
scopeProfilerName	The name of the profiler.

See also

kanzi::ProfilingCategory

Example

To profile a scope:

    {
        // Simple scope profiling
        // Category is KZ_PROFILING_CATEGORY_GENERIC
        // Profiler is named "Something"
        // The profiler is registered within default profiler registry.
        // Sample Buffer size is taken from Category
        // The profiler is registered within default profiler registry.
        kzProfileScope(KZ_PROFILING_CATEGORY_GENERIC, "Something");
 
        // Do something
    }
 
    {
        // Extended scope profiling
        // Category is MY_PROFILING_CATEGORY
        // The profiler is registered within default profiler registry.
        // The profiler is named "SomethingElse"
        // Sample buffer size is set to 100.
        kzProfileScopeExtended(MY_PROFILING_CATEGORY, kzProfilingGetDefaultRegistry(), "SomethingElse", 100);
 
        // Do something else
    }

kzProfileScopeExtended

#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.

Parameters

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.

See also

kanzi::ProfilingCategory

Example

To profile the execution time of a scope using custom profiler registry and sample buffer size:

    {
        // Simple scope profiling
        // Category is KZ_PROFILING_CATEGORY_GENERIC
        // Profiler is named "Something"
        // The profiler is registered within default profiler registry.
        // Sample Buffer size is taken from Category
        // The profiler is registered within default profiler registry.
        kzProfileScope(KZ_PROFILING_CATEGORY_GENERIC, "Something");
 
        // Do something
    }
 
    {
        // Extended scope profiling
        // Category is MY_PROFILING_CATEGORY
        // The profiler is registered within default profiler registry.
        // The profiler is named "SomethingElse"
        // Sample buffer size is set to 100.
        kzProfileScopeExtended(MY_PROFILING_CATEGORY, kzProfilingGetDefaultRegistry(), "SomethingElse", 100);
 
        // Do something else
    }

kzProfileFunction

#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.

Parameters

category

The profiling category.

See also

kanzi::ProfilingCategory

Example

To profile the execution time of a function:

void profilingFunction()
{
    // Profile this function.
    kzProfileFunction(KZ_PROFILING_CATEGORY_GENERIC);
 
    // Do something
}

kzProfileScopeWithSampler

#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.

Parameters

category	The profiling category.
profiler	The profiler.
samplerClass	The profiling sampler class type.

See also

kanzi::ProfilingCategory

Example

To profile the execution time of a scope using a sampler:

// Define a custom sampler
class LoggingIntervalProfilingSampler : public IntervalProfilingSampler
{
public:
    explicit LoggingIntervalProfilingSampler(string_view scopeName) :
        m_name(scopeName)
    {
    }
 
    void start()
    {
        kzLogInfo(KZ_LOG_CATEGORY_PROFILING, ("Starting measuring {} scope...", m_name));
        IntervalProfilingSampler::start();
    }
 
    void stop()
    {
        IntervalProfilingSampler::stop();
        kzLogInfo(KZ_LOG_CATEGORY_PROFILING, ("Finished measuring {} scope...", m_name));
    }
 
private:
    string_view m_name;
};
 
void profilingWithSampler()
{
    // Create interval profiler and assign it to KZ_GENERIC_PROFILING_CATEGORY. The sample buffer size is 100.
    IntervalProfilerSharedPtr profiler =
        IntervalProfiler::create("my profiler",
                                    kzProfilingGetCategoryRuntimeReference(KZ_PROFILING_CATEGORY_GENERIC),
                                    100);
 
    {
        // Profile this scope with IntervalProfilingSampler.
        kzProfileScopeWithSampler(KZ_PROFILING_CATEGORY_GENERIC, profiler, IntervalProfilingSampler);
 
        // Do something
    }
 
    {
        // Profile this scope with LoggingIntervalProfilingSampler, which requires to pass name of the scope to the constructor.
        kzProfileScopeWithSamplerExtended(KZ_PROFILING_CATEGORY_GENERIC, profiler, LoggingIntervalProfilingSampler, ("SomethingElse"));
 
        // Do something else
    }
}

kzProfileScopeWithSamplerExtended

#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.

Parameters

category	The profiling category.
profiler	The profiler.
samplerClass	The profiling sampler class type.
samplerConstructorArguments	The sampler constructor arguments enclosed in parentheses.

See also

kanzi::ProfilingCategory

Example

To profile the execution time of a scope using a sampler with constructor arguments:

// Define a custom sampler
class LoggingIntervalProfilingSampler : public IntervalProfilingSampler
{
public:
    explicit LoggingIntervalProfilingSampler(string_view scopeName) :
        m_name(scopeName)
    {
    }
 
    void start()
    {
        kzLogInfo(KZ_LOG_CATEGORY_PROFILING, ("Starting measuring {} scope...", m_name));
        IntervalProfilingSampler::start();
    }
 
    void stop()
    {
        IntervalProfilingSampler::stop();
        kzLogInfo(KZ_LOG_CATEGORY_PROFILING, ("Finished measuring {} scope...", m_name));
    }
 
private:
    string_view m_name;
};
 
void profilingWithSampler()
{
    // Create interval profiler and assign it to KZ_GENERIC_PROFILING_CATEGORY. The sample buffer size is 100.
    IntervalProfilerSharedPtr profiler =
        IntervalProfiler::create("my profiler",
                                    kzProfilingGetCategoryRuntimeReference(KZ_PROFILING_CATEGORY_GENERIC),
                                    100);
 
    {
        // Profile this scope with IntervalProfilingSampler.
        kzProfileScopeWithSampler(KZ_PROFILING_CATEGORY_GENERIC, profiler, IntervalProfilingSampler);
 
        // Do something
    }
 
    {
        // Profile this scope with LoggingIntervalProfilingSampler, which requires to pass name of the scope to the constructor.
        kzProfileScopeWithSamplerExtended(KZ_PROFILING_CATEGORY_GENERIC, profiler, LoggingIntervalProfilingSampler, ("SomethingElse"));
 
        // Do something else
    }
}

KZ_LOG_DEFAULT_CATEGORY_PROFILING_STATE

#define KZ_LOG_DEFAULT_CATEGORY_PROFILING_STATE

Defines profiling log category state.

The profiling log category is enabled by default.

See also

KZ_LOG_CATEGORY_PROFILING

KZ_LOG_CATEGORY_PROFILING

#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.

KZ_PROFILING_DEFAULT_CATEGORY_GENERIC_STATE

#define KZ_PROFILING_DEFAULT_CATEGORY_GENERIC_STATE

Defines generic profiling category compile time state.

The generic profiling category is enabled by default.

See also

KZ_PROFILING_CATEGORY_GENERIC

KZ_PROFILING_CATEGORY_GENERIC

#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.

KZ_PROFILING_ENABLED_CATEGORY

#define KZ_PROFILING_ENABLED_CATEGORY

The enabled profiling category state.

KZ_PROFILING_DISABLED_CATEGORY

#define KZ_PROFILING_DISABLED_CATEGORY

The disabled profiling category state.

kzProfilingCreateCategory

#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.

Parameters

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.

Example

To create and register a profiling category:

#define MY_PROFILING_CATEGORY kzProfilingCreateCategory(KZ_PROFILING_ENABLED_CATEGORY, "myCategory", KZ_PROFILING_DEFAULT_SAMPLE_BUFFER_SIZE)
kzProfilingRegisterCategory(MY_PROFILING_CATEGORY, KZ_PROFILING_ENABLED_CATEGORY)
 
// kzProfilingInitializeCategory must be placed in a cpp file.
kzProfilingInitializeCategory(, MY_PROFILING_CATEGORY, KZ_PROFILING_ENABLED_CATEGORY)

kzProfilingRegisterCategory

#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.

Parameters

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).

Example

To create and register a profiling category:

#define MY_PROFILING_CATEGORY kzProfilingCreateCategory(KZ_PROFILING_ENABLED_CATEGORY, "myCategory", KZ_PROFILING_DEFAULT_SAMPLE_BUFFER_SIZE)
kzProfilingRegisterCategory(MY_PROFILING_CATEGORY, KZ_PROFILING_ENABLED_CATEGORY)
 
// kzProfilingInitializeCategory must be placed in a cpp file.
kzProfilingInitializeCategory(, MY_PROFILING_CATEGORY, KZ_PROFILING_ENABLED_CATEGORY)

kzProfilingRegisterExportedCategory

#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.

Parameters

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).

Example

To create and register an exported profiling category:

// Example export/import macro for Windows.
#ifdef USE_SHARED_LIBRARY
#ifdef COMPILE_LIBRARY_CODE
// Compiling shared library: export category to shared library.
#define EXPORT_IMPORT_API __declspec(dllexport)
#else
// Compiling user code: import category from shared library.
#define EXPORT_IMPORT_API __declspec(dllimport)
#endif
#else
// Use empty macro for static linking.
#define EXPORT_IMPORT_API
#endif
 
#define MY_PROFILING_CATEGORY_EXPORTED kzProfilingCreateCategory(KZ_PROFILING_ENABLED_CATEGORY, "myCategoryExported", KZ_PROFILING_DEFAULT_SAMPLE_BUFFER_SIZE)
kzProfilingRegisterExportedCategory(EXPORT_IMPORT_API, MY_PROFILING_CATEGORY_EXPORTED, KZ_PROFILING_DISABLED_CATEGORY)
 
// kzProfilingInitializeCategory must be placed in a cpp file.
kzProfilingInitializeCategory(EXPORT_IMPORT_API, MY_PROFILING_CATEGORY_EXPORTED, KZ_PROFILING_DISABLED_CATEGORY)

kzProfilingInitializeCategory

#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().

Parameters

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).

kzProfilingCategorySetRuntimeState

#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.

Parameters

category	The profiling category macro.
newRuntimeState	New runtime state of the category: enabled (KZ_PROFILING_ENABLED_CATEGORY) or disabled (KZ_PROFILING_DISABLED_CATEGORY).

kzProfilingSetAllCategoriesRuntimeState

#define kzProfilingSetAllCategoriesRuntimeState

(

newRuntimeState

)

Sets the runtime state of all profiling categories.

Parameters

newRuntimeState

New runtime state for all categories: enabled (KZ_PROFILING_ENABLED_CATEGORY) or disabled (KZ_PROFILING_DISABLED_CATEGORY).

kzProfilingGetCategoryCompileTimeState

#define kzProfilingGetCategoryCompileTimeState

(

category

)

Gets the compile-time category state.

Parameters

category

The profiling category macro to fetch state.

Returns

The state of category: enabled (KZ_PROFILING_ENABLED_CATEGORY) or disabled (KZ_PROFILING_DISABLED_CATEGORY).

kzProfilingGetCategoryName

#define kzProfilingGetCategoryName

(

category

)

Gets the name of a profiling category.

Parameters

category

The profiling category macro to fetch name.

Returns

The name of the category.

kzProfilingGetCategorySampleBufferSize

#define kzProfilingGetCategorySampleBufferSize

(

category

)

Gets the sample buffer size of a profiling category.

Parameters

category

The profiling category macro to fetch sample buffer size.

Returns

The sample buffer size of the category.

kzProfilingGetCategoryRuntimeReference

#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.

Parameters

category

The profiling category macro to fetch category runtime reference.

Returns

Reference to kanzi::ProfilingCategory.

kzProfilingIsCategoryEnabledAtRuntime

#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.

Parameters

category

The profiling category macro to fetch status.

Returns

KZ_PROFILING_DISABLED_CATEGORY if the category is disabled at compile time, otherwise true/false, if profiling category is enabled/disabled at runtime.

kzProfilingIsCategoryEnabledAtCompileTime

#define kzProfilingIsCategoryEnabledAtCompileTime

(

category

)

Checks whether a profiling category is enabled at compile time.

Parameters

category

The profiling category macro to test status.

Returns

KZ_PROFILING_ENABLED_CATEGORY / KZ_PROFILING_DISABLED_CATEGORY, when profiling category is enabled / disabled.