6.0 (revision 14673)
Files
Score-P User Adapter

Files

file  SCOREP_User.h
 This file contains the interface for the manual user instrumentation.
 
file  SCOREP_User_Types.h
 This file contains type definitions for manual user instrumentation.
 

Macros for region instrumentation

#define SCOREP_USER_OA_PHASE_BEGIN(handle, name, type)
 
#define SCOREP_USER_OA_PHASE_END(handle)   SCOREP_User_OaPhaseEnd( handle );
 
#define SCOREP_USER_REGION_BEGIN(handle, name, type)
 
#define SCOREP_USER_REGION_INIT(handle, name, type)
 
#define SCOREP_USER_REGION_END(handle)   SCOREP_User_RegionEnd( handle );
 
#define SCOREP_USER_REGION_ENTER(handle)   SCOREP_User_RegionEnter( handle );
 
#define SCOREP_USER_REGION_DEFINE(handle)   static SCOREP_User_RegionHandle handle = SCOREP_USER_INVALID_REGION;
 
#define SCOREP_USER_FUNC_DEFINE()
 
#define SCOREP_USER_FUNC_BEGIN()
 
#define SCOREP_USER_FUNC_END()   SCOREP_User_RegionEnd( scorep_user_func_handle );
 
#define SCOREP_USER_GLOBAL_REGION_DEFINE(handle)   SCOREP_User_RegionHandle handle = SCOREP_USER_INVALID_REGION;
 
#define SCOREP_USER_GLOBAL_REGION_EXTERNAL(handle)   extern SCOREP_User_RegionHandle handle;
 

Macros for parameter instrumentation

#define SCOREP_USER_PARAMETER_INT64(name, value)
 
#define SCOREP_USER_PARAMETER_UINT64(name, value)
 
#define SCOREP_USER_PARAMETER_STRING(name, value)
 

Macros to provide user metrics

#define SCOREP_USER_METRIC_LOCAL(metricHandle)
 
#define SCOREP_USER_METRIC_GLOBAL(metricHandle)
 
#define SCOREP_USER_METRIC_EXTERNAL(metricHandle)   extern SCOREP_SamplingSetHandle metricHandle;
 
#define SCOREP_USER_METRIC_INIT(metricHandle, name, unit, type, context)   SCOREP_User_InitMetric( &metricHandle, name, unit, type, context );
 
#define SCOREP_USER_METRIC_INT64(metricHandle, value)
 
#define SCOREP_USER_METRIC_UINT64(metricHandle, value)
 
#define SCOREP_USER_METRIC_DOUBLE(metricHandle, value)
 

Macros for creation of user topologies

#define SCOREP_USER_CARTESIAN_TOPOLOGY_CREATE(userTopology, name, nDims)
 
#define SCOREP_USER_CARTESIAN_TOPOLOGY_ADD_DIM(userTopology, size, periodic, name)   SCOREP_User_CartTopologyAddDim( userTopology, size, periodic, name );
 
#define SCOREP_USER_CARTESIAN_TOPOLOGY_INIT(userTopology)   SCOREP_User_CartTopologyInit( userTopology );
 
#define SCOREP_USER_CARTESIAN_TOPOLOGY_SET_COORDS(userTopology, nDims, ...)   SCOREP_User_CartTopologySetCoords( userTopology, nDims, __VA_ARGS__ );
 
#define SCOREP_USER_CARTESIAN_TOPOLOGY_DEFINE(userTopology)
 

C++ specific macros for region instrumentation

#define SCOREP_USER_REGION(name, type)
 

Macros for measurement control

#define SCOREP_RECORDING_ON()   SCOREP_User_EnableRecording();
 
#define SCOREP_RECORDING_OFF()   SCOREP_User_DisableRecording();
 
#define SCOREP_RECORDING_IS_ON()   SCOREP_User_RecordingEnabled()
 

Region types

#define SCOREP_USER_REGION_TYPE_COMMON   0
 
#define SCOREP_USER_REGION_TYPE_FUNCTION   1
 
#define SCOREP_USER_REGION_TYPE_LOOP   2
 
#define SCOREP_USER_REGION_TYPE_DYNAMIC   4
 
#define SCOREP_USER_REGION_TYPE_PHASE   8
 

Metric types

#define SCOREP_USER_METRIC_TYPE_INT64   0
 
#define SCOREP_USER_METRIC_TYPE_UINT64   1
 
#define SCOREP_USER_METRIC_TYPE_DOUBLE   2
 

Metric contexts

#define SCOREP_USER_METRIC_CONTEXT_GLOBAL   0
 
#define SCOREP_USER_METRIC_CONTEXT_CALLPATH   1
 

Detailed Description

The user adapter provides a set of macros for user manual instrumentation. The macros are inserted in the source code and call functions of the Score-P runtime system. The user should avoid calling the Score-P runtime functions directly.

For every macro, two definitions are provided: The first one inserts calls to the Score-P runtime system, the second definitions resolve to nothing. Which implementation is used, depends on the definition of SCOREP_USER_ENABLE. If SCOREP_USER_ENABLE is defined, the macros resolve to calls to the Score-P runtime system. If SCOREP_USER_ENABLE is undefined, the user instrumentation is removed by the preprocessor. This flag SCOREP_USER_ENABLE should be set through the instrumentation wrapper tool automatically if user manual instrumentation is enabled.

Every source file which is instrumented must include a header file with the Score-P user instrumentation header. For C/C++ programs, the header file is 'scorep/SCOREP_User.h', for Fortran files, 'scorep/SCOREP_User.inc' must be included. Because the Fortran compilers cannot expand macros, the Fortran source code must be preprocessed by a C or C++ preprocessor, to include the headers and expand the macros. Which Fortran files are passed to the preprocessor depends on the suffix. Usually, suffixes .f and .f90 are not preprocessed, .F and .F90 files are preprocessed. However, this may depend on the used compiler.

Macro Definition Documentation

#define SCOREP_RECORDING_IS_ON ( )    SCOREP_User_RecordingEnabled()

In C/C++ it behaves like a function call which returns whether recording is enabled or not. It returns false if the recording of events is disabled, else it returns true.

C/C++ example:

