3.1-rc3 (revision d9ca08bb)
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 uint8_t OTF2_IdMapMode
 
typedef void(* OTF2_IdMap_TraverseCallback) (uint64_t localId, uint64_t globalId, void *userData)
 Function prototype for use in OTF2_IdMap_Traverse.
 

Enumerations

enum  OTF2_IdMapMode_enum {
  OTF2_ID_MAP_DENSE,
  OTF2_ID_MAP_SPARSE
}
 

Functions

OTF2_IdMapOTF2_IdMap_Create (OTF2_IdMapMode mode, uint64_t capacity)
 
OTF2_IdMapOTF2_IdMap_CreateFromUint64Array (uint64_t length, const uint64_t *mappings, bool optimizeSize)
 
OTF2_IdMapOTF2_IdMap_CreateFromUint32Array (uint64_t length, const uint32_t *mappings, bool optimizeSize)
 
void OTF2_IdMap_Free (OTF2_IdMap *instance)
 
OTF2_ErrorCode OTF2_IdMap_GetSize (const OTF2_IdMap *instance, uint64_t *size)
 
OTF2_ErrorCode OTF2_IdMap_GetMode (const OTF2_IdMap *instance, OTF2_IdMapMode *mode)
 
OTF2_ErrorCode OTF2_IdMap_Clear (OTF2_IdMap *instance)
 
OTF2_ErrorCode OTF2_IdMap_AddIdPair (OTF2_IdMap *instance, uint64_t localId, uint64_t globalId)
 
OTF2_ErrorCode OTF2_IdMap_GetGlobalId (const OTF2_IdMap *instance, uint64_t localId, uint64_t *globalId)
 
OTF2_ErrorCode OTF2_IdMap_GetGlobalIdSave (const OTF2_IdMap *instance, uint64_t localId, uint64_t *globalId)
 
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.

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_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 cannot 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_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-identity entries in the mappings array (i.e., mapping[ i ] != i) is less than half the length.

Returns NULL when optimizeSize is true and the number of non-identity entries equals zero, i.e., 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.
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, except 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.
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_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_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_Clear ( OTF2_IdMap instance)

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

Parameters
instanceObject to remove entries from.
Returns
OTF2_SUCCESS, or error code.
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_GetGlobalId ( const OTF2_IdMap instance,
uint64_t  localId,
uint64_t *  globalId 
)

Maps the given localId to the global id and store it in the storage 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_GetGlobalIdSave ( const OTF2_IdMap instance,
uint64_t  localId,
uint64_t *  globalId 
)

Maps the given localId to the global id and store it in the storage provide by globalId.

If the given localId is not in the mapping, returns OTF2_ERROR_INDEX_OUT_OF_BOUNDS.

Parameters
instanceObject to add the mapping to.
localIdLocal identifier.
[out]globalIdGlobal identifier.
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 each mapping pair.
userDataData which is passed to the callback function.
Returns
OTF2_SUCCESS, or error code.