About User APIs

The user APIs provided by the Intel® VTune™ Amplifier enable you to control collection, set marks during the execution of the specific code, and specify custom synchronization primitives implemented without standard system APIs.

User applications/modules linked to the static user API library do not have a runtime dependency on a dynamic library. Therefore, they can be executed without VTune Amplifier or other Parallel Studio tools.

To use the user APIs, do the following:

Include ittnotify.h, located at <install_dir>/include, in your code.
Insert __itt_* notifications in your code, in appropriate places.
Link to the libittnotify.a file located at <install_dir>/lib

The default Linux* OS installation directory is intel/vtune_amplifier_xe_2013.

Note

To be able to see user tasks in your results, enable the "Analyze user tasks" checkbox in analysis settings.

Unicode Support

All API functions that take parameters of type __itt_char follow the Windows OS unicode convention. If UNICODE is defined when compiling on a Windows OS, __itt_char is wchar_t, otherwise it is char. The actual function names are suffixed with A for the ASCII APIs and W for the unicode APIs. Both types of functions are defined in the DLL that implements the API.

Strings that are all ASCII characters are internally equivalent for both the unicode and the ASCII API versions. For example, the following strings are equivalent:

__itt_sync_createA( addr, "OpenMP Scheduler", "Critical Section", 0); 
__itt_sync_createW( addr, L"OpenMP Scheduler", L"Critical Section", 0);

Conditional Compilation

For best performance in the release version of your code, use conditional compilation to turn off annotations. Define the macro INTEL_NO_ITTNOTIFY_API before you include ittnotify.h during compilation to eliminate all __itt_* functions from your code.

You can also remove the static library from the linking stage by defining this macro.