Intel® Trace Analyzer and Collector User and Reference Guide

ID 767272
Date 8/08/2022
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

Defining and Recording Scopes

Scope is a user-defined region in the source code. In contrast to regions and functions, which are entered and left with VT_begin/VT_end() or VT_enter/VT_leave(), scope does not follow the stack based approach. It is possible to start scope a, then start scope b and stop a before b, that is they can overlap one another:

   |---- a -----|
      |------ b ----|

VT_scopedef

int VT_scopedef (const char * scopename, int classhandle, int scl1, int scl2, int * scopehandle)

Description

Define a new scope. A scope is identified by its name and class, like functions. The source code locations that can be associated with it are additional and optional attributes; they can be used to mark a static start and end of the scope in the source.

Like functions, scopename may consist of several components separated by a colon :.

Fortran

VTSCOPEDEF(scopename, classhandle, scl1, scl2, scopehandle, ierr)

Parameters

scopename the name of the scope
classhandle the class this scope belongs to (defined with VT_classdef())
scl1 any kind of SCL as defined with VT_scldef(), or VT_NOSCL
scl2 any kind of SCL as defined with VT_scldef(), or VT_NOSCL

Return values

scopehandle set to a numeric handle for the scope, needed by VT_scopebegin()

Returns error code

VT_scopebegin

int VT_scopebegin (int scopehandle, int scl, int * seqnr)

Description

Starts a new instance of the scope previously defined with VT_scopedef().

There can be more than one instance of a scope at the same time. In order to have the flexibility to stop an arbitrary instance, Intel® Trace Collector assigns an intermediate identifier to it which can (but does not have to) be passed to VT_scopeend(). If the application does not need this flexibility, then it can simply pass 0 to VT_scopeend().

Fortran

VTSCOPEBEGIN(scopehandle, scl, seqnr, ierr)

Parameters

scopehandle the scope as defined by VT_scopedef()
scl in contrast to the static SCL given in the scope definition this you can vary with each instance; pass VT_NOSCL if not needed

Return values

seqnr is set to a number that together with the handle identifies the scope instance; pointer may be NULL

Returns error code

VT_scopeend

int VT_scopeend (int scopehandle, int seqnr, int scl)

Description

Stops a scope that was previously started with VT_scopebegin().

Fortran

VTSCOPEEND(scopehandle, seqnr, scl)

Parameters

scopehandle identifies the scope that is to be terminated
seqnr 0 terminates the most recent scope with the given handle, passing the seqnr returned from VT_scopebegin() terminates exactly that instance
scl a dynamic SCL for leaving the scope

Did you find the information on this page useful?

Characters remaining:

Feedback Message