The ITT (Instrumentation and Tracing Technology) API is used to annotate a user's program with additional information that can be used by correctness and performance tools. The user inserts calls in their program. Those calls generate information that is collected at runtime, and used by Intel® Threading Tools.
The following general concepts are used throughout the API.
Many API functions take character string arguments. On Windows, there are two versions of each such function. The function name is suffixed by W if Unicode support is enabled, and by A otherwise. Any API function that takes a character string argument adheres to this convention.
Domains provide a way to separate notification for different modules or libraries in a program.
Domains are specified by dotted character strings, eg
A mechanism (to be specified) is provided to enable and disable domains. By default, all domains are enabled.
Create a domain using some domain name: the URI naming style is recommended. Because the set of domains is expected to be static over the application's execution time, there is no mechanism to destroy a domain. Any domain can be accessed by any thread in the process, regardless of which thread created the domain. Creating a domain is thread-safe.
Named entities (frames, regions, tasks, and markers) communicate information about the program to the analysis tools. A named entity often refers to a section of program code, or to some set of logical concepts that the programmer wants to group together.
Named entities relate to the programmer's static view of the program. When the program actually executes, many instances of a given named entity may be created.
The API annotations denote instances of named entities. The actual named entities are displayed using the analysis tools. In other words, the named entities come into existence when instances are created.
Instances of named entities may have instance identifiers (IDs). Some API calls use instance identifiers to create relationships between different instances of named entities. Other API calls associate data with instances of named entities.
Some named entities must always have instance IDs. In particular, regions and frames always have IDs. Task and markers need IDs only if the ID is needed in another API call (such as adding a relation or metadata).
The lifetime of instance IDs is distinct from the lifetime of instances. This allows various relationships to be specified separatefrom the actual execution of instances. This flexibility comes at the expense of extra API calls.
The same ID may not be reused for different instances, unless a previous
__itt_id_destroy() call for that ID has been issued.
General behavior: application continues to run, but no profiling information is being collected
Pausing occurs not only for the current thread but for all process as well as spawned processes. It also possibly reduces runtime overhead. Pausing also varies by collector application:-
Does not analyze or report errors that involve memory access.
Other errors are reported as usual. Pausing data collection in Intel® Parallel Inspector and Intel® Inspector XE only pauses tracing and analyzing memory access. It does not pause tracing or analyzing threading APIs.
Does continue to record when new threads are started.
This is the subset of itt used for modeling by Intel® Parallel Advisor.
This API is called ONLY using
annotate.h, by `Annotation" macros the user places in their sources during the parallelism modeling steps.
task_end take the address of handle variables, which are writeable by the API.
Handles must be 0 initialized prior to the first call to begin, or may cause a run-time failure.
The handles are initialized in a multi-thread safe way by the API if the handle is 0.
The commonly expected idiom is one static handle to identify a site or task.
If a site or task of the same name has already been started during this collection, the same handle MAY be returned, but is not required to be - it is unspecified if data merging is done based on name.
These routines also take an instance variable.
Like the lexical instance, these must be 0 initialized.
Unlike the lexical instance, this is used to track a single dynamic instance.
The API used by the Intel® Parallel Advisor allows one to describe potential concurrency and related activities. //! User-added source annotations expand to calls to these procedures to enable modeling of a hypothetical concurrent execution serially.
site instances may be recursively nested with themselves.
site_end exits the most recently started but unended site for the current thread.
The handle passed to end may be used to validate structure
Instances of a site encountered on different threads concurrently are considered completely distinct.
If the site name for two different lexical sites match, it is unspecified whether they are treated as the same or different for data presentation.
The potential task is contained within the most closely enclosing dynamic site.
task_end exits the most recently started but unended task.
The handle passed to end may be used to validate structure.
It is unspecified if bad dynamic nesting is detected.
If it is, it should be encoded in the resulting data collection.
The collector should not fail due to construct nesting issues, nor attempt to directly indicate the problem.
@brief Description of a single entry in the line number information of a code region. @details A table of line number entries gives information about how the reported code region is mapped to source file. Intel(R) VTune(TM) Amplifier uses line number information to attribute the samples (virtual address) to a line number. \n It is acceptable to report different code addresses for the same source line: @code Offset LineNumber 1 2 12 4 15 2 18 1 21 30
Internal domain handle type.
Internal identifier type.
Internal string handle type.
@brief Description of an inline JIT-compiled method @details When you use the_iJIT_Method_Inline_Load structure to describe the JIT compiled method, use iJVM_EVENT_TYPE_METHOD_INLINE_LOAD_FINISHED as an event type to report it.
@brief Description of a JIT-compiled method @details When you use the iJIT_Method_Load structure to describe the JIT compiled method, use iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED as an event type to report it.
@brief Description of a JIT-compiled method @details When you use the iJIT_Method_Load_V2 structure to describe the JIT compiled method, use iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED_V2 as an event type to report it.
@brief Description of a JIT-compiled method @details The iJIT_Method_Load_V3 structure is the same as iJIT_Method_Load_V2 with a newly introduced 'arch' field that specifies architecture of the code region. When you use the iJIT_Method_Load_V3 structure to describe the JIT compiled method, use iJVM_EVENT_TYPE_METHOD_LOAD_FINISHED_V3 as an event type to report it.
@brief Description of a dynamic update of the content within JIT-compiled method @details The JIT engine may generate the methods that are updated at runtime partially by mixed (data + executable code) content. When you use the iJIT_Method_Update structure to describe the update of the content within a JIT-compiled method, use iJVM_EVENT_TYPE_METHOD_UPDATE_V2 as an event type to report it.
@brief Enumerator for the code architecture.
@brief Enumerator for the agent's mode
@cond exclude_from_documentation */ @brief Description of a segment type @details Use the segment type to specify a type of data supplied with the iJVM_EVENT_TYPE_METHOD_UPDATE_V2 event to be applied to a certain code trace.
@brief Enumerator for the types of notifications
Create a domain.
Record an event end occurrence.
Record an event occurrence.
Begin a frame instance.
End a frame instance.
Submits a frame instance.
Return timestamp corresponding to the current moment.
Create an instance of identifier.
Destroy an instance of identifier.
Begin of region instance.
End of region instance
Create a string handle.
Begin a task instance.
Begin a task instance.
End the current task instance.
Mark current thread as ignored from this point on, for the duration of its existence.
@brief Generates a new unique method ID.
@brief Returns the current mode of the agent.
@brief Reports infomation about JIT-compiled code to the agent.