1 void foo()
2 {
3  if ( SCOREP_RECORDING_IS_ON() )
4  {
5  // do something
6  }
7 }

In Fortran, this macro has a different syntax. An integer variable must be specified as parameter, which is set to non-zero if recording is enabled, else the value is set to zero.

Fortran example:

1 subroutine foo
2  integer :: l
3 
4  SCOREP_RECORDING_IS_ON( l )
5  if (l .eq. 0) then
6  ! do something
7  end if
8 
9 end subroutine foo
#define SCOREP_RECORDING_OFF ( )    SCOREP_User_DisableRecording();

Disables recording of events. If already disabled, this command has no effect. The control is not restricted to events from the user adapter, but disables the recording of all events.

C/C++ example:

1 void foo()
2 {
3  SCOREP_RECORDING_OFF()
4 
5  // do something
6 
7  SCOREP_RECORDING_ON()
8 }

Fortran example:

1 subroutine foo
2 
3  SCOREP_RECORDING_OFF()
4 ! do something
5  SCOREP_RECORDING_ON()
6 
7 end subroutine foo
#define SCOREP_RECORDING_ON ( )    SCOREP_User_EnableRecording();

Enables recording of events. If already enabled, this command has no effect. The control is not restricted to events from the user adapter, but enables the recording of all events.

C/C++ example:

1 void foo()
2 {
3  SCOREP_RECORDING_OFF()
4 
5  // do something
6 
7  SCOREP_RECORDING_ON()
8 }

Fortran example:

1 subroutine foo
2 
3  SCOREP_RECORDING_OFF()
4 ! do something
5  SCOREP_RECORDING_ON()
6 
7 end subroutine foo
#define SCOREP_USER_CARTESIAN_TOPOLOGY_ADD_DIM (   userTopology,
  size,
  periodic,
  name 
)    SCOREP_User_CartTopologyAddDim( userTopology, size, periodic, name );

This statement defines a dimension for the topology of the given handle.

Parameters
userTopologyThe handle that identifies the respective topology.
sizeNumber of elements in the dimension.
periodicThe periodicity of the dimension; Bool values allowed.
nameThe name of the dimension.
#define SCOREP_USER_CARTESIAN_TOPOLOGY_CREATE (   userTopology,
  name,
  nDims 
)
Value:
SCOREP_User_CartesianTopologyHandle userTopology = SCOREP_USER_INVALID_CARTESIAN_TOPOLOGY; \
SCOREP_User_CartTopologyCreate( &userTopology, name, nDims );
struct SCOREP_User_Topology * SCOREP_User_CartesianTopologyHandle
Definition: SCOREP_User_Types.h:88

This statement creates an user topology by the given name and initializes it based on name and number of expected dimensions.

Parameters
userTopologyThe handle that identifies the topology in subsequent calls.
nameThe unique name for the user topology.
nDimsThe number of dimensions.
Note
The name of each user topology has to be unique to appear as a distinct topology!
#define SCOREP_USER_CARTESIAN_TOPOLOGY_DEFINE (   userTopology)

This statement defines an user topology in the Fortran case. As a variable definition it has to be placed in the variable section.

Parameters
userTopologyThe handle that identifies the topology in subsequent calls.
#define SCOREP_USER_CARTESIAN_TOPOLOGY_INIT (   userTopology)    SCOREP_User_CartTopologyInit( userTopology );

Initialize the topology after all dimensions are set.

Parameters
userTopologyThe handle that identifies the respective topology.
#define SCOREP_USER_CARTESIAN_TOPOLOGY_SET_COORDS (   userTopology,
  nDims,
  ... 
)    SCOREP_User_CartTopologySetCoords( userTopology, nDims, __VA_ARGS__ );

This statement defines the coordinates for the topology of the given handle. This call has to be done on the thread/process that should be associated with this set of coordinates, as the mapping will be done implicitly. The number of coordinate parameters in the variable array has to be the same as the number of dimensions for the topology.

Parameters
userTopologyThe handle that identifies the respective topology.
nDimsThe number of dimensions, which is the number of coordinate parameters in C and the length of the coordinate array in Fortran.
variablearray Coordinate information for each of the nDims dimensions.

The order of macro execution is important. All dimensions have to be added before the init call; the coordinates have to be added after the init call.

Note
For MPI programs, all calls to SCOREP_USER_CARTESIAN_TOPOLOGY_SET_COORDS have to happen after MPI_Init!

C/C++ Example:

1 SCOREP_USER_CARTESIAN_TOPOLOGY_CREATE ( mytopo, "This is a new user topology", 2 );
2 SCOREP_USER_CARTESIAN_TOPOLOGY_ADD_DIM ( mytopo, 2 , 1, "dim1_2" );
3 SCOREP_USER_CARTESIAN_TOPOLOGY_ADD_DIM ( mytopo, ( numprocs + 1 ) / 2 , 1, "dim2_4" );
4 SCOREP_USER_CARTESIAN_TOPOLOGY_INIT ( mytopo );
5 SCOREP_USER_CARTESIAN_TOPOLOGY_SET_COORDS ( mytopo, 2, rank % 2, rank / 2 );

Note that SCOREP_USER_CARTESIAN_TOPOLOGY_SET_COORDS takes the location into account on which it is executed. To create coordinates on a thread level, use this macro inside an OpenMP parallel region or in a POSIX thread's start_routine. It is possible to set all coordinates in a serial part of your program though.

Note, for Fortran the CREATE macro is split in a define and create step to allow its placement in the variable section.

Fortran example:

