• 2019 Update 3
  • 03/07/2019
  • Public Content
  • Download as PDF
Contents

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

Product and Performance Information

1

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and SSSE3 instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804