Measurement Library Reference
The following tables list all environment variables and API functions of the measurement library. For more information and examples, click the Details link.
Environment Variables
Environment Variable | Short Description |
|---|---|
INTEL_LIBITTNOTIFY64 | Specify the collector library. Details |
TCC_USE_SHARED_MEMORY | Use a shared memory ring buffer instead of a local buffer to store all measurement results. Can be true or false. Default: false. Details |
TCC_MEASUREMENTS_BUFFERS | Define the buffers that will hold the measurements generated from your application. Details |
TCC_MEASUREMENTS_DUMP_FILE | File where measurements are logged after the program finishes. Details |
TCC_MEASUREMENTS_TIME_UNIT | Time unit that will be used to store the results. Details |
API Functions
API Function | Short Description |
|---|---|
Instrumentation and Tracing Technology API (ITT API) functions | Use these functions to instrument your code and initialize measurements |
__itt_domain_create() | Initialize the domain. Details |
__itt_string_handle_create() | Initialize the task handle. Details |
__itt_task_begin() | Start the measurement. Details |
__itt_task_end() | End the measurement. Details |
Functions operating with deadline | Use these functions to set a deadline handler for your measurements |
tcc_measurement_get_deadline_from_env() | Read the deadline value from the environment. Details |
tcc_measurement_set_deadline() | Set the deadline value. Details |
notify_deadline() | Example callback function that prints a message when a deadline violation occurs. Details |
Functions operating with output | Use these functions to print measurement results to the console or a file |
tcc_measurement_print() | Output certain statistics to the console from data structures created in the measurement library collector. Details |
tcc_measurement_print_summary() | Output fields of the measurement structure with selected time unit and the measurements history (measurements buffer content) in JSON format. Details |
tcc_measurement_print_history() | Output the measurements history in the selected time unit and clear the history afterward. Details |
tcc_measurement_print_last_record() | Output the most recent measurement in the selected time unit in JSON format. Details |
Functions operating with time unit | Use these functions to convert measurement results to different time units |
tcc_measurement_get_time_unit_from_env() | Extract the time unit from the environment variable. Details |
tcc_measurement_get_string_from_time_unit() | Convert the time unit enum to the string name. Details |
tcc_measurement_get_time_unit_from_string() | Convert the string name of the time unit to enum. Details |
tcc_measurement_convert_clock_to_timespec() | Convert CPU clock cycles to the standard Linux struct timespec. Details |
tcc_measurement_convert_timespec_to_clock() | Convert struct timespec to CPU clock cycles. Details |
tcc_measurement_convert_clock_to_time_units() | Convert CPU clock cycles to a specified time unit. Details |
tcc_measurement_convert_time_units_to_clock() | Convert a time unit to CPU clock cycles. Details |
Functions operating with buffer | Use these functions in your monitoring application to access measurement results located in a shared memory ring buffer |
tcc_measurement_get() | Get the pointer to the measurement structure. Details |
tcc_measurement_buffer_get() | Read the data from the shared memory buffer. Details |
tcc_measurement_get_buffer_size_from_env() | Extract the buffer size from the environment variable. Details |
tcc_measurement_buffer_init() | Get the pointer to the ring buffer where the measurements are located. Details |
tcc_measurement_buffer_check() | See whether a measurement ring buffer exists in shared memory. Details |
Time Unit Types
Time Unit Type | Short Description |
|---|---|
TCC_TIME_UNIT | Time units for the measurement results output |
TCC_TU_CLK | Time in CPU clock cycles |
TCC_TU_NS | Time in nanoseconds |
TCC_TU_US | Time in microseconds |
TCC_TU_UNKNOWN | Unknown units. Returned by tcc_measurement_get_time_unit_from_env() if it fails to get a valid time unit from the environment. |