1.2 (revision 3183)
Typedefs | Enumerations | Functions

OTF2_IdMap.h File Reference

Identifier mapping data structure, based on Scalasca's epk_idmap.h. More...

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
#include <otf2/OTF2_ErrorCodes.h>

Go to the source code of this file.

Typedefs

typedef struct OTF2_IdMap_struct OTF2_IdMap
typedef void(* OTF2_IdMap_TraverseCallback )(uint64_t localId, uint64_t globalId, void *userData)
 Function prototype for use in OTF2_IdMap_Traverse.
typedef uint8_t OTF2_IdMapMode

Enumerations

enum  OTF2_IdMapMode_enum {
  OTF2_ID_MAP_DENSE,
  OTF2_ID_MAP_SPARSE
}

Functions

OTF2_ErrorCode OTF2_IdMap_AddIdPair (OTF2_IdMap *instance, uint64_t localId, uint64_t globalId)
OTF2_ErrorCode OTF2_IdMap_Clear (OTF2_IdMap *instance)
OTF2_IdMapOTF2_IdMap_Create (OTF2_IdMapMode mode, uint64_t capacity)
OTF2_IdMapOTF2_IdMap_CreateFromUint32Array (uint64_t length, const uint32_t *mappings, bool optimizeSize)
OTF2_IdMapOTF2_IdMap_CreateFromUint64Array (uint64_t length, const uint64_t *mappings, bool optimizeSize)
void OTF2_IdMap_Free (OTF2_IdMap *instance)
OTF2_ErrorCode OTF2_IdMap_GetGlobalId (const OTF2_IdMap *instance, uint64_t localId, uint64_t *globalId)
OTF2_ErrorCode OTF2_IdMap_GetMode (const OTF2_IdMap *instance, OTF2_IdMapMode *mode)
OTF2_ErrorCode OTF2_IdMap_GetSize (const OTF2_IdMap *instance, uint64_t *size)
OTF2_ErrorCode OTF2_IdMap_Traverse (const OTF2_IdMap *instance, OTF2_IdMap_TraverseCallback callback, void *userData)

Detailed Description

Identifier mapping data structure, based on Scalasca's epk_idmap.h.

Maintainer:
Christian Rössel <c.roessel@fz-juelich.de>

This file provides type definitions and function prototypes for an identifier mapping data structure which is used to store mapping tables for converting local into global identifiers.

This mapping data structure can operate in two different modes (see OTF2_IdMapMode): A dense mapping can be used if the local identifiers are consecutively enumerated from 0 to N-1. In this case, only the global identifier are stored in the table at the corresponding entry, leading to compact storage and fast look-up. By contrast, if the local identifiers can consist of arbitrary numbers, a sparse mapping is necessary. Here, (localId, globalId) tuples are stored, which requires a more complicated look-up procedure.


Typedef Documentation

typedef struct OTF2_IdMap_struct OTF2_IdMap

Opaque data structure representing an ID mapping table.

typedef uint8_t OTF2_IdMapMode

Wrapper around enum OTF2_IdMapMode_enum, so that it is guaranteed that it is a uint8_t


Enumeration Type Documentation

Enumeration type defining the two different modes of an identifier mapping table.

Enumerator:
OTF2_ID_MAP_DENSE 

Dense mapping table

OTF2_ID_MAP_SPARSE 

Sparse mapping table


Function Documentation

OTF2_ErrorCode OTF2_IdMap_AddIdPair ( OTF2_IdMap instance,
uint64_t  localId,
uint64_t  globalId 
)

Adds the given mapping from localId to globalId to the mapping table instance. If the current capacity does not suffice, the data structure is automatically resized.

Note:
If the mapping table operates in dense mapping mode, the parameter localId has to correspond to the next entry in the mapping table.
Parameters:
instanceObject to add the mapping to.
localIdLocal identifier.
globalIdGlobal identifier.
Returns:
OTF2_SUCCESS, or error code.
OTF2_ErrorCode OTF2_IdMap_Clear ( OTF2_IdMap instance)

