User Guide

Intel® VTune™ Profiler User Guide

ID 766319
Date 3/31/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

Counter API

The Counter API is used to observe user-defined global characteristic counters that are unknown to VTune Profiler. For example, it is useful for system on a chip (SoC) development when different counters may represent different parts of the SoC and count some hardware characteristics.

To define and create a counter object, use the following primitives:

__itt_counter

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

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

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

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

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

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

A counter name and domain name should be specified. To load a specialized type of data, specify the counter type. By default the unsigned int64 type is used.

Parameters of the primitives:

[in]

domain

Counter domain

[in]

name

Counter name

[in]

type

Counter type

To increment\decrement counter value, use the following primitives:

NOTE:

Applicable to uint64 counters only.

__itt_counter_inc (__itt_counter id);

__itt_counter_inc_delta(__itt_counter id, unsigned long long value);

__itt_counter_dec(__itt_counter id);

__itt_counter_dec_delta(__itt_counter id, unsigned long long value);

To directly set the counter value, use the following primitive:

__itt_counter_set_value(__itt_counter id, void *value_ptr);

Parameters of the primitive:

[in]

id

Counter ID

[in]

value_ptr

Counter value

To remove an existing counter:

__itt_counter_destroy(__itt_counter id);

Usage Example

The following 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);