PEARL
Parallel Event Access and Replay Library
Public Types | Static Public Attributes | List of all members
pearl::Region Class Reference

Representation of a region definition. More...

#include <pearl/Region.h>

Public Types

enum  {
  cCLASS_INTERNAL = (0 << 24),
  cCLASS_USER = (1 << 24),
  cCLASS_MPI = (2 << 24),
  cCLASS_OMP = (4 << 24),
  cCLASS_ARMCI = (8 << 24),
  cCLASS_PTHREAD = (16 << 24),
  cCAT_MPI_SETUP = (1 << 16),
  cCAT_MPI_COLLECTIVE = (2 << 16),
  cCAT_MPI_P2P = (4 << 16),
  cCAT_MPI_RMA = (8 << 16),
  cCAT_MPI_IO = (16 << 16),
  cCAT_OMP_PARALLEL = (1 << 16),
  cCAT_OMP_SYNC = (2 << 16),
  cCAT_ARMCI_COMM = (1 << 16),
  cCAT_ARMCI_SYNC = (2 << 16),
  cCAT_PTHREAD_MGMT = (1 << 16),
  cCAT_PTHREAD_SYNC = (2 << 16),
  cTYPE_OMP_BARRIER = (1 << 8),
  cMODE_OMP_IMPLICIT = (1 << 0),
  cMODE_OMP_EXPLICIT = (2 << 0),
  cTYPE_PTHREAD_MUTEX = (1 << 8),
  cTYPE_PTHREAD_SPIN = (2 << 8),
  cTYPE_PTHREAD_CONDITION = (4 << 8),
  cMODE_PTHREAD_LOCK = (1 << 0),
  cMODE_PTHREAD_TRYLOCK = (2 << 0),
  cMODE_PTHREAD_UNLOCK = (4 << 0),
  cMODE_PTHREAD_WAIT = (1 << 0),
  cMODE_PTHREAD_TIMEDWAIT = (2 << 0),
  cTYPE_MPI_INIT = (1 << 8),
  cTYPE_MPI_FINALIZE = (2 << 8),
  cTYPE_MPI_BARRIER = (1 << 8),
  cTYPE_MPI_ONE_TO_N = (2 << 8),
  cTYPE_MPI_N_TO_ONE = (4 << 8),
  cTYPE_MPI_N_TO_N = (8 << 8),
  cTYPE_MPI_PARTIAL = (16 << 8),
  cTYPE_MPI_SEND = (1 << 8),
  cTYPE_MPI_RECV = (2 << 8),
  cTYPE_MPI_SENDRECV = (3 << 8),
  cTYPE_MPI_TEST = (4 << 8),
  cTYPE_MPI_WAIT = (8 << 8),
  cTYPE_MPI_RMA_COMM = (1 << 8),
  cTYPE_MPI_RMA_COLL = (2 << 8),
  cTYPE_MPI_RMA_GATS = (4 << 8),
  cTYPE_MPI_RMA_PASSIVE = (8 << 8),
  cTYPE_ARMCI_INIT = (1 << 8),
  cTYPE_ARMCI_FINALIZE = (2 << 8),
  cTYPE_ARMCI_ALLFENCE = (4 << 8),
  cTYPE_ARMCI_BARRIER = (8 << 8),
  cMODE_MPI_STANDARD = (1 << 0),
  cMODE_MPI_SYNCHRONOUS = (2 << 0),
  cMODE_MPI_BUFFERED = (4 << 0),
  cMODE_MPI_READY = (8 << 0),
  cMODE_MPI_NONBLOCKING = (16 << 0),
  cMODE_MPI_PERSISTENT = (32 << 0),
  cMODE_MPI_SINGLE = (1 << 0),
  cMODE_MPI_MANY = (2 << 0),
  cMODE_RMA_PUT = (1 << 0),
  cMODE_RMA_GET = (2 << 0),
  cMODE_RMA_START = (1 << 0),
  cMODE_RMA_COMPLETE = (2 << 0),
  cMODE_RMA_POST = (4 << 0),
  cMODE_RMA_WAIT = (8 << 0),
  cMODE_RMA_TEST = (16 << 0),
  cMODE_RMA_FENCE = (1 << 0),
  cMODE_RMA_WIN_CREATE = (2 << 0),
  cMODE_RMA_WIN_FREE = (4 << 0),
  cMODE_RMA_LOCK = (1 << 0),
  cMODE_RMA_UNLOCK = (2 << 0)
}
 Symbolic names for region classification. More...
 
