Counter API

A Counter is a user-defined characteristic or metric of hardware or software behavior that you use to collect information about execution breakdown. You can also use counters to correlate this information with tasks, events, and markers.

For example, the development of system-on-a-chip (SoC) benefits from several counters that represent different parts of the SoC to count some hardware characteristics.

Define and create a counter object

Use these primitives:

__itt_counter __itt_counter_create(const char *name, const char *domain);

__itt_counter __itt_counter_createA(const char *name, const char *domain);

__itt_counter __itt_counter_createW(const wchar_t *name, const wchar_t *domain);

__itt_counter __itt_counter_create_typed(const char *name, const char *domain, __itt_metadata_type type);

__itt_counter __itt_counter_create_typedA(const char *name, const char *domain, __itt_metadata_type type);

__itt_counter __itt_counter_create_typedW(const wchar_t *name, const wchar_t *domain, __itt_metadata_type type);

__itt_counter __itt_counter_create_v3(__itt_domain* domain, const char* name,__itt_metadata_type type);

You must specify a counter name and domain name. To load a specialized type of data, specify the counter type. The default counter type is uint64_t.

Parameters of the primitives:

Type	Parameter	Description
[in]	domain	Counter domain
[in]	name	Counter name
[in]	type	Counter type

Increment/decrement a counter value

Use these primitives:

void __itt_counter_inc (__itt_counter id);

void __itt_counter_inc_delta(__itt_counter id, unsigned long long value);

void __itt_counter_dec(__itt_counter id);

void __itt_counter_dec_delta(__itt_counter id, unsigned long long value);

Note

These primitives are applicable to uint64 counters only.

Directly set the counter value

Use:

void __itt_counter_set_value(__itt_counter id, void *value_ptr);

void __itt_counter_set_value_v3(__itt_counter counter, void *value_ptr);

Parameters of the primitive:

Type	Parameter	Description
[in]	id	Counter ID
[in]	value_ptr	Counter value

Remove an existing counter

Use:

void __itt_counter_destroy(__itt_counter id);

Usage Example

This example creates a counter that measures temperature and memory usage metrics:

#include "ittnotify.h"


__itt_counter temperatureCounter = __itt_counter_create("Temperature", "Domain");
__itt_counter memoryUsageCounter = __itt_counter_create("Memory Usage", "Domain");
unsigned __int64 temperature;


while (...)
{
    ...
    temperature = getTemperature();
    __itt_counter_set_value(temperatureCounter, &temperature);


    __itt_counter_inc_delta(memoryUsageCounter, getAllocatedMemSize());
    __itt_counter_dec_delta(memoryUsageCounter, getDeallocatedMemSize());
    ...
}


__itt_counter_destroy(temperatureCounter);
__itt_counter_destroy(memoryUsageCounter);