1 program main
2  integer :: numprocs
3  SCOREP_USER_CARTESIAN_TOPOLOGY_DEFINE( mytopo )
4  integer, dimension(2) :: coords
5 
6  !...
7 
8  SCOREP_USER_CARTESIAN_TOPOLOGY_CREATE( mytopo, "This is a new user topology", 2 )
9  SCOREP_USER_CARTESIAN_TOPOLOGY_ADD_DIM( mytopo, 2, 1, "dim1_2" )
10  SCOREP_USER_CARTESIAN_TOPOLOGY_ADD_DIM( mytopo, ( numprocs + 1 ) / 2 , 1, "dim2_4" )
11  SCOREP_USER_CARTESIAN_TOPOLOGY_INIT ( mytopo );
12  coords = (/ MOD( rank, 2 ), rank / 2 /)
13  SCOREP_USER_CARTESIAN_TOPOLOGY_SET_COORDS ( mytopo, 2, coords )
14 end program main
#define SCOREP_USER_FUNC_BEGIN ( )
Value:
static SCOREP_User_RegionHandle \
scorep_user_func_handle = SCOREP_USER_INVALID_REGION; \
SCOREP_User_RegionBegin( &scorep_user_func_handle, &SCOREP_User_LastFileName, \
&SCOREP_User_LastFileHandle, SCOREP_USER_FUNCTION_NAME, \
SCOREP_USER_REGION_TYPE_FUNCTION, __FILE__, __LINE__ );
#define SCOREP_USER_REGION_TYPE_FUNCTION
Definition: SCOREP_User_Types.h:115
#define SCOREP_USER_INVALID_REGION
Definition: SCOREP_User_Types.h:57

This macro marks the start of a function. It should be inserted at the beginning of the instrumented function. It will generate a region, with the function name.

The C/C++ version of this command takes no arguments. It contains a variable declaration and a function call. Compilers that require a strict separation between declaration block and execution block may fail if this macro is used.

In Fortran one argument is required for the name of the function. Furthermore, the handle must be declared explicitly in Fortran.

Parameters
nameFortan only: A string containing the name of the function.

C/C++ example:

1 void myfunc()
2 {
3  // declarations
4 
5  SCOREP_USER_FUNC_BEGIN()
6 
7  // do something
8 
9  SCOREP_USER_FUNC_END()
10 }

Fortran example:

1 subroutine myfunc
2  SCOREP_USER_FUNC_DEFINE()
3  ! more declarations
4 
5  SCOREP_USER_FUNC_BEGIN( "myfunc" )
6  ! do something
7  SCOREP_USER_FUNC_END()
8 
9 end subroutine myfunc

Note that in Fortran the function need to be declared using SCOREP_USER_FUNC_DEFINE before.

#define SCOREP_USER_FUNC_DEFINE ( )

This macro is for Fortran only. It declares the handle for a function. Every function handle must be declared in the declaration part of the subroutine or function if the SCOREP_USER_FUNC_BEGIN and SCOREP_USER_FUNC_END macros are used.

Example:

1 subroutine myfunc
2  SCOREP_USER_FUNC_DEFINE()
3  ! more declarations
4 
5  SCOREP_USER_FUNC_BEGIN( "myfunc" )
6  ! do something
7  SCOREP_USER_FUNC_END()
8 
9 end subroutine myfunc

Note that in Fortran the function need to be declared using SCOREP_USER_FUNC_DEFINE before.

#define SCOREP_USER_FUNC_END ( )    SCOREP_User_RegionEnd( scorep_user_func_handle );

This macro marks the end of a function. It should be inserted at every return point of the instrumented function.

C/C++ example:

1 void myfunc()
2 {
3  // declarations
4 
5  SCOREP_USER_FUNC_BEGIN()
6 
7  // do something
8  if ( some_expression )
9  {
10  SCOREP_USER_FUNC_END()
11  return;
12  }
13 
14  SCOREP_USER_FUNC_END()
15 }

Fortran example:

1 subroutine myfunc
2  SCOREP_USER_FUNC_DEFINE()
3  ! more declarations
4 
5  SCOREP_USER_FUNC_BEGIN( "myfunc" )
6  ! do something
7  SCOREP_USER_FUNC_END()
8 
9 end subroutine myfunc

Note that in Fortran the function need to be declared using SCOREP_USER_FUNC_DEFINE before.

#define SCOREP_USER_GLOBAL_REGION_DEFINE (   handle)    SCOREP_User_RegionHandle handle = SCOREP_USER_INVALID_REGION;

This macro defines a region handle in a global scope for usage in more than one code block. If a region is used in multiple source files, only one of them must contain the definition using SCOREP_USER_GLOBAL_REGION_DEFINE. All other files, in which the global handle is accessed, must only declare the global handle with SCOREP_USER_GLOBAL_REGION_EXTERNAL( handle ). It is possible to use the global handle in more than one code-block. However, code-blocks that share a handle, are handled as they were all the same region. Enter and exit events for global regions are created with SCOREP_USER_REGION_BEGIN and SCOREP_USER_REGION_END, respectively. Its name and type is determined at the first enter event and is not changed on later events, even if other code blocks contains a different name or type in their SCOREP_USER_REGION_BEGIN statement.

This macro is not available in Fortran.

Parameters
handleA unique name for the handle must be provided. This handle is declared in the macro. This handle is used in the SCOREP_USER_REGION_BEGIN and SCOREP_USER_REGION_END statements to specify which region is started, or ended. If you are using a Fortran version which has a limited length of code lines, the length of the handle parameter must be at most 4 characters, else the declaration line exceeds the allowed length.

C/C++ example:

1 // In File1:
2 SCOREP_USER_GLOBAL_REGION_DEFINE( my_global_handle )
3 
4 void myfunc()
5 {
6  SCOREP_USER_REGION_BEGIN( my_global_handle, "my_global", SCOREP_USER_REGION_TYPE_PHASE )
7 
8  // do something
9 
10  SCOREP_USER_REGION_END( my_global_handle )
11 }
1 // In File2:
2 SCOREP_USER_GLOBAL_EXTERNAL( my_global_handle )
3 
4 void foo()
5 {
6  SCOREP_USER_REGION_BEGIN( my_global_handle, "my_global", SCOREP_USER_REGION_TYPE_PHASE )
7 
8  // do something
9 
10  SCOREP_USER_REGION_END( my_global_handle )
11 }
#define SCOREP_USER_GLOBAL_REGION_EXTERNAL (   handle)    extern SCOREP_User_RegionHandle handle;

This macro declares an externally defined global region. If a region is used in multiple source files, only one of them must contain the definition using SCOREP_USER_GLOBAL_REGION_DEFINE. All other files, in which the global handle is accessed, must only declare the global handle with SCOREP_USER_GLOBAL_REGION_EXTERNAL( handle ). It is possible to use the global handle in more than one code-block. However, code-blocks that share a handle, are handled as they were all the same region. Enter and exit events for global regions are created with SCOREP_USER_REGION_BEGIN and SCOREP_USER_REGION_END, respectively. Its name and type is determined at the first enter event and is not changed on later events, even if other code blocks contains a different name or type in their SCOREP_USER_REGION_BEGIN statement.

