Developer Guide

  • 2021.2
  • 06/11/2021
  • Public
Contents

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.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.