The Intel® Trace Collector library provides the user with a number of routines 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 routines are to be called.
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.
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_VERSION 2090 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
Of course, breaking compatibility that way will be avoided at all costs. Beware of comparing against a fixed number and 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.
Error codes returned by Intel® Trace Collector API.
No valid license found
Invalid request type
Wrong symbol ID
Wrong SCL ID
Wrong kind found
Could not get memory
Error while handling file
Error while flushing
No worker threads
Wrong thread index
Intel® Trace Collector API called while inside an Intel® Trace Collector function
Non-fatal error code