enum  Role {
  ROLE_UNKNOWN,
  ROLE_FUNCTION,
  ROLE_WRAPPER,
  ROLE_LOOP,
  ROLE_CODE,
  ROLE_PARALLEL,
  ROLE_SECTIONS,
  ROLE_SECTION,
  ROLE_SINGLE,
  ROLE_SINGLE_SBLOCK,
  ROLE_WORKSHARE,
  ROLE_MASTER,
  ROLE_CRITICAL,
  ROLE_CRITICAL_SBLOCK,
  ROLE_BARRIER,
  ROLE_IMPLICIT_BARRIER,
  ROLE_ATOMIC,
  ROLE_FLUSH,
  ROLE_ORDERED,
  ROLE_ORDERED_SBLOCK,
  ROLE_TASK,
  ROLE_TASK_CREATE,
  ROLE_TASK_WAIT,
  ROLE_COLL_ONE2ALL,
  ROLE_COLL_ALL2ONE,
  ROLE_COLL_ALL2ALL,
  ROLE_COLL_OTHER,
  ROLE_FILE_IO,
  ROLE_POINT2POINT,
  ROLE_RMA,
  ROLE_DATA_TRANSFER,
  ROLE_ARTIFICIAL,
  ROLE_THREAD_CREATE,
  ROLE_THREAD_WAIT,
  ROLE_TASK_UNTIED,
  ROLE_ALLOCATE,
  ROLE_DEALLOCATE,
  ROLE_REALLOCATE,
  NUMBER_OF_ROLES
}
 Region roles. More...
 
typedef uint32_t IdType
 Region definition identifier type. More...
 

Public Member Functions

Constructors & destructor
 Region (IdType id, const String &canonicalName, const String &displayName, const String &description, Role role, Paradigm paradigm, const String &filename, uint32_t startLine, uint32_t endLine)
 Constructor. More...
 
Access definition data
IdType getId () const
 Get global identifier. More...
 
const StringgetCanonicalName () const
 Get canonical region name. More...
 
const StringgetDisplayName () const
 Get display region name. More...
 
const StringgetDescription () const
 Get region description. More...
 
Role getRole () const
 Get region role. More...
 
Paradigm getParadigm () const
 Get region paradigm. More...
 
const StringgetFilename () const
 Get filename. More...
 
uint32_t getStartLine () const
 Get start line number. More...
 
uint32_t getEndLine () const
 Get end line number. More...
 
uint32_t getClassification () const
 Get region classification. More...
 

Static Public Attributes

static const IdType NO_ID = (~static_cast<IdType>(0))
 Numerical identifier used for undefined region definitions. More...
 
static const Region UNDEFINED
 Static instance of class Region representing undefined region entries in other definitions. More...
 

Related Functions

(Note that these are not member functions.)

Stream I/O functions
std::ostream & operator<< (std::ostream &stream, const Region &item)
 Stream output operator. More...
 
Comparison operators
bool operator== (const Region &lhs, const Region &rhs)
 Equality operator. More...
 
bool operator!= (const Region &lhs, const Region &rhs)
 Inequality operator. More...
 

Detailed Description