This macro is not available in Fortran

Parameters
handleA name for a variable must be provided. This variable name must be the same like for the corresponding SCOREP_USER_GLOBAL_REGION_DEFINE statement. The handle is used in the SCOREP_USER_REGION_BEGIN and SCOREP_USER_REGION_END statements to specify which region is started, or ended.

C/C++ example:

1 // In File 1
2 SCOREP_USER_GLOBAL_REGION_DEFINE( my_global_handle )
3 
4 void myfunc()
5 {
6  SCOREP_USER_REGION_BEGIN( my_global_handle, "my_global", SCOREP_USER_REGION_TYPE_PHASE )
7 
8  // do something
9 
10  SCOREP_USER_REGION_END( my_global_handle )
11 }
1 // In File 2
2 SCOREP_USER_GLOBAL_EXTERNAL( my_global_handle )
3 
4 void foo()
5 {
6  SCOREP_USER_REGION_BEGIN( my_global_handle, "my_global", SCOREP_USER_REGION_TYPE_PHASE )
7 
8  // do something
9 
10  SCOREP_USER_REGION_END( my_global_handle )
11 }
#define SCOREP_USER_METRIC_CONTEXT_CALLPATH   1

Indicates that a user counter is is measured for every callpath.

#define SCOREP_USER_METRIC_CONTEXT_GLOBAL   0

Indicates that a user counter is is measured for the global context.

#define SCOREP_USER_METRIC_DOUBLE (   metricHandle,
  value 
)
Value:
SCOREP_User_TriggerMetricDouble( \
metricHandle, value );

Triggers a new event for a user counter of a double precision floating point data type. Each user metric must be declared with SCOREP_USER_COUNTER_LOCAL, SCOREP_USER_COUNTER_GLOBAL, or SCOREP_USER_COUNTER_EXTERNAL and initialized with SCOREP_USER_COUNTER_INIT before it is triggered for the first time.

Parameters
metricHandleThe handle of the metric for which a value is given in this statement.
valueThe value of the counter. It must be possible for implicit casts to cast it to a double.

Example:

1 SCOREP_USER_METRIC_LOCAL( my_local_metric )
2 
3 int main()
4 {
5  SCOREP_USER_METRIC_INIT( my_local_metric, "My Metric", "seconds", \
6  SCOREP_USER_METRIC_TYPE_DOUBLE, \
7  SCOREP_USER_METRIC_CONTEXT_GLOBAL )
8  // do something
9 }
10 
11 void foo()
12 {
13  double my_double = get_some_double_value();
14  SCOREP_USER_METRIC_DOUBLE( my_local_metric, my_double )
15 }

Fortran example:

1 program myProg
2  SCOREP_USER_METRIC_LOCAL( my_local_metric )
3  real (kind=selected_int_kind(14,200)):: my_real = 24.5
4 ! more declarations
5 
6 
7  SCOREP_USER_METRIC_INIT( my_local_metric, "My Metric", "seconds", &
8  SCOREP_USER_METRIC_TYPE_DOUBLE, &
9  SCOREP_USER_METRIC_CONTEXT_GLOBAL )
10 
11 ! do something
12 
13  SCOREP_USER_METRIC_DOUBLE( my_local_metric, my_real )
14 end program myProg
#define SCOREP_USER_METRIC_EXTERNAL (   metricHandle)    extern SCOREP_SamplingSetHandle metricHandle;

Declares an externally defined handle for a user metric. Every global metric must be declared only in one file using SCOREP_USER_METRIC_GLOBAL. All other files in which this handle is accessed must declare it with SCOREP_USER_METRIC_EXTERNAL.

This macro is not available in Fortran.

Parameters
metricHandleThe variable name of the handle. it must be the same name as used in the corresponding SCOREP_USER_METRIC_GLOBAL statement.

C/C++ example:

1 // In File 1
2 SCOREP_USER_METRIC_GLOBAL( my_global_metric )
3 
4 int main()
5 {
6  SCOREP_USER_METRIC_INIT( my_global_metric, "My Global Metric", "seconds", \
7  SCOREP_USER_METRIC_TYPE_UINT64, \
8  SCOREP_USER_METRIC_CONTEXT_GLOBAL )
9  // do something
10 }
11 
12 void foo()
13 {
14  uint64 my_int = get_some_int_value();
15  SCOREP_USER_METRIC_UINT64( my_global_metric, my_int )
16 }
1 // In File 2
2 SCOREP_USER_METRIC_EXTERNAL( my_global_metric )
3 
4 void bar()
5 {
6  uint64 my_int = get_some_int_value();
7  SCOREP_USER_METRIC_UINT64( my_global_metric, my_int )
8 }
#define SCOREP_USER_METRIC_GLOBAL (   metricHandle)
Value:
SCOREP_AnyHandle SCOREP_SamplingSetHandle
Definition: SCOREP_PublicTypes.h:123
#define SCOREP_INVALID_SAMPLING_SET
Definition: SCOREP_PublicTypes.h:128

Declares a handle for a user metric as a global variable. It must be used if a metric handle is accessed in more than one file. Every global metric must be declared only in one file using SCOREP_USER_METRIC_GLOBAL. All other files in which this handle is accessed must declare it with SCOREP_USER_METRIC_EXTERNAL.

This macro is not available in Fortran.

Parameters
metricHandleThe variable name for the handle. If you are using a Fortran version which has a limited length of code lines, the length of the handle parameter must be at most 4 characters, else the declaration line exceeds the allowed length.

C/C++ example:

1 // In File 1
2 SCOREP_USER_METRIC_GLOBAL( my_global_metric )
3 
4 int main()
5 {
6  SCOREP_USER_METRIC_INIT( my_global_metric, "My Global Metric", "seconds", \
7  SCOREP_USER_METRIC_TYPE_UINT64, \
8  SCOREP_USER_METRIC_CONTEXT_GLOBAL )
9  // do something
10 }
11 
12 void foo()
13 {
14  uint64 my_int = get_some_int_value();
15  SCOREP_USER_METRIC_UINT64( my_global_metric, my_int )
16 }
1 // In File 2
2 SCOREP_USER_METRIC_EXTERNAL( my_global_metric )
3 
4 void bar()
5 {
6  uint64 my_int = get_some_int_value();
7  SCOREP_USER_METRIC_UINT64( my_global_metric, my_int )
8 }
#define SCOREP_USER_METRIC_INIT (   metricHandle,
  name,
  unit,
  type,
  context 
)    SCOREP_User_InitMetric( &metricHandle, name, unit, type, context );

Initializes a new user counter. Each counter must be initialized before it is triggered the first time. The handle must be declared using SCOREP_USER_METRIC_LOCAL, SCOREP_USER_METRIC_GLOBAL, or SCOREP_USER_METRIC_EXTERNAL.

Parameters
metricHandleProvides a variable name of the variable to store the metric handle. The variable is declared by the macro.
nameA string containing a unique name for the counter.
unitA string containing a the unit of the data.
typeSpecifies the data type of the counter. It must be one of the following: SCOREP_USER_METRIC_TYPE_INT64, SCOREP_USER_METRIC_TYPE_UINT64, SCOREP_USER_METRIC_TYPE_DOUBLE. In Fortran is SCOREP_USER_METRIC_TYPE_UINT64 not available.
contextSpecifies the context for which the counter is measured. IT must be one of the following: SCOREP_USER_METRIC_CONTEXT_GLOBAL, or SCOREP_USER_METRIC_CONTEXT_CALLPATH.

C/C++ example:

1 SCOREP_USER_METRIC_LOCAL( my_local_metric )
2 
3 int main()
4 {
5  SCOREP_USER_METRIC_INIT( my_local_metric, "My Metric", "seconds", \
6  SCOREP_USER_METRIC_TYPE_UINT64, \
7  SCOREP_USER_METRIC_CONTEXT_GLOBAL )
8  // do something
9 }
10 
11 void foo()
12 {
13  uint64 my_int = get_some_int_value();
14  SCOREP_USER_METRIC_UINT64( my_local_metric, my_int )
15 }

Fortran example:

1 program myProg
2  SCOREP_USER_METRIC_LOCAL( my_local_metric )
3  integer (kind=selected_int_kind(8)):: my_int = 19
4 ! more declarations
5 
6 
7  SCOREP_USER_METRIC_INIT( my_local_metric, "My Metric", "seconds", &
8  SCOREP_USER_METRIC_TYPE_INT64, &
9  SCOREP_USER_METRIC_CONTEXT_GLOBAL )
10 
11 ! do something
12 
13  SCOREP_USER_METRIC_INT64( my_local_metric, my_int )
14 end program myProg
#define SCOREP_USER_METRIC_INT64 (   metricHandle,
  value 
)
Value:
SCOREP_User_TriggerMetricInt64( \
metricHandle, value );

Triggers a new event for a user counter of a 64 bit integer data type. Each user metric must be declared with SCOREP_USER_COUNTER_LOCAL, SCOREP_USER_COUNTER_GLOBAL, or SCOREP_USER_COUNTER_EXTERNAL and initialized with SCOREP_USER_COUNTER_INIT before it is triggered for the first time.

Parameters
metricHandleThe handle of the metric for which a value is given in this statement.
valueThe value of the counter. It must be possible for implicit casts to cast it to a 64 bit integer.

C/C++ example:

1 SCOREP_USER_METRIC_LOCAL( my_local_metric )
2 
3 int main()
4 {
5  SCOREP_USER_METRIC_INIT( my_local_metric, "My Metric", "seconds", \
6  SCOREP_USER_METRIC_TYPE_INT64, \
7  SCOREP_USER_METRIC_CONTEXT_GLOBAL )
8  // do something
9 }
10 
11 void foo()
12 {
13  int64 my_int = get_some_int_value();
14  SCOREP_USER_METRIC_INT64( my_local_metric, my_int )
15 }

Fortran example:

1 program myProg
2  SCOREP_USER_METRIC_LOCAL( my_local_metric )
3  integer (kind=selected_int_kind(8)):: my_int = 19
4 ! more declarations
5 
6 
7  SCOREP_USER_METRIC_INIT( my_local_metric, "My Metric", "seconds", &
8  SCOREP_USER_METRIC_TYPE_INT64, &
9  SCOREP_USER_METRIC_CONTEXT_GLOBAL )
10 
11 ! do something
12 
13  SCOREP_USER_METRIC_INT64( my_local_metric, my_int )
14 end program myProg
#define SCOREP_USER_METRIC_LOCAL (   metricHandle)
Value:
static SCOREP_SamplingSetHandle \
metricHandle \
#define SCOREP_INVALID_SAMPLING_SET
Definition: SCOREP_PublicTypes.h:128

Declares a handle for a user metric. It defines a variable which must be in scope at all places where the metric is used. If it is used in more than one place it need to be a global definition.

Parameters
metricHandleThe name of the variable which will be declared for storing the metric handle.

C/C++ example:

1 SCOREP_USER_METRIC_LOCAL( my_local_metric )
2 
3 int main()
4 {
5  SCOREP_USER_METRIC_INIT( my_local_metric, "My Metric", "seconds", \
6  SCOREP_USER_METRIC_TYPE_UINT64, \
7  SCOREP_USER_METRIC_CONTEXT_GLOBAL )
8  // do something
9 }
10 
11 void foo()
12 {
13  uint64 my_int = get_some_int_value();
14  SCOREP_USER_METRIC_UINT64( my_local_metric, my_int )
15 }

Fortran example:

1 program myProg
2  SCOREP_USER_METRIC_LOCAL( my_local_metric )
3  integer (kind=selected_int_kind(8)):: my_int = 19
4 ! more declarations
5 
6 
7  SCOREP_USER_METRIC_INIT( my_local_metric, "My Metric", "seconds", &
8  SCOREP_USER_METRIC_TYPE_INT64, &
9  SCOREP_USER_METRIC_CONTEXT_GLOBAL )
10 
11 ! do something
12 
13  SCOREP_USER_METRIC_INT64( my_local_metric, my_int )
14 end program myProg
#define SCOREP_USER_METRIC_TYPE_DOUBLE   2

