EPIK  Scalable runtime performance measurement system
Data Structures | Typedefs | Enumerations
esd_unify.h File Reference

Static program entity unification routines. More...

Data Structures

struct  UnifyMach
struct  UnifyNode
struct  UnifyProc
struct  UnifyThrd
struct  UnifyLoc
struct  UnifyRegion
struct  UnifyCsite
struct  UnifyCpath
struct  UnifyMetric
struct  UnifyComDist
struct  UnifyCart
struct  UnifyWin
struct  CartCoord
struct  EsdUnifyData_struct

Typedefs

typedef struct EsdUnifyData_struct EsdUnifyData
 Opaque data structure storing global and per-process unification data.

Enumerations

enum  esd_unify_map_t {
  ESD_UNIFY_STRMAP, ESD_UNIFY_MACHMAP, ESD_UNIFY_NODEMAP, ESD_UNIFY_LOCMAP,
  ESD_UNIFY_FILEMAP, ESD_UNIFY_REGMAP, ESD_UNIFY_CSITEMAP, ESD_UNIFY_CPATHMAP,
  ESD_UNIFY_GROUPMAP, ESD_UNIFY_COMMAP, ESD_UNIFY_WINMAP, ESD_UNIFY_TOPMAP,
  ESD_UNIFY_NUM_MAPS
}
 Enumeration type defining symbolic names for the different per-process identifier mapping tables handled by EsdUnifyData. More...
enum  esd_unify_mode_t { ESD_UNIFY_FULL, ESD_UNIFY_PARTIAL }
 Enumeration type defining symbolic names for the different unification modes. More...

Functions

Unification data handling
EXTERN EsdUnifyDataesd_unify_create ()
 Creates and returns an new instance of type EsdUnifyData.
EXTERN void esd_unify_free (EsdUnifyData *instance)
 Destroys the given instance of EsdUnifyData and releases the allocated memory.
EXTERN void esd_unify_buffer (EsdUnifyData *instance, const buffer_t buffer, size_t size, int rank, esd_unify_mode_t mode)
 Processes size bytes of the local definition record data provided in the given memory buffer.
EXTERN void esd_unify_clear_data (EsdUnifyData *instance)
 Clears the unification data stored in the unification data object instance.
EXTERN EpkIdMapesd_unify_get_map (const EsdUnifyData *instance, esd_unify_map_t map_id)
 Returns one of the per-process identifier mapping tables stored in the unification data object instance.
EXTERN void esd_unify_clear_maps (EsdUnifyData *instance)
 Clears the per-process identifier mapping tables stored in the unification data object instance, except for the MPI communicator reference mapping.
EXTERN size_t esd_unify_size_defs (const EsdUnifyData *instance, esd_unify_mode_t mode)
 Determines the size of the definition data stored by the given instance of EsdUnifyData when written to a file/memory buffer in EPILOG format.
EXTERN size_t esd_unify_size_maps (const EsdUnifyData *instance)
 Determines the size of the identifier mapping data stored by the given instance of EsdUnifyData when written to a file/memory buffer in EPILOG format.
EXTERN void esd_unify_write_defs (EsdUnifyData *instance, ElgOut *deffile, esd_unify_mode_t mode)
 Writes the unified definition data collected in the given EsdUnifyData instance to the EPILOG output stream deffile.
EXTERN void esd_unify_write_maps (EsdUnifyData *instance, int rank, ElgOut *mapfile)
 Writes the identifier mapping data collected in the given EsdUnifyData instance to the EPILOG output stream mapfile using the given rank number.
EXTERN void esd_unify_serialize_defs (EsdUnifyData *instance, buffer_t *buffer, size_t *size, esd_unify_mode_t mode)
 Serialized the definition data held by the instance of EsdUnifyData to a memory buffer.
EXTERN void esd_unify_serialize_maps (EsdUnifyData *instance, int rank, buffer_t *buffer, size_t *size)
 Serialized the mapping data held by the instance of EsdUnifyData to a memory buffer.
EXTERN elg_ui4 esd_unify_add_group (EsdUnifyData *instance, elg_ui4 group_id, elg_ui1 mode, elg_ui4 size, elg_ui4 *ranks)
 Adds the definition data of an MPI group to the given unification data object instance and returns a unique identifier for that particular group.
EXTERN void esd_unify_add_comm (EsdUnifyData *instance, elg_ui4 comm_id, elg_ui4 group_id)
 Adds the definition data of an MPI communicator to the given unification data object instance.

Detailed Description

This file contains type definitions and function prototypes needed for the unification of per-process EPILOG definition records for static program entities, such as instrumented source code regions or MPI communicators.

Note:
This module uses the assert() macro to check various conditions (especially the values of given parameters) at runtime, which can cause a performance penalty.

Typedef Documentation


Enumeration Type Documentation

Enumerator:
ESD_UNIFY_STRMAP 

String ID mapping table.

ESD_UNIFY_MACHMAP 

Machine ID mapping table.

ESD_UNIFY_NODEMAP 

Node ID mapping table.

ESD_UNIFY_LOCMAP 

Location ID mapping table.

ESD_UNIFY_FILEMAP 

File ID mapping table.

ESD_UNIFY_REGMAP 

Region ID mapping table.

ESD_UNIFY_CSITEMAP 

Call site ID mapping table.

ESD_UNIFY_CPATHMAP 

Call-path ID mapping table.

ESD_UNIFY_GROUPMAP 