Instances of the Region class provide information about source-code regions of the target application. Regions are characterized by their canonical name (typically the linker decorated, i.e., mangled name), their display name (i.e., the demangled name if available), a file in which this region is defined, begin and end line numbers, as well as a region role and a paradigm. In addition, a free-form textual description can be provided. The numerical identifiers of the individual regions are globally defined and continuously enumerated, i.e., the ID is element of [0,#regions-1].

Member Typedef Documentation

◆ IdType

typedef uint32_t pearl::Region::IdType

Member Enumeration Documentation

◆ anonymous enum

anonymous enum
Enumerator
cCLASS_INTERNAL 
cCLASS_USER 
cCLASS_MPI 
cCLASS_OMP 
cCLASS_ARMCI 
cCLASS_PTHREAD 
cCAT_MPI_SETUP 
cCAT_MPI_COLLECTIVE 
cCAT_MPI_P2P 
cCAT_MPI_RMA 
cCAT_MPI_IO 
cCAT_OMP_PARALLEL 
cCAT_OMP_SYNC 
cCAT_ARMCI_COMM 
cCAT_ARMCI_SYNC 
cCAT_PTHREAD_MGMT 
cCAT_PTHREAD_SYNC 
cTYPE_OMP_BARRIER 
cMODE_OMP_IMPLICIT 
cMODE_OMP_EXPLICIT 
cTYPE_PTHREAD_MUTEX 
cTYPE_PTHREAD_SPIN 
cTYPE_PTHREAD_CONDITION 
cMODE_PTHREAD_LOCK 
cMODE_PTHREAD_TRYLOCK 
cMODE_PTHREAD_UNLOCK 
cMODE_PTHREAD_WAIT 
cMODE_PTHREAD_TIMEDWAIT 
cTYPE_MPI_INIT 
cTYPE_MPI_FINALIZE 
cTYPE_MPI_BARRIER 
cTYPE_MPI_ONE_TO_N 
cTYPE_MPI_N_TO_ONE 
cTYPE_MPI_N_TO_N 
cTYPE_MPI_PARTIAL 
cTYPE_MPI_SEND 
cTYPE_MPI_RECV 
cTYPE_MPI_SENDRECV 
cTYPE_MPI_TEST 
cTYPE_MPI_WAIT 
cTYPE_MPI_RMA_COMM 
cTYPE_MPI_RMA_COLL 
cTYPE_MPI_RMA_GATS 
cTYPE_MPI_RMA_PASSIVE 
cTYPE_ARMCI_INIT 
cTYPE_ARMCI_FINALIZE 
cTYPE_ARMCI_ALLFENCE 
cTYPE_ARMCI_BARRIER 
cMODE_MPI_STANDARD 
cMODE_MPI_SYNCHRONOUS 
cMODE_MPI_BUFFERED 
cMODE_MPI_READY 
cMODE_MPI_NONBLOCKING 
cMODE_MPI_PERSISTENT 
cMODE_MPI_SINGLE 
cMODE_MPI_MANY 
cMODE_RMA_PUT 
cMODE_RMA_GET 
cMODE_RMA_START 
cMODE_RMA_COMPLETE 
cMODE_RMA_POST 
cMODE_RMA_WAIT 
cMODE_RMA_TEST 
cMODE_RMA_FENCE 
cMODE_RMA_WIN_CREATE 
cMODE_RMA_WIN_FREE 
cMODE_RMA_LOCK 
cMODE_RMA_UNLOCK 

◆ Role

Every region has a role field associated to it. The role encodes more specific information about the region, in particular to which kind of language construct (e.g., function, loop, OpenMP construct) the region refers to.

Enumerator
ROLE_UNKNOWN 

Unknown role, used only if no other role fits.

ROLE_FUNCTION 

Function or subroutine.

ROLE_WRAPPER 

Wrapped API function.

ROLE_LOOP 

Loop construct.

ROLE_CODE 

Arbitrary user-defined code block.

ROLE_PARALLEL 

OpenMP "parallel" construct (structured block)

ROLE_SECTIONS 

OpenMP "sections" construct.

ROLE_SECTION 

Individual "section" inside an OpenMP "sections" construct.

ROLE_SINGLE 

OpenMP "single" construct.

ROLE_SINGLE_SBLOCK 

OpenMP "single" construct (structured block)

ROLE_WORKSHARE 

OpenMP "workshare" construct.

ROLE_MASTER 

OpenMP "master" construct.

ROLE_CRITICAL 

OpenMP "critical" construct.

ROLE_CRITICAL_SBLOCK 

OpenMP "critical" construct (structured block)

ROLE_BARRIER 

Explicit barrier (e.g., MPI or OpenMP)

ROLE_IMPLICIT_BARRIER 

Implicit barrier as part of various OpenMP constructs.

ROLE_ATOMIC 

OpenMP "atomic" construct.

ROLE_FLUSH 

OpenMP "flush" construct.

ROLE_ORDERED 

OpenMP "ordered" construct.

ROLE_ORDERED_SBLOCK 

OpenMP "ordered construct (structured block)

ROLE_TASK 

OpenMP "task" construct (structured block)

ROLE_TASK_CREATE 

OpenMP "task" construct (creation)

ROLE_TASK_WAIT 

OpenMP "taskwait" construct.

ROLE_COLL_ONE2ALL 

Collective 1:N communication operation (e.g., MPI_Bcast)

ROLE_COLL_ALL2ONE 

Collective N:1 communication operation (e.g., MPI_Gather)

ROLE_COLL_ALL2ALL 

Collective N:N communication operation (e.g., MPI_Allreduce)

ROLE_COLL_OTHER 

Collective M:N communication operation (e.g., MPI_Scan)

ROLE_FILE_IO 

File I/O operation.

ROLE_POINT2POINT 

Point-to-point communication operation.

ROLE_RMA 

Remote memory access communication operation.

ROLE_DATA_TRANSFER 

Memory data transfer operation.

ROLE_ARTIFICIAL 

Artificial region (used for measurement-related activities).

ROLE_THREAD_CREATE 

Thread creation in create-wait paradigm.

ROLE_THREAD_WAIT 

Thread wait in create-wait paradigm.

ROLE_TASK_UNTIED 

OpenMP "untied task" construct (structured block)

ROLE_ALLOCATE 

Memory allocation operation.

ROLE_DEALLOCATE 

Memory deallocation operation.

ROLE_REALLOCATE 

Memory reallocation operation.

NUMBER_OF_ROLES 

Not a valid role, for internal use only.

Constructor & Destructor Documentation

◆ Region()

pearl::Region::Region ( IdType  id,
const String canonicalName,
const String displayName,
const String description,
Role  role,
Paradigm  paradigm,
const String filename,
uint32_t  startLine,
uint32_t  endLine 
)

Creates a new region definition instance and initializes it with the given values.

Parameters
idGlobal region identifier
canonicalNameRegion name (typically mangled)
displayNameRegion name (demangled if available, otherwise identical to canonicalName)
descriptionFree-form region description (optional, String::UNDEFINED otherwise)
roleRegion role
paradigmRegion paradigm
filenameName of source file in which the region is defined (String::UNDEFINED if unknown)
startLineLine number where the region starts (zero if unknown)
endLineLine number where the region ends (zero if unknown)

Member Function Documentation

◆ getCanonicalName()

const String& pearl::Region::getCanonicalName ( ) const

Returns the string definition storing the canonical region name. For compiler-instrumented functions, this is typically the mangled (i.e., linker-decorated) name. For other regions, it can be an arbitrary character string.

Returns
Canonical region name

◆ getClassification()

uint32_t Region::getClassification ( ) const
inline

Returns a 32-bit unsigned integer value providing an encoded classification of the region. This member functions and its return value is not intended to be used directly. Instead, the region predicate functions should be called from client code.

Returns
Region classification

◆ getDescription()

const String& pearl::Region::getDescription ( ) const

Returns the string definition storing the free-form region description associated with the source-code region. If this information is not available, String::UNDEFINED is returned.

Returns
Region description

◆ getDisplayName()

const String& pearl::Region::getDisplayName ( ) const

Returns the string definition storing the region's display name. For compiler-instrumented functions, this corresponds to the demangled name if available, otherwise it is identical to the canonical name. For other regions, it can be an arbitrary character string.

Returns
Region name for display

◆ getEndLine()

uint32_t pearl::Region::getEndLine ( ) const

Returns the line number where the region ends in the associated source file (zero if this information is not available).

Returns
End line number

◆ getFilename()

const String& pearl::Region::getFilename ( ) const

Returns the string definition storing the name of the file in which the region is defined. If this information is not available, String::UNDEFINED is returned.

Returns
Filename

◆ getId()

IdType pearl::Region::getId ( ) const

Returns the global identifier of the region definition.

Returns
Global identifier

◆ getParadigm()

Paradigm pearl::Region::getParadigm ( ) const

Returns the region paradigm, encoding more detailed information on the programming model or how the region got generated, respectively.

Returns
Region paradigm

◆ getRole()

Role pearl::Region::getRole ( ) const

Returns the region role, encoding more detailed information. See the documentation of Region::Role for details.

Returns
Region role

◆ getStartLine()

uint32_t pearl::Region::getStartLine ( ) const

Returns the line number where the region starts in the associated source file (zero if this information is not available).

Returns
Start line number

Friends And Related Function Documentation

◆ operator!=()

bool operator!= ( const Region lhs,
const Region rhs 
)
related

Compares two region definition objects lhs and rhs for inequality. Two region definitions are considered unequal if any of their attributes differ.

Parameters
lhsLeft-hand operand
rhsRight-hand operand
Returns
True if the region definitions differ, false otherwise.

◆ operator<<()

std::ostream & operator<< ( std::ostream &  stream,
const Region item 
)
related

Prints the contents of the given region definition object item to an output stream in a human-readable form.

Parameters
streamOutput stream
itemRegion definition object
Returns
Output stream

◆ operator==()

bool operator== ( const Region lhs,
const Region rhs 
)
related

Compares two region definition objects lhs and rhs for equality. Two region definitions are considered equal if all of their attributes are identical.

Parameters
lhsLeft-hand operand
rhsRight-hand operand
Returns
True if the region definitions are equal, false otherwise.

Member Data Documentation

◆ NO_ID

const IdType pearl::Region::NO_ID = (~static_cast<IdType>(0))
static

◆ UNDEFINED

const Region pearl::Region::UNDEFINED
static

The documentation for this class was generated from the following files:

Scalasca    Copyright © 1998–2019 Forschungszentrum Jülich GmbH, Jülich Supercomputing Centre
Copyright © 2009–2015 German Research School for Simulation Sciences GmbH, Laboratory for Parallel Programming