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

The following functions take a state handle defined with either the new or old interface. Handles defined with the old interface incur a higher overhead in these functions, because they need to be mapped to the real internal handles. Therefore it is better to use the new interface.
Intel® Trace Collector distinguishes between code regions (marked with
VT_begin()
/
VT_end()
) and functions (marked with
VT_enter()
/
VT_leave()
). The difference is only relevant when passing source code locations.
VT_begin
int VT_begin (int statehandle)
Description
Marks the beginning of a region with the name that was assigned to the symbol.
Regions should be used to subdivide a function into different parts or to mark the location where a function is called.
If automatic tracing of source code locations (PC tracing) is supported, then Intel® Trace Collector will log the location where
VT_begin()
is called as source code location for this region and the location where
VT_end()
is called as SCL for the next part of the calling symbol (which may be a function or another larger region).
If an SCL has been set with
VT_thisloc()
, then this SCL will be used even if PC tracing is supported.
The functions
VT_enter()
and
VT_leave()
have been added that can be used to mark the beginning and end of a function call within the function itself. The difference is that a manual source code location which is given to
VT_leave()
cannot specify where the function call took place, but rather where the function is left.
If PC tracing is enabled, then the
VT_leave
function stores the SCL where the instrumented function was called as SCL for the next part of the calling symbol. In other words, it skips the location where the function is left, which would be recorded if
VT_end()
were used instead.
VT_begin()
adds an entry to a stack which can be removed only with
VT_end()
.
Fortran
VTBEGIN(statehandle, ierr)
Parameters
statehandle
handle defined either with
VT_symdef()
or
VT_funcdef()
Return values
Returns error code
VT_beginl
int VT_beginl (int statehandle, int sclhandle)
Description
Shortcut for
VT_thisloc(sclhandle)
;
VT_begin(statehandle)
.
Fortran
VTBEGINL(statehandle, sclhandle, ierr)
VT_end
int VT_end (int statehandle)
Description
Marks the end of a region.
Has to match a
VT_begin()
. The parameter was used to check this, but this is no longer done to simplify instrumentation; now it is safe to pass a 0 instead of the original state handle.
Fortran
VTEND(statehandle, ierr)
Parameters
statehandle
obsolete, pass anything you want
Return values
Returns error code
VT_endl
int VT_endl (int statehandle, int sclhandle)
Description
Shortcut for
VT_thisloc(sclhandle)
;
VT_end(statehandle)
.
Fortran
VTENDL(statehandle, sclhandle, ierr)
VT_enter
int VT_enter (int statehandle, int sclhandle)
Description
Mark the beginning of a function.
Usage similar to
VT_beginl()
. See also
VT_begin()
.
Fortran
VTENTER(statehandle, sclhandle, ierr)
Parameters
statehandle
handle defined either with
VT_symdef()
or
VT_funcdef()
sclhandle
handle, defined by
VT_scldef
. Use
VT_NOSCL
if you don't have a specific value.
Return values
Returns error code
VT_leave
int VT_leave (int sclhandle)
Description
Mark the end of a function.
See also
VT_begin()
.
Fortran
VTLEAVE(sclhandle, ierr)
Parameters
sclhandle
handle, defined by
VT_scldef
. Currently ignored, but is meant to specify the location of exactly where the function was left in the future. Use
VT_NOSCL
if you don't have a specific value.
Return values
Returns error code
VT_enterstate
int VT_enterstate (const char * name, int * statehandle, int * truncated)
Description
Defines a state (when invoked the first time) and enters it.
It relies on the caller to provide persistent storage for state handles.
The corresponding call to leave the state again is the normal
VT_leave()
.
VT_leave()
must be called if and only if
VT_enterstate()
returns a zero return code.
static int bsend_handle, bsend_truncated; int bsend_retval; bsend_retval = VT_enterstate( "MPI:TRANSFER:BSEND", &bsend_handle, &bsend_truncated ); ... if( !bsend_retval) VT_leave( VT_NOSCL );
As demonstrated in this example, one or more colons
:
may be used to specify parent classes of the state, just as in
VT_funcdef()
and others.
But in contrast to those,
VT_enterstate()
also treats a slash
/
as special and uses it to log states at a varying degree of detail: depending on the value of
DETAILED-STATES
(
0
=
OFF
,
1
=
ON
,
2
,
3
...), only the part of the name before the first slash is used (
DETAILED-STATES 0
). For higher values of
DETAILED-STATES
more components of the name are used and the slashes in the part of the name which is used is treated like the class separator (
:
).
Examples
  1. "MPI:TRANSFER/SEND/COPY" + DETAILED-STATES 0: "MPI:TRANSFER"
  2. "MPI:TRANSFER/SEND/COPY" + DETAILED-STATES 1: "MPI:TRANSFER:SEND"
  3. "MPI:TRANSFER/SEND/COPY" + DETAILED-STATES >= 2: "MPI:TRANSFER:SEND:COPY"
  4. "/MPI:INTERNAL" + DETAILED-STATES 0: "" = not logged
  5. "/MPI:INTERNAL" + DETAILED-STATES 1: ":MPI:INTERNAL" = "MPI:INTERNAL"
If (and only if) the configuration option
DETAILED-STATES
causes the truncation of a certain state name, then entering that state is ignored if the process already is in that state.
Example of trace with
DETAILED-STATES 0
:
  1. enter
    "MPI:TRANSFER/WAIT"
    = enter
    "MPI:TRANSFER"
  2. enter
    "MPI:TRANSFER/COPY"
    =
    "MPI:TRANSFER"
    = ignored by Intel® Trace Collector, return code != 0
  3. leave
    "MPI:TRANSFER/COPY"
    = ignored by application
  4. enter
    "MPI:TRANSFER/WAIT"
    = recursive call; ignored too
  5. leave
    "MPI:TRANSFER/WAIT"
    = ignored by application
  6. leave
    "MPI:TRANSFER/WAIT"
    = leave
    "MPI:TRANSFER"
The same trace with
DETAILED-STATES 1
:
  1. enter
    "MPI:TRANSFER/WAIT"
    = enter
    "MPI:TRANSFER:WAIT"
  2. enter
    "MPI:TRANSFER/COPY"
    = enter
    "MPI:TRANSFER:COPY"
  3. leave
    "MPI:TRANSFER/COPY"
    = leave
    "MPI:TRANSFER:COPY"
  4. enter
    "MPI:TRANSFER/WAIT"
    = enter
    "MPI:TRANSFER:WAIT"
  5. leave
    "MPI:TRANSFER/WAIT"
    = leave
    "MPI:TRANSFER:WAIT"
  6. leave
    "MPI:TRANSFER/WAIT"
    = leave
    "MPI:TRANSFER:WAIT"
Fortran
VTENTERSTATE(name, statehandle, truncated, ierr)
Parameters
name
the name of the state, with colons and/or slashes as separators as described above
Return values
statehandle
must be initialized to zero before calling this function for the first time, then is set inside the function to the state handle which corresponds to the function which is logged
truncated
set when calling the function for the first time: zero if the full name is logged
Returns zero if state was entered and
VT_leave()
needs to be called
VT_wakeup
int VT_wakeup (void)
Description
Triggers the same additional actions as logging a function call, but without actually logging a call.
When Intel® Trace Collector logs a function entry or exit it might also execute other actions, like sampling and logging counter data. If a function runs for a very long time, then Intel® Trace Collector has no chance to execute these actions. To avoid that, the programmer can insert calls to this function into the source code of the long-running function.
Fortran
VTWAKEUP(ierr)
Return values
Returns 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