Intel® Trace Collector API

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.

#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_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.

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

如需更全面地了解编译器优化,请参阅优化注意事项