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 |