Download Intel® Trace Collector Reference Guide

Transcript
Intel® Trace Collector Reference Guide
8.4
Defining and Recording Functions or Regions
ITA can display and analyze general (properly nested) state changes, relating to subroutine calls,
entry/exit to/from code regions and other activities occurring in a process. ITA implements a two-level
model of states: a state is referred to by an activity name that identifies a group of states, and the
state (or symbol) name that references a particular state in that group. For instance, all MPI routines
are part of the activity MPI, and each one is identified by its routine name, for instance MPI_Send for
C and MPI_SEND for Fortran.
The ITC API allows the user to define arbitrary activities and symbols and to record entry and exit
to/from them. In order to reduce the instrumentation overhead, symbols are referred to by integer
handles that can be managed automatically (using the VT_funcdef() interface) or assigned by the user
(using the old VT_symdef() routine). All activities and symbols are defined by each process that uses
them, but it is no longer necessary to define them consistently on all processes (see UNIFY-SYMBOLS).
Optionally, information about source locations can be recorded for state enter and exit events by
passing a non-null location handle to the VT_enter()/VT_leave() or VT_beginl()/VT_endl() routines.
8.4.1 New Interface
To simplify the use of user-defined states, a new interface has been introduced for ITC. It manages
the symbol handles automatically, freeing the user from the task of assigning and keeping track of
symbol handles, and has a reduced number of arguments. Furthermore, the performance of the new
routines has been optimized, reducing the overhead of recording state changes.
To define a new symbol, first the respective activity needs to have been created by a call to the
VT_classdef() routine. A handle for that activity is returned, and with it the symbol can be defined by
calling VT_funcdef(). The returned symbol handle is passed f.i. to VT_enter() to record a state entry
event.
int VT_classdef (const char classname, int classhandle)
Allocates a handle for a class name.
The classname may consist of several components separated by a colon (:). Leading and trailing
colons are ignored. Several colons in a row are treated as just one separator.
Fortran
VTCLASSDEF( classname, classhandle, ierr )
Parameters:
classname name of the class
Return values:
classhandle the int it points to is set by ITC
Returns:
error code
int VT_funcdef (const char symname, int classhandle, int statehandle)
Allocates a handle for a state.
The symname may consist of several components separated by a colon (:). If that's the case, then
these become the parent class(es). Leading and trailing colons are ignored. Several colons in a row
are treated as just one separator.
This is a replacement for VT_symdef() which doesn't require the application to provide a unique
numeric handle.
Fortran
VTFUNCDEF( symname, classhandle, statehandle, ierr )
Parameters:
symname name of the symbol
classhandle handle for the class this symbol belongs to, created with VT_classdef(), or VT_NOCLASS,
Document number: 318119-002 68