Indicates that a user counter is of data type double.

#define SCOREP_USER_METRIC_TYPE_INT64   0

Indicates that a user counter is of data type signed 64 bit integer.

#define SCOREP_USER_METRIC_TYPE_UINT64   1

Indicates that a user counter is of data type unsigned 64 bit integer.

#define SCOREP_USER_METRIC_UINT64 (   metricHandle,
  value 
)
Value:
SCOREP_User_TriggerMetricUint64( \
metricHandle, value );

Triggers a new event for a user counter of a 64 bit unsigned integer data type. Each user metric must be declared with SCOREP_USER_COUNTER_LOCAL, SCOREP_USER_COUNTER_GLOBAL, or SCOREP_USER_COUNTER_EXTERNAL and initialized with SCOREP_USER_COUNTER_INIT before it is triggered for the first time.

In Fortran is the unsigned integer type metric not available.

Parameters
metricHandleThe handle of the metric for which a value is given in this statement.
valueThe value of the counter. It must be possible for implicit casts to cast it to a 64 bit unsigned integer.

Example:

1 SCOREP_USER_METRIC_LOCAL( my_local_metric )
2 
3 int main()
4 {
5  SCOREP_USER_METRIC_INIT( my_local_metric, "My Metric", "seconds", \
6  SCOREP_USER_METRIC_TYPE_UINT64, \
7  SCOREP_USER_METRIC_CONTEXT_GLOBAL )
8  // do something
9 }
10 
11 void foo()
12 {
13  uint64 my_int = get_some_int_value();
14  SCOREP_USER_METRIC_UINT64( my_local_metric, my_int )
15 }
#define SCOREP_USER_OA_PHASE_BEGIN (   handle,
  name,
  type 
)
Value:
SCOREP_User_OaPhaseBegin( \
&handle, &SCOREP_User_LastFileName, &SCOREP_User_LastFileHandle, name, \
type, __FILE__, __LINE__ );

This macro marks the start of a user defined Online Access phase region. The SCOREP_USER_OA_PHASE_BEGIN and SCOREP_USER_OA_PHASE_END must be correctly nested and be a potential global synchronization points, also it is recommended to mark the body of the application's main loop as a Online Access phase in order to utilize main loop iterations for iterative online analysis.

Parameters
handleThe handle of the associated user region, which will become a root of the profile call-tree. This handle must be declared using SCOREP_USER_REGION_DEFINE or SCOREP_USER_GLOBAL_REGION_DEFINE before.
nameA string containing the name of the new region. The name should be unique.
typeSpecifies the type of the region. Possible values are SCOREP_USER_REGION_TYPE_COMMON, SCOREP_USER_REGION_TYPE_FUNCTION, SCOREP_USER_REGION_TYPE_LOOP, SCOREP_USER_REGION_TYPE_DYNAMIC, SCOREP_USER_REGION_TYPE_PHASE, or a combination of them.

C/C++ example:

1 void main()
2 {
3  SCOREP_USER_REGION_DEFINE( my_region_handle )
4 
5  // application initialization
6 
7  for ( ) // main loop of the application
8  {
9  SCOREP_USER_OA_PHASE_BEGIN( my_region_handle, "main loop",SCOREP_USER_REGION_TYPE_COMMON )
10 
11  // do something
12 
13  SCOREP_USER_OA_PHASE_END( my_region_handle )
14  }
15 
16  // application finalization
17 }

Fortran example:

1 program myProg
2  SCOREP_USER_REGION_DEFINE( my_region_handle )
3 
4  ! applications initialization
5 
6  ! main loop of the application
7  do ...
8 
9  SCOREP_USER_OA_PHASE_BEGIN( my_region_handle, "main loop",SCOREP_USER_REGION_TYPE_COMMON )
10 
11  ! do something
12 
13  SCOREP_USER_OA_PHASE_END( my_region_handle )
14 
15  enddo
16 
17  !application finalization
18 
19 end program myProg
#define SCOREP_USER_OA_PHASE_END (   handle)    SCOREP_User_OaPhaseEnd( handle );

This macro marks the end of a user defined Online Access phase region. The SCOREP_USER_OA_PHASE_BEGIN and SCOREP_USER_OA_PHASE_END must be correctly nested and be a potential global synchronization points, also it is recommended to mark the body of the application's main loop as a Online Access phase in order to utilize main loop iterations for iterative online analysis.

Parameters
handleThe handle of the associated user region, which will become a root of the profile call-tree. This handle must be declared using SCOREP_USER_REGION_DEFINE or SCOREP_USER_GLOBAL_REGION_DEFINE before. C/C++ example:
1 void main()
2 {
3  SCOREP_USER_REGION_DEFINE( my_region_handle )
4 
5  // application initialization
6 
7  for ( ) // main loop of the application
8  {
9  SCOREP_USER_OA_PHASE_BEGIN( my_region_handle, "main loop",SCOREP_USER_REGION_TYPE_COMMON )
10 
11  // do something
12 
13  SCOREP_USER_OA_PHASE_END( my_region_handle )
14  }
15 
16  // application finalization
17 }

Fortran example:

1 program myProg
2  SCOREP_USER_REGION_DEFINE( my_region_handle )
3 
4  ! applications initialization
5 
6  ! main loop of the application
7  do ...
8 
9  SCOREP_USER_OA_PHASE_BEGIN( my_region_handle, "main loop",SCOREP_USER_REGION_TYPE_COMMON )
10 
11  ! do something
12 
13  SCOREP_USER_OA_PHASE_END( my_region_handle )
14 
15  enddo
16 
17  !application finalization
18 
19 end program myProg
#define SCOREP_USER_PARAMETER_INT64 (   name,
  value 
)
Value:
{ \
SCOREP_User_ParameterInt64( &scorep_param, name, value ); }
uint64_t SCOREP_User_ParameterHandle
Definition: SCOREP_User_Types.h:72
#define SCOREP_USER_INVALID_PARAMETER
Definition: SCOREP_User_Types.h:78

This statement adds a 64 bit signed integer type parameter for parameter-based profiling to the current region. The call-tree for the region is split according to the different values of the parameters with the same name. It is possible to add an arbitrary number of parameters to a region. Each parameter must have a unique name. However, it is not recommended to use more than 1 parameter per region.