MPI group ID mapping table.

ESD_UNIFY_COMMAP 

MPI communicator ID mapping table.

ESD_UNIFY_WINMAP 

RMA window ID mapping table.

ESD_UNIFY_TOPMAP 

Cartesian topology ID mapping table.

ESD_UNIFY_NUM_MAPS 

Total number of mapping tables.

Enumerator:
ESD_UNIFY_FULL 

Full unification, incl.

locations & topologies

ESD_UNIFY_PARTIAL 

Partial unification.


Function Documentation

EXTERN void esd_unify_add_comm ( EsdUnifyData instance,
elg_ui4  comm_id,
elg_ui4  group_id 
)

It is assumed that the communicator data is already globalized.

Parameters:
instanceUnification data object
comm_idGlobal MPI communicator identifier
group_idGlobal MPI group identifier.
EXTERN elg_ui4 esd_unify_add_group ( EsdUnifyData instance,
elg_ui4  group_id,
elg_ui1  mode,
elg_ui4  size,
elg_ui4 *  ranks 
)

If the same group has already been defined before, no operation is performed (i.e., the data is merged).

Parameters:
instanceUnification data object
group_idLocal MPI group identifier
modeStorage mode of rank information
sizeGroup size (i.e., number of ranks)
ranksRank information (local |-> global rank mapping)
Returns:
Unique identifier for the group
EXTERN void esd_unify_buffer ( EsdUnifyData instance,
const buffer_t  buffer,
size_t  size,
int  rank,
esd_unify_mode_t  mode 
)

The unified definition data is collected in the unification data object instance. In addition, the per-process data (mapping tables etc.) is stored. Depending on the unification mode, location and topology data is just aggregated (ESD_UNIFY_PARTIAL) or really unified to generate identifier mappings (ESD_UNIFY_FULL). The rank parameter should either be set to the global rank of the process whose data is being processed or to -1 for partially unified data from multiple processes.

In case of an error (e.g., if the buffer does not contain EPILOG data), an error message is printed and the program is aborted.

Parameters:
instanceUnification data object
bufferMemory buffer containing the definition record data
sizeSize of buffer in bytes
rankRank of data being processed (or -1 for partially unified data)
modeUnification mode

It should be used in conjunction with esd_unify_clear_maps() to also clear the per-process identifier mappings.

Parameters:
instanceUnification data object
Parameters:
instanceUnification data object
Note:
This function does not modify/delete any global unification data.

Creates and returns an new instance of type EsdUnifyData. If the memory allocation request can not be fulfilled, an error message is printed and the program is aborted.

Returns:
Pointer to new instance
EXTERN void esd_unify_free ( EsdUnifyData instance)
Parameters:
instanceObject to be freed
EXTERN EpkIdMap* esd_unify_get_map ( const EsdUnifyData instance,
esd_unify_map_t  map_id 
)

The requested table is specified by map_id.

Parameters:
instanceUnification data object
map_idRequested mapping table
Returns:
Per-process identifier mapping table
EXTERN void esd_unify_serialize_defs ( EsdUnifyData instance,
buffer_t *  buffer,
size_t *  size,
esd_unify_mode_t  mode 
)

A buffer of appropriate size if implicitly created and its size and a pointer to it stored in buffer and size, respectively. Depending on the unification mode, location and topology data is either serialized (ESD_UNIFY_FULL) or not (ESD_UNIFY_PARTIAL).

Parameters:
instanceUnification data object
bufferAddress of a pointer where the memory location of the buffer is stored
sizeAddress of a pointer where the size of the buffer is stored
modeUnification mode
EXTERN void esd_unify_serialize_maps ( EsdUnifyData instance,
int  rank,
buffer_t *  buffer,
size_t *  size 
)

A buffer of appropriate size if implicitly created and its size and a pointer to it stored in buffer and size, respectively. To correctly initialize the header for the process-specific mapping data, the corresponding MPI rank needs to be given as well.

Parameters:
instanceUnification data object
rankRank to which the data corresponds
bufferAddress of a pointer where the memory location of the buffer is stored
sizeAddress of a pointer where the size of the buffer is stored
EXTERN size_t esd_unify_size_defs ( const EsdUnifyData instance,
esd_unify_mode_t  mode 
)

Depending on the unification mode, location and topology information is included (ESD_UNIFY_FULL) or not (ESD_UNIFY_PARTIAL).

Parameters:
instanceUnification data object
modeUnification mode
Returns:
Size of the definition data in EPILOG format in bytes
EXTERN size_t esd_unify_size_maps ( const EsdUnifyData instance)
Parameters:
instanceUnification data object
Returns:
Size of the mapping data in EPILOG format in bytes
EXTERN void esd_unify_write_defs ( EsdUnifyData instance,
ElgOut *  deffile,
esd_unify_mode_t  mode 
)

Depending on the unification mode, location and topology information is either written (ESD_UNIFY_FULL) or not (ESD_UNIFY_PARTIAL).

Parameters:
instanceObject containing the unified definition data
deffileEPILOG output stream
modeUnification mode
EXTERN void esd_unify_write_maps ( EsdUnifyData instance,
int  rank,
ElgOut *  mapfile 
)
Parameters:
instanceObject containing the unified definition data
rankRank number written to the header.
mapfileEPILOG output stream
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines

SCALASCA    Copyright © 1998–2012 Forschungszentrum Jülich GmbH, Jülich Supercomputing Centre