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