Parameters
nameA string containing the name of the parameter.
valueThe value of the parameter. It must be possible for implicit casts to cast it to a 64 bit integer.

C/C++ example:

1 void myfunc(int64 myint)
2 {
3  SCOREP_USER_REGION_DEFINE( my_region_handle )
4  SCOREP_USER_REGION_BEGIN( my_region_handle, "my_region",SCOREP_USER_REGION_TYPE_COMMON )
5  SCOREP_USER_PARAMETER_INT64("A nice int",myint)
6 
7  // do something
8 
9  SCOREP_USER_REGION_END( my_region_handle )
10 }
#define SCOREP_USER_PARAMETER_STRING (   name,
  value 
)
Value:
{ \
SCOREP_User_ParameterString( &scorep_param, name, value ); }
uint64_t SCOREP_User_ParameterHandle
Definition: SCOREP_User_Types.h:72
#define SCOREP_USER_INVALID_PARAMETER
Definition: SCOREP_User_Types.h:78

This statement adds a string type parameter for parameter-based profiling to the current region. The call-tree for the region is split according to the different values of the parameters with the same name. It is possible to add an arbitrary number of parameters to a region. Each parameter must have a unique name. However, it is not recommended to use more than 1 parameter per region. During one visit it is not allowed to use the same name twice for two different parameters.

Parameters
nameA string containing the name of the parameter.
valueThe value of the parameter. It must be a pointer to a C-string (a NULL-terminated string).

C/C++ Example:

1 void myfunc(char *mystring)
2 {
3  SCOREP_USER_REGION_DEFINE( my_region_handle )
4  SCOREP_USER_REGION_BEGIN( my_region_handle, "my_region",SCOREP_USER_REGION_TYPE_COMMON )
5  SCOREP_USER_PARAMETER_STRING("A nice string",mystring)
6 
7  // do something
8 
9  SCOREP_USER_REGION_END( my_region_handle )
10 }
#define SCOREP_USER_PARAMETER_UINT64 (   name,
  value 
)
Value:
{ \
SCOREP_User_ParameterUint64( &scorep_param, name, value ); }
uint64_t SCOREP_User_ParameterHandle
Definition: SCOREP_User_Types.h:72
#define SCOREP_USER_INVALID_PARAMETER
Definition: SCOREP_User_Types.h:78

This statement adds a 64 bit unsigned integer type parameter for parameter-based profiling to the current region. The call-tree for the region is split according to the different values of the parameters with the same name. It is possible to add an arbitrary number of parameters to a region. Each parameter must have a unique name. However, it is not recommended to use more than 1 parameter per region.

Parameters
nameA string containing the name of the parameter.
valueThe value of the parameter. It must be possible for implicit casts to cast it to a 64 bit unsigned integer.

C/C++ example:

1 void myfunc(uint64 myuint)
2 {
3  SCOREP_USER_REGION_DEFINE( my_region_handle )
4  SCOREP_USER_REGION_BEGIN( my_region_handle, "my_region",SCOREP_USER_REGION_TYPE_COMMON )
5  SCOREP_USER_PARAMETER_UINT64("A nice unsigned int",myuint)
6 
7  // do something
8 
9  SCOREP_USER_REGION_END( my_region_handle )
10 }
#define SCOREP_USER_REGION (   name,
  type 
)

Instruments a code block as a region with the given name. It inserts a local variable of the type class SCOREP_User_Region. Its constructor generates the enter event and its destructor generates the exit event. Thus, only one statement is necessary to instrument the code block. This statement is only in C++ available.

Parameters
nameA string containing the name of the new region. The name should be unique.
typeSpecifies the type of the region. Possible values are SCOREP_USER_REGION_TYPE_COMMON, SCOREP_USER_REGION_TYPE_FUNCTION, SCOREP_USER_REGION_TYPE_LOOP, SCOREP_USER_REGION_TYPE_DYNAMIC, SCOREP_USER_REGION_TYPE_PHASE, or a combination of them.

Example:

1 void myfunc()
2 {
3  SCOREP_USER_REGION_( "myfunc", SCOREP_USER_REGION_TYPE_FUNCTION )
4 
5  // do something
6 }
#define SCOREP_USER_REGION_BEGIN (   handle,
  name,
  type 
)
Value:
SCOREP_User_RegionBegin( \
&handle, &SCOREP_User_LastFileName, &SCOREP_User_LastFileHandle, name, \
type, __FILE__, __LINE__ );

This macro marks the start of a user defined region. The SCOREP_USER_REGION_BEGIN and SCOREP_USER_REGION_END calls of all regions must be correctly nested.

Parameters
handleThe handle of the region to be started. This handle must be declared using SCOREP_USER_REGION_DEFINE or SCOREP_USER_GLOBAL_REGION_DEFINE before.
nameA string containing the name of the new region. The name should be unique.
typeSpecifies the type of the region. Possible values are SCOREP_USER_REGION_TYPE_COMMON, SCOREP_USER_REGION_TYPE_FUNCTION, SCOREP_USER_REGION_TYPE_LOOP, SCOREP_USER_REGION_TYPE_DYNAMIC, SCOREP_USER_REGION_TYPE_PHASE, or a combination of them.

C/C++ example:

1 void myfunc()
2 {
3  SCOREP_USER_REGION_DEFINE( my_region_handle )
4 
5  // do something
6 
7  SCOREP_USER_REGION_BEGIN( my_region_handle, "my_region",SCOREP_USER_REGION_TYPE_COMMON )
8 
9  // do something
10 
11  SCOREP_USER_REGION_END( my_region_handle )
12 }

Fortran example:

1 program myProg
2  SCOREP_USER_REGION_DEFINE( my_region_handle )
3  ! more declarations
4 
5  SCOREP_USER_REGION_BEGIN( my_region_handle, "my_region",SCOREP_USER_REGION_TYPE_COMMON )
6  ! do something
7  SCOREP_USER_REGION_END( my_region_handle )
8 
9 end program myProg
#define SCOREP_USER_REGION_DEFINE (   handle)    static SCOREP_User_RegionHandle handle = SCOREP_USER_INVALID_REGION;