Removes all entries in the given mapping table instance. It can be used, e.g., to reuse an mapping table object for new input data.

Parameters:
instanceObject to remove entries from.
Returns:
OTF2_SUCCESS, or error code.
OTF2_IdMap* OTF2_IdMap_Create ( OTF2_IdMapMode  mode,
uint64_t  capacity 
)

Creates and returns a new instance of OTF2_IdMap with the given mode and initial capacity. If the memory allocation request can not be fulfilled, NULL is returned.

Parameters:
modeMapping mode.
capacityInitial capacity.
Returns:
Pointer to new instance or NULL if memory request couldn't be fulfilled.
OTF2_IdMap* OTF2_IdMap_CreateFromUint32Array ( uint64_t  length,
const uint32_t *  mappings,
bool  optimizeSize 
)

Creates and returns a new instance of OTF2_IdMap from the array given by mappings.

Same as OTF2_IdMap_CreateFromUint64Array, excpet from a uint32_t array.

Parameters:
lengthNumber of elements in the mappings array.
mappingsArray with a dense mapping.
optimizeSizeCreates a SPARSE mapping, if the number of non- identities is less than half the array length.
Returns:
Pointer to new instance or NULL if memory request couldn't be fulfilled.
OTF2_IdMap* OTF2_IdMap_CreateFromUint64Array ( uint64_t  length,
const uint64_t *  mappings,
bool  optimizeSize 
)

Creates and returns a new instance of OTF2_IdMap from the array given by mappings.

This creates always a DENSE mapping if optimizeSize is false. If it is true, it creates a SPARSE mapping, if the number of non-identitiy entries in the mappings array (ie. mapping[ i ] != i) is less than half the length.

Returns NULL when optimizeSize is true and the number of non-identitiy entries equals zero, ie. the given map is the identity map.

Parameters:
lengthNumber of elements in the mappings array.
mappingsArray with a dense mapping.
optimizeSizeCreates a SPARSE mapping, if the number of non- identities is less than half the array length.
Returns:
Pointer to new instance or NULL if memory request couldn't be fulfilled.
void OTF2_IdMap_Free ( OTF2_IdMap instance)

Destroys the given instance of OTF2_IdMap and releases the allocated memory.

Parameters:
instanceObject to be freed
OTF2_ErrorCode OTF2_IdMap_GetGlobalId ( const OTF2_IdMap instance,
uint64_t  localId,
uint64_t *  globalId 
)

Maps the given localId to the global id ansd store it in the starge provide by globalId.

If the given localId is not in the mapping, sets globalId to the localId.

Parameters:
instanceObject to add the mapping to.
localIdLocal identifier.
[out]globalIdGlobal identifier.
Returns:
OTF2_SUCCESS, or error code.
OTF2_ErrorCode OTF2_IdMap_GetMode ( const OTF2_IdMap instance,
OTF2_IdMapMode mode 
)

Returns the identifier mapping mode (dense/sparse) used for the given mapping table instance.

Parameters:
instanceQueried object.
[out]modeIdentifier mapping mode.
Returns:
OTF2_SUCCESS, or error code.
OTF2_ErrorCode OTF2_IdMap_GetSize ( const OTF2_IdMap instance,
uint64_t *  size 
)

Returns the actual number of entries stored in the given OTF2_IdMap instance.

Parameters:
instanceQueried object.
[out]sizeNumber of entries.
Returns:
OTF2_SUCCESS, or error code.
OTF2_ErrorCode OTF2_IdMap_Traverse ( const OTF2_IdMap instance,
OTF2_IdMap_TraverseCallback  callback,
void *  userData 
)

Calls for each mapping pair the callback callback.

Parameters:
instanceObject to add the mapping to.
callbackCallback function which is called for eaach mapping pair.
userDataData which is passed to the callback function.
Returns:
OTF2_SUCCESS, or error code.