API Reference

Intel® Trace Analyzer and Collector User and Reference Guide

Download PDF

ID 767272

Date 10/31/2024

Version 2021.10

Public

Visible to Intel only — GUID: GUID-F15273F0-D1AA-4871-9E81-89A75546EEA5

View Details

API Reference

The Intel® Trace Collector library provides the user with a number of functions that control the profiling library and record user-defined activities, define groups of processes, define performance counters and record their values. Header files with the necessary parameter, macro and function declarations are provided in the include directory: VT.h for ANSI C and C++ and VT.inc for Fortran 77 and Fortran 90. It is strongly recommended to include these header files if any Intel Trace Collector API functions are to be called.

You can also find the description of all available API functions in comments for VT.h and in the man pages on Linux* OS (man VT).

The Intel Trace Collector library is thread-safe in the sense that all of its API functions can be called by several threads at the same time. Some API functions can really be executed concurrently, others protect global data with POSIX* mutexes.

Concepts

This section uses the following concepts, essential for understanding the Intel Trace Collector API:

Symbol – function referred to by its name without the class name. For example: MPI_Send.
Activity – set of functions referred to by their class name. For example: MPI.
State – function referred to by its full name including the class name (combination of activity and symbol). For example: MPI:MPI_Send.
State change – event of entering or leaving a function (state).

For detailed description and examples of these concepts within the framework of the configuration functionality, see Filtering Trace Data.

General Macros and Errors

#define VT_VERSION

API version constant. It is incremented each time the API changes, even if the change does not break compatibility with the existing API. It can be used to determine at compile time how to call the API, like this:

#if VT_VERSION > 4000
   do something
#else
   do something different
#endif

VT_version() provides the same information at runtime.

To check whether the current revision of the API is still compatible with the revision of the API that the application was written against, compare against both VT_VERSION and VT_VERSION_COMPATIBILITY, as shown below.

#define VT_VERSION_COMPATIBILITY

Oldest API definition, which is still compatible with the current one.

It is set to the current version each time an API change can break programs written for the previous API. For example, a program written for VT_VERSION2090 will work with API 3000 if VT_VERSION_COMPATIBILITY remained at 2090. It may even work without modifications when VT_VERSION_COMPATIBILITY was increased to 3000, but this cannot be determined automatically and will require a source code review.

Here is a usage example:

#define APP_VT_VERSION 1000 // API version used by APP
#ifdef VT_VERSION_COMPATIBILITY > APP_EXPECTED_VT_VERSION
# error "VT.h is no longer compatible with APP's usage of the API"
#endif
#ifdef VT_VERSION < APP_EXPECTED_VT_VERSION
# error "VT.h is not recent enough for APP"
#endif

Suppose you instrumented your C source code for the API with VT_VERSION equal to 3100. Then you could add the following code fragment to detect incompatible changes in the API:

#include <VT.h>
#if VT_VERSION_COMPATIBILITY > 3100
# error ITC API is no longer compatible with our calls
#endif

Make sure to compare against a fixed number but not VT_VERSION, because VT_VERSION will always be greater or equal VT_VERSION_COMPATIBILITY.

To make the instrumentation work again after such a change, you can either just update the instrumentation to accommodate for the change or even provide different instrumentation that is chosen by the C preprocessor based on the value of VT_VERSION.

enum _VT_ErrorCode

Error codes returned by Intel Trace Collector API.

Enumerator	Description
`VT_OK`	OK
`VT_ERR_NOLICENSE`	No valid license found
`VT_ERR_NOTIMPLEMENTED`	Not implemented
`VT_ERR_NOTINITIALIZED`	Not initialized
`VT_ERR_BADREQUEST`	Invalid request type
`VT_ERR_BADSYMBOLID`	Wrong symbol ID
`VT_ERR_BADSCLID`	Wrong SCL ID
`VT_ERR_BADSCL`	Wrong SCL
`VT_ERR_BADFORMAT`	Wrong format
`VT_ERR_BADKIND`	Wrong kind found
`VT_ERR_NOMEMORY`	Could not get memory
`VT_ERR_BADFILE`	Error while handling file
`VT_ERR_FLUSH`	Error while flushing
`VT_ERR_BADARG`	Wrong argument
`VT_ERR_NOTHREADS`	No worker threads
`VT_ERR_BADINDEX`	Wrong thread index
`VT_ERR_COMM`	Communication error
`VT_ERR_INVT`	Intel® Trace Collector API called while inside an Intel® Trace Collector function
`VT_ERR_IGNORE`	Non-fatal error code

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Intel® Trace Analyzer and Collector User and Reference Guide

API Reference

Concepts

General Macros and Errors