This macro defines a user region handle in a local context. Every user handle must be defined, before it can be used.

Parameters
handleA unique name for the handle must be provided. This handle is declared in the macro. This handle is used in the SCOREP_USER_REGION_BEGIN and SCOREP_USER_REGION_END statements to specify which region is started, or ended. If you are using a Fortran version which has a limited length of code lines, the length of the handle parameter must be at most 4 characters, else the declaration line exceeds the allowed length.

C/C++ example:

1 void myfunc()
2 {
3  SCOREP_USER_REGION_DEFINE( my_region_handle )
4 
5  // do something
6 
7  SCOREP_USER_REGION_BEGIN( my_region_handle, "my_region",SCOREP_USER_REGION_TYPE_COMMON )
8 
9  // do something
10 
11  SCOREP_USER_REGION_END( my_region_handle )
12 }

Fortran example:

1 program myProg
2  SCOREP_USER_REGION_DEFINE( my_region_handle )
3  ! more declarations
4 
5  SCOREP_USER_REGION_BEGIN( my_region_handle, "my_region",SCOREP_USER_REGION_TYPE_COMMON )
6  ! do something
7  SCOREP_USER_REGION_END( my_region_handle )
8 
9 end program myProg
#define SCOREP_USER_REGION_END (   handle)    SCOREP_User_RegionEnd( handle );

This macro marks the end of a user defined region. The SCOREP_USER_REGION_BEGIN and SCOREP_USER_REGION_END calls of all regions must be correctly nested.

Parameters
handleThe handle of the region which ended here. It must be the same handle which is used as the start of the region.

C/C++ example:

1 void myfunc()
2 {
3  SCOREP_USER_REGION_DEFINE( my_region_handle )
4 
5  // do something
6 
7  SCOREP_USER_REGION_BEGIN( my_region_handle, "my_region",SCOREP_USER_REGION_TYPE_COMMON )
8 
9  // do something
10 
11  SCOREP_USER_REGION_END( my_region_handle )
12 }

Fortran example:

1 program myProg
2  SCOREP_USER_REGION_DEFINE( my_region_handle )
3  ! more declarations
4 
5  SCOREP_USER_REGION_BEGIN( my_region_handle, "my_region",SCOREP_USER_REGION_TYPE_COMMON )
6  ! do something
7  SCOREP_USER_REGION_END( my_region_handle )
8 
9 end program myProg
#define SCOREP_USER_REGION_ENTER (   handle)    SCOREP_User_RegionEnter( handle );

This macro marks the beginning of a user defined and already initialized region. The SCOREP_USER_REGION_BEGIN/SCOREP_USER_REGION_ENTER and SCOREP_USER_REGION_END calls of all regions must be correctly nested. To initialize the region handle, SCOREP_USER_REGION_INIT or SCOREP_USER_REGION_BEGIN must be called before.

Parameters
handleThe handle of the region which ended here. It must be the same handle which is used as the start of the region.

C/C++ example:

1 void myfunc()
2 {
3  SCOREP_USER_REGION_DEFINE( my_region_handle )
4 
5  // do something
6 
7  SCOREP_USER_REGION_INIT( my_region_handle, "my_region",SCOREP_USER_REGION_TYPE_COMMON )
8  SCOREP_USER_REGION_ENTER( my_region_handle )
9 
10  // do something
11 
12  SCOREP_USER_REGION_END( my_region_handle )
13 }

Fortran example:

1 program myProg
2  SCOREP_USER_REGION_DEFINE( my_region_handle )
3  ! more declarations
4 
5  SCOREP_USER_REGION_INIT( my_region_handle, "my_region",SCOREP_USER_REGION_TYPE_COMMON )
6  SCOREP_USER_REGION_ENTER( my_region_handle )
7  ! do something
8  SCOREP_USER_REGION_END( my_region_handle )
9 
10 end program myProg
#define SCOREP_USER_REGION_INIT (   handle,
  name,
  type 
)
Value:
SCOREP_User_RegionInit( \
&handle, &SCOREP_User_LastFileName, &SCOREP_User_LastFileHandle, name, \
type, __FILE__, __LINE__ );

This macro initializes a user defined region. If the region handle is already initialized, no operation is executed.

Parameters
handleThe handle of the region to be started. This handle must be declared using SCOREP_USER_REGION_DEFINE or SCOREP_USER_GLOBAL_REGION_DEFINE before.
nameA string containing the name of the new region. The name should be unique.
typeSpecifies the type of the region. Possible values are SCOREP_USER_REGION_TYPE_COMMON, SCOREP_USER_REGION_TYPE_FUNCTION, SCOREP_USER_REGION_TYPE_LOOP, SCOREP_USER_REGION_TYPE_DYNAMIC, SCOREP_USER_REGION_TYPE_PHASE, or a combination of them.

C/C++ example:

1 void myfunc()
2 {
3  SCOREP_USER_REGION_DEFINE( my_region_handle )
4 
5  // do something
6 
7  SCOREP_USER_REGION_INIT( my_region_handle, "my_region",SCOREP_USER_REGION_TYPE_COMMON )
8  SCOREP_USER_REGION_ENTER( my_region_handle )
9 
10  // do something
11 
12  SCOREP_USER_REGION_END( my_region_handle )
13 }

Fortran example:

1 program myProg
2  SCOREP_USER_REGION_DEFINE( my_region_handle )
3  ! more declarations
4 
5  SCOREP_USER_REGION_INIT( my_region_handle, "my_region",SCOREP_USER_REGION_TYPE_COMMON )
6  SCOREP_USER_REGION_ENTER( my_region_handle )
7  ! do something
8  SCOREP_USER_REGION_END( my_region_handle )
9 
10 end program myProg
#define SCOREP_USER_REGION_TYPE_COMMON   0

Region without any specific type.

#define SCOREP_USER_REGION_TYPE_DYNAMIC   4

Marks the regions as dynamic.

#define SCOREP_USER_REGION_TYPE_FUNCTION   1

Marks the region as being the codeblock of a function.

#define SCOREP_USER_REGION_TYPE_LOOP   2

Marks the region as being the codeblock of a loop with the same number of iterations on all processes.

#define SCOREP_USER_REGION_TYPE_PHASE   8

Marks the region as being a root node of a phase.