PEARL
Parallel Event Access and Replay Library
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Public Types | Public Member Functions | Static Public Attributes | Related Functions
pearl::Region Class Reference

Representation of a region definition. More...

#include <pearl/Region.h>

List of all members.

Public Types

enum  {
  cCLASS_INTERNAL = (0 << 24), cCLASS_USER = (1 << 24), cCLASS_MPI = (2 << 24), cCLASS_OMP = (4 << 24),
  cCLASS_ARMCI = (8 << 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), cTYPE_OMP_BARRIER = (1 << 8), cMODE_OMP_IMPLICIT = (1 << 0),
  cMODE_OMP_EXPLICIT = (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,
  NUMBER_OF_ROLES
}
 Region roles. More...
enum  Paradigm {
  PARADIGM_UNKNOWN, PARADIGM_USER, PARADIGM_COMPILER, PARADIGM_OPENMP,
  PARADIGM_MPI, PARADIGM_CUDA, PARADIGM_MEASUREMENT_SYSTEM, NUMBER_OF_PARADIGMS
}
 Region paradigms. More...
typedef uint32_t IdType
 Region definition identifier type.

Public Member Functions

IdType getId () const
 Get global identifier.
const StringgetCanonicalName () const
 Get canonical region name.
const StringgetDisplayName () const
 Get display region name.
const StringgetDescription () const
 Get region description.
Role getRole () const
 Get region role.
Paradigm getParadigm () const
 Get region paradigm.
const StringgetFilename () const
 Get filename.
uint32_t getStartLine () const
 Get start line number.
uint32_t getEndLine () const
 Get end line number.
uint32_t getClassification () const
 Get region classification.
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.

Static Public Attributes

static const IdType NO_ID = (~static_cast<IdType>(0))
 Numerical identifier used for undefined region definitions.
static const Region UNDEFINED

Related Functions

(Note that these are not member functions.)

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

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 type. 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

typedef uint32_t pearl::Region::IdType

Member Enumeration Documentation

anonymous enum
Enumerator:
cCLASS_INTERNAL 
cCLASS_USER 
cCLASS_MPI 
cCLASS_OMP 
cCLASS_ARMCI 
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 
cTYPE_OMP_BARRIER 
cMODE_OMP_IMPLICIT 
cMODE_OMP_EXPLICIT 
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 

Every region has a paradigm field associated to it. The paradigm encodes the programming model the region refers to (e.g., MPI or OpenMP), or how the region was captured (e.g., through compiler or user instrumentation).

Enumerator:
PARADIGM_UNKNOWN 

Unknown paradigm, used only if no other paradigm fits.

PARADIGM_USER 

Generated through user instrumentation.

PARADIGM_COMPILER 

Generated through compiler instrumentation.

PARADIGM_OPENMP 

OpenMP directives and API functions.

PARADIGM_MPI 

MPI functions.

PARADIGM_CUDA 

CUDA API functions.

PARADIGM_MEASUREMENT_SYSTEM 

Measurement-related activities.

NUMBER_OF_PARADIGMS 

Not a valid paradigm, for internal use only.

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).

NUMBER_OF_ROLES 

Not a valid role, for internal use only.


Constructor & Destructor Documentation

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

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
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

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

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 ba an arbitrary character string.

Returns:
Region name for display
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

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

Returns the global identifier of the region definition.

Returns:
Global identifier

Returns the region paradigm, encoding more detailed information on the programmind model or how the region got generated, respectively. See the documentation of Region::Paradigm for details.

Returns:
Region paradigm

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

Returns:
Region role
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

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.
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
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

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

Static instance of class Region representing undefined region entries in other definitions.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

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