State Changes

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

For more complete information about compiler optimizations, see our Optimization Notice.
Select sticky button color: 
Orange (only for download buttons)