1.5.1 (revision 4026)
Typedefs | Functions
otf2/OTF2_Reader.h File Reference

Reading interface for OTF2 archives. More...

#include <stdint.h>
#include <otf2/OTF2_ErrorCodes.h>
#include <otf2/OTF2_Archive.h>

Go to the source code of this file.

Typedefs

typedef struct OTF2_Reader_struct OTF2_Reader
 Keeps all necessary information for the reader.

Functions

OTF2_ErrorCode OTF2_Reader_Close (OTF2_Reader *reader)
 Close a reader handle.
OTF2_ErrorCode OTF2_Reader_CloseDefFiles (OTF2_Reader *reader)
 Closes the local definitions file container.
OTF2_ErrorCode OTF2_Reader_CloseDefReader (OTF2_Reader *reader, OTF2_DefReader *defReader)
 Close a local definition reader.
OTF2_ErrorCode OTF2_Reader_CloseEvtFiles (OTF2_Reader *reader)
 Closes the events file container.
OTF2_ErrorCode OTF2_Reader_CloseEvtReader (OTF2_Reader *reader, OTF2_EvtReader *evtReader)
 Close a local event reader.
OTF2_ErrorCode OTF2_Reader_CloseGlobalDefReader (OTF2_Reader *reader, OTF2_GlobalDefReader *globalDefReader)
 Closes the global definition reader.
OTF2_ErrorCode OTF2_Reader_CloseGlobalEvtReader (OTF2_Reader *reader, OTF2_GlobalEvtReader *globalEvtReader)
 Closes the global event reader.
OTF2_ErrorCode OTF2_Reader_CloseGlobalSnapReader (OTF2_Reader *reader, OTF2_GlobalSnapReader *globalSnapReader)
 Closes the global snapshot reader.
OTF2_ErrorCode OTF2_Reader_CloseMarkerReader (OTF2_Reader *reader, OTF2_MarkerReader *markerReader)
 Closes the marker reader.
OTF2_ErrorCode OTF2_Reader_CloseMarkerWriter (OTF2_Reader *reader, OTF2_MarkerWriter *markerWriter)
 Closes the marker writer.
OTF2_ErrorCode OTF2_Reader_CloseSnapFiles (OTF2_Reader *reader)
 Closes the snapshots file container.
OTF2_ErrorCode OTF2_Reader_CloseSnapReader (OTF2_Reader *reader, OTF2_SnapReader *snapReader)
 Close a local snapshot reader.
OTF2_ErrorCode OTF2_Reader_CloseThumbReader (OTF2_Reader *reader, OTF2_ThumbReader *thumbReader)
 Close an opened thumbnail reader.
OTF2_ErrorCode OTF2_Reader_GetBoolProperty (OTF2_Reader *reader, const char *name, bool *value)
 Get the value of the named trace file property as boolean.
OTF2_ErrorCode OTF2_Reader_GetChunkSize (OTF2_Reader *reader, uint64_t *chunkSizeEvents, uint64_t *chunkSizeDefinitions)
 Get event and definition chunk sizes.
OTF2_ErrorCode OTF2_Reader_GetCompression (OTF2_Reader *reader, OTF2_Compression *compression)
 Get copression mode.
OTF2_ErrorCode OTF2_Reader_GetCreator (OTF2_Reader *reader, char **creator)
 Get creator name.
OTF2_DefReaderOTF2_Reader_GetDefReader (OTF2_Reader *reader, OTF2_LocationRef location)
 Get a local definition reader.
OTF2_ErrorCode OTF2_Reader_GetDescription (OTF2_Reader *reader, char **description)
 Get description.
OTF2_EvtReaderOTF2_Reader_GetEvtReader (OTF2_Reader *reader, OTF2_LocationRef location)
 Get a local event reader.
OTF2_ErrorCode OTF2_Reader_GetFileSubstrate (OTF2_Reader *reader, OTF2_FileSubstrate *substrate)
 Get file substrate information.
OTF2_GlobalDefReaderOTF2_Reader_GetGlobalDefReader (OTF2_Reader *reader)
 Get a global definition reader.
OTF2_GlobalEvtReaderOTF2_Reader_GetGlobalEvtReader (OTF2_Reader *reader)
 Get a global event reader.
OTF2_GlobalSnapReaderOTF2_Reader_GetGlobalSnapReader (OTF2_Reader *reader)
 Get a global snap reader.
OTF2_ErrorCode OTF2_Reader_GetMachineName (OTF2_Reader *reader, char **machineName)
 Get machine name.
OTF2_MarkerReaderOTF2_Reader_GetMarkerReader (OTF2_Reader *reader)
 Get a marker reader.
OTF2_MarkerWriterOTF2_Reader_GetMarkerWriter (OTF2_Reader *reader)
 Get a marker writer.
OTF2_ErrorCode OTF2_Reader_GetNumberOfGlobalDefinitions (OTF2_Reader *reader, uint64_t *numberOfDefinitions)
 Get number of global definitions.
OTF2_ErrorCode OTF2_Reader_GetNumberOfLocations (OTF2_Reader *reader, uint64_t *numberOfLocations)
 Get number of locations.
OTF2_ErrorCode OTF2_Reader_GetNumberOfSnapshots (OTF2_Reader *reader, uint32_t *number)
 Get number of snapshots.
OTF2_ErrorCode OTF2_Reader_GetNumberOfThumbnails (OTF2_Reader *reader, uint32_t *number)
 Get number of thumbs.
OTF2_ErrorCode OTF2_Reader_GetProperty (OTF2_Reader *reader, const char *name, char **value)
 Get the value of the named trace file property.
OTF2_ErrorCode OTF2_Reader_GetPropertyNames (OTF2_Reader *reader, uint32_t *numberOfProperties, char ***names)
 Get the names of all trace file properties.
OTF2_SnapReaderOTF2_Reader_GetSnapReader (OTF2_Reader *reader, OTF2_LocationRef location)
 Get a local snapshot reader.
OTF2_ThumbReaderOTF2_Reader_GetThumbReader (OTF2_Reader *reader, uint32_t number)
 Get a thumb reader.
OTF2_ErrorCode OTF2_Reader_GetTraceId (OTF2_Reader *reader, uint64_t *id)
 Get the identifier of the trace file.
OTF2_ErrorCode OTF2_Reader_GetVersion (OTF2_Reader *reader, uint8_t *major, uint8_t *minor, uint8_t *bugfix)
 Get OTF2 version.
OTF2_ErrorCode OTF2_Reader_HasGlobalEvent (OTF2_Reader *reader, OTF2_GlobalEvtReader *evtReader, int *flag)
 Has the global event reader at least one more event to deliver.
OTF2_ReaderOTF2_Reader_Open (const char *anchorFilePath)
 Create a new reader handle.
OTF2_ErrorCode OTF2_Reader_OpenDefFiles (OTF2_Reader *reader)
 Open the local definitions file container.
OTF2_ErrorCode OTF2_Reader_OpenEvtFiles (OTF2_Reader *reader)
 Open the events file container.
OTF2_ErrorCode OTF2_Reader_OpenSnapFiles (OTF2_Reader *reader)
 Open the snapshots file container.
OTF2_ErrorCode OTF2_Reader_ReadAllGlobalDefinitions (OTF2_Reader *reader, OTF2_GlobalDefReader *defReader, uint64_t *definitionsRead)
 Read all definitions via a global definition reader.
OTF2_ErrorCode OTF2_Reader_ReadAllGlobalEvents (OTF2_Reader *reader, OTF2_GlobalEvtReader *evtReader, uint64_t *eventsRead)
 Read all events via a global event reader.
OTF2_ErrorCode OTF2_Reader_ReadAllGlobalSnapshots (OTF2_Reader *reader, OTF2_GlobalSnapReader *snapReader, uint64_t *recordsRead)
 Read all records via a global snapshot reader.
OTF2_ErrorCode OTF2_Reader_ReadAllLocalDefinitions (OTF2_Reader *reader, OTF2_DefReader *defReader, uint64_t *definitionsRead)
 Read all definitions via a local definition reader.
OTF2_ErrorCode OTF2_Reader_ReadAllLocalEvents (OTF2_Reader *reader, OTF2_EvtReader *evtReader, uint64_t *eventsRead)
 Read all events via a local event reader.
OTF2_ErrorCode OTF2_Reader_ReadAllLocalSnapshots (OTF2_Reader *reader, OTF2_SnapReader *snapReader, uint64_t *recordsRead)
 Read all records via a local snapshot reader.
OTF2_ErrorCode OTF2_Reader_ReadAllMarkers (OTF2_Reader *reader, OTF2_MarkerReader *markerReader, uint64_t *markersRead)
 Read all markers via a marker reader.
OTF2_ErrorCode OTF2_Reader_ReadGlobalDefinitions (OTF2_Reader *reader, OTF2_GlobalDefReader *defReader, uint64_t definitionsToRead, uint64_t *definitionsRead)
 Read a given number of definitions via a global definition reader.
OTF2_ErrorCode OTF2_Reader_ReadGlobalEvent (OTF2_Reader *reader, OTF2_GlobalEvtReader *evtReader)
 Read an event via a global event reader.
OTF2_ErrorCode OTF2_Reader_ReadGlobalEvents (OTF2_Reader *reader, OTF2_GlobalEvtReader *evtReader, uint64_t eventsToRead, uint64_t *eventsRead)
 Read a given number of events via a global event reader.
OTF2_ErrorCode OTF2_Reader_ReadGlobalSnapshots (OTF2_Reader *reader, OTF2_GlobalSnapReader *snapReader, uint64_t recordsToRead, uint64_t *recordsRead)
 Read a given number of records via a global snapshot reader.
OTF2_ErrorCode OTF2_Reader_ReadLocalDefinitions (OTF2_Reader *reader, OTF2_DefReader *defReader, uint64_t definitionsToRead, uint64_t *definitionsRead)
 Read a given number of definitions via a local definition reader.
OTF2_ErrorCode OTF2_Reader_ReadLocalEvents (OTF2_Reader *reader, OTF2_EvtReader *evtReader, uint64_t eventsToRead, uint64_t *eventsRead)
 Read a given number of events via a local event reader.
OTF2_ErrorCode OTF2_Reader_ReadLocalEventsBackward (OTF2_Reader *reader, OTF2_EvtReader *evtReader, uint64_t eventsToRead, uint64_t *eventsRead)
 Read a given number of events via a local event reader backwards.
OTF2_ErrorCode OTF2_Reader_ReadLocalSnapshots (OTF2_Reader *reader, OTF2_SnapReader *snapReader, uint64_t recordsToRead, uint64_t *recordsRead)
 Read a given number of records via a local snapshot reader.
OTF2_ErrorCode OTF2_Reader_ReadMarkers (OTF2_Reader *reader, OTF2_MarkerReader *markerReader, uint64_t markersToRead, uint64_t *markersRead)
 Read a given number of markers via a marker reader.
OTF2_ErrorCode OTF2_Reader_RegisterDefCallbacks (OTF2_Reader *reader, OTF2_DefReader *defReader, const OTF2_DefReaderCallbacks *callbacks, void *userData)
 Register local definition reader callbacks.
OTF2_ErrorCode OTF2_Reader_RegisterEvtCallbacks (OTF2_Reader *reader, OTF2_EvtReader *evtReader, const OTF2_EvtReaderCallbacks *callbacks, void *userData)
 Register event reader callbacks.
OTF2_ErrorCode OTF2_Reader_RegisterGlobalDefCallbacks (OTF2_Reader *reader, OTF2_GlobalDefReader *defReader, const OTF2_GlobalDefReaderCallbacks *callbacks, void *userData)
 Register global definition reader callbacks.
OTF2_ErrorCode OTF2_Reader_RegisterGlobalEvtCallbacks (OTF2_Reader *reader, OTF2_GlobalEvtReader *evtReader, const OTF2_GlobalEvtReaderCallbacks *callbacks, void *userData)
 Register global event reader callbacks.
OTF2_ErrorCode OTF2_Reader_RegisterGlobalSnapCallbacks (OTF2_Reader *reader, OTF2_GlobalSnapReader *evtReader, const OTF2_GlobalSnapReaderCallbacks *callbacks, void *userData)
 Register global event reader callbacks.
OTF2_ErrorCode OTF2_Reader_RegisterMarkerCallbacks (OTF2_Reader *reader, OTF2_MarkerReader *markerReader, const OTF2_MarkerReaderCallbacks *callbacks, void *userData)
 Register marker reader callbacks.
OTF2_ErrorCode OTF2_Reader_RegisterSnapCallbacks (OTF2_Reader *reader, OTF2_SnapReader *snapReader, const OTF2_SnapReaderCallbacks *callbacks, void *userData)
 Register snapshot event reader callbacks.
OTF2_ErrorCode OTF2_Reader_SelectLocation (OTF2_Reader *reader, OTF2_LocationRef location)
 Select a location to be read.
OTF2_ErrorCode OTF2_Reader_SetCollectiveCallbacks (OTF2_Reader *reader, const OTF2_CollectiveCallbacks *collectiveCallbacks, void *collectiveData, OTF2_CollectiveContext *globalCommContext, OTF2_CollectiveContext *localCommContext)
 Set the collective callbacks for the reader.
OTF2_ErrorCode OTF2_Reader_SetHint (OTF2_Reader *reader, OTF2_Hint hint, void *value)
 Set the hint in the reader to the given value.
OTF2_ErrorCode OTF2_Reader_SetLockingCallbacks (OTF2_Reader *reader, const OTF2_LockingCallbacks *lockingCallbacks, void *lockingData)
 Set the locking callbacks for the reader.
OTF2_ErrorCode OTF2_Reader_SetSerialCollectiveCallbacks (OTF2_Reader *reader)
 Convenient function to set the collective callbacks to an serial implementation.

Detailed Description

Reading interface for OTF2 archives.


Function Documentation

OTF2_ErrorCode OTF2_Reader_Close ( OTF2_Reader reader)

Close a reader handle.

Closes a reader handle and releases all associated handles. Does nothing if NULL is provided.

Parameters:
readerReader handle.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_ErrorCode OTF2_Reader_CloseDefFiles ( OTF2_Reader reader)

Closes the local definitions file container.

This function is an collective operation.

All previously used local definition readers must be closed before this call.

Parameters:
readerReader handle.
Since:
Version 1.3
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_ErrorCode OTF2_Reader_CloseDefReader ( OTF2_Reader reader,
OTF2_DefReader defReader 
)

Close a local definition reader.

Parameters:
readerValid reader handle.
defReaderDefinition reader to be closed.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_ErrorCode OTF2_Reader_CloseEvtFiles ( OTF2_Reader reader)

Closes the events file container.

All previously used event readers must be closed before this call.

This function is an collective operation.

Parameters:
readerReader handle.
Since:
Version 1.3
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_ErrorCode OTF2_Reader_CloseEvtReader ( OTF2_Reader reader,
OTF2_EvtReader evtReader 
)

Close a local event reader.

Parameters:
readerValid reader handle.
evtReaderEvent reader to be closed.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_CloseGlobalDefReader ( OTF2_Reader reader,
OTF2_GlobalDefReader globalDefReader 
)

Closes the global definition reader.

Parameters:
readerValid reader handle.
globalDefReaderThe global definition reader.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_CloseGlobalEvtReader ( OTF2_Reader reader,
OTF2_GlobalEvtReader globalEvtReader 
)

Closes the global event reader.

This closes also all local event readers.

Parameters:
readerValid reader handle.
globalEvtReaderThe global event reader.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_ErrorCode OTF2_Reader_CloseGlobalSnapReader ( OTF2_Reader reader,
OTF2_GlobalSnapReader globalSnapReader 
)

Closes the global snapshot reader.

Parameters:
readerValid reader handle.
globalSnapReaderThe global snapshot reader.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Since:
Version 1.2
OTF2_ErrorCode OTF2_Reader_CloseMarkerReader ( OTF2_Reader reader,
OTF2_MarkerReader markerReader 
)

Closes the marker reader.

Parameters:
readerValid reader handle.
markerReaderThe marker reader.
Since:
Version 1.2
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_CloseMarkerWriter ( OTF2_Reader reader,
OTF2_MarkerWriter markerWriter 
)

Closes the marker writer.

Parameters:
readerValid reader handle.
markerWriterThe marker writer.
Since:
Version 1.2
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_CloseSnapFiles ( OTF2_Reader reader)

Closes the snapshots file container.

This function is an collective operation.

All previously used snapshot readers must be closed before this call.

Parameters:
readerReader handle.
Since:
Version 1.3
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_CloseSnapReader ( OTF2_Reader reader,
OTF2_SnapReader snapReader 
)

Close a local snapshot reader.

Parameters:
readerValid reader handle.
snapReadersnapshot reader to be closed.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Since:
Version 1.2
OTF2_ErrorCode OTF2_Reader_CloseThumbReader ( OTF2_Reader reader,
OTF2_ThumbReader thumbReader 
)

Close an opened thumbnail reader.

Parameters:
readerReader handle.
thumbReaderThumbn reader handle to be closed.
Since:
Version 1.2
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_GetBoolProperty ( OTF2_Reader reader,
const char *  name,
bool *  value 
)

Get the value of the named trace file property as boolean.

Parameters:
readerReader handle.
nameName of the property.
[out]valueReturned boolean value of the property.
Returns:
OTF2_SUCCESS

if successful

OTF2_ERROR_PROPERTY_NOT_FOUND

if the named property was not found

OTF2_ERROR_PROPERTY_VALUE_INVALID

if the value could not be interpreted as an boolean value

OTF2_ErrorCode OTF2_Reader_GetChunkSize ( OTF2_Reader reader,
uint64_t *  chunkSizeEvents,
uint64_t *  chunkSizeDefinitions 
)

Get event and definition chunk sizes.

Parameters:
readerReader handle.
[out]chunkSizeEventsReturned size of event chunks
[out]chunkSizeDefinitionsReturned size of definition chunks.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_GetCompression ( OTF2_Reader reader,
OTF2_Compression compression 
)

Get copression mode.

Parameters:
readerReader handle.
[out]compressionReturned compression mode.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_GetCreator ( OTF2_Reader reader,
char **  creator 
)

Get creator name.

Parameters:
readerReader handle.
[out]creatorReturned creator. Allocated with malloc.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_DefReader* OTF2_Reader_GetDefReader ( OTF2_Reader reader,
OTF2_LocationRef  location 
)

Get a local definition reader.

Parameters:
readerValid reader handle.
locationLocation ID for the requested local reader.
Returns:
Returns a handle to the local definition reader if successful, NULL otherwise.
Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_ErrorCode OTF2_Reader_GetDescription ( OTF2_Reader reader,
char **  description 
)

Get description.

Parameters:
readerReader handle.
[out]descriptionReturned description. Allocated with malloc.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_EvtReader* OTF2_Reader_GetEvtReader ( OTF2_Reader reader,
OTF2_LocationRef  location 
)

Get a local event reader.

Parameters:
readerValid reader handle.
locationLocation ID for the requested local reader.
Returns:
Returns a handle to the local event reader if successful, NULL otherwise.
Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_ErrorCode OTF2_Reader_GetFileSubstrate ( OTF2_Reader reader,
OTF2_FileSubstrate substrate 
)

Get file substrate information.

Parameters:
readerReader handle.
[out]substrateReturned file substrate.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_GlobalDefReader* OTF2_Reader_GetGlobalDefReader ( OTF2_Reader reader)

Get a global definition reader.

Parameters:
readerValid reader handle.
Returns:
Returns a handle to the global definition reader if successful, NULL otherwise.
Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_GlobalEvtReader* OTF2_Reader_GetGlobalEvtReader ( OTF2_Reader reader)

Get a global event reader.

Parameters:
readerValid reader handle.
Returns:
Returns a handle to the global event reader if successful, NULL otherwise.
Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_GlobalSnapReader* OTF2_Reader_GetGlobalSnapReader ( OTF2_Reader reader)

Get a global snap reader.

Parameters:
readerValid reader handle.
Returns:
Returns a handle to the global snap reader if successful, NULL otherwise.
Since:
Version 1.2
OTF2_ErrorCode OTF2_Reader_GetMachineName ( OTF2_Reader reader,
char **  machineName 
)

Get machine name.

Parameters:
readerReader handle.
[out]machineNameReturned machine name. Allocated with malloc.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_MarkerReader* OTF2_Reader_GetMarkerReader ( OTF2_Reader reader)

Get a marker reader.

Parameters:
readerValid reader handle.
Since:
Version 1.2
Returns:
Returns a handle to the marker reader if successful, NULL otherwise.
OTF2_MarkerWriter* OTF2_Reader_GetMarkerWriter ( OTF2_Reader reader)

Get a marker writer.

Parameters:
readerValid reader handle.
Since:
Version 1.2
Returns:
Returns a handle to the marker writer if successful, NULL otherwise.
OTF2_ErrorCode OTF2_Reader_GetNumberOfGlobalDefinitions ( OTF2_Reader reader,
uint64_t *  numberOfDefinitions 
)

Get number of global definitions.

Parameters:
readerReader handle.
[out]numberOfDefinitionsReturned number of global definitions.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_GetNumberOfLocations ( OTF2_Reader reader,
uint64_t *  numberOfLocations 
)

Get number of locations.

Parameters:
readerReader handle.
[out]numberOfLocationsReturned number of locations.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_ErrorCode OTF2_Reader_GetNumberOfSnapshots ( OTF2_Reader reader,
uint32_t *  number 
)

Get number of snapshots.

Parameters:
readerReader handle.
[out]numberReturned number of snapshots.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Since:
Version 1.2
OTF2_ErrorCode OTF2_Reader_GetNumberOfThumbnails ( OTF2_Reader reader,
uint32_t *  number 
)

Get number of thumbs.

Parameters:
readerReader handle.
[out]numberReturned number of thumbs.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Since:
Version 1.2
OTF2_ErrorCode OTF2_Reader_GetProperty ( OTF2_Reader reader,
const char *  name,
char **  value 
)

Get the value of the named trace file property.

Parameters:
readerReader handle.
nameName of the property.
[out]valueReturned value of the property. Allocated with malloc.
Returns:
OTF2_SUCCESS

if successful

OTF2_ERROR_PROPERTY_NOT_FOUND

if the named property was not found

OTF2_ErrorCode OTF2_Reader_GetPropertyNames ( OTF2_Reader reader,
uint32_t *  numberOfProperties,
char ***  names 
)

Get the names of all trace file properties.

Parameters:
readerReader handle.
[out]numberOfPropertiesReturned number of trace file properties.
[out]namesReturned list of property names. Allocated with malloc. To release memory, just pass *names to free.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_SnapReader* OTF2_Reader_GetSnapReader ( OTF2_Reader reader,
OTF2_LocationRef  location 
)

Get a local snapshot reader.

Parameters:
readerValid reader handle.
locationLocation ID for the requested local reader.
Returns:
Returns a handle to the local event reader if successful, NULL otherwise.
Since:
Version 1.2
OTF2_ThumbReader* OTF2_Reader_GetThumbReader ( OTF2_Reader reader,
uint32_t  number 
)

Get a thumb reader.

Parameters:
readerReader handle.
numberThumbnail number.
Since:
Version 1.2
Returns:
Returns a global definition writer handle if successful, NULL if an error occurs.
OTF2_ErrorCode OTF2_Reader_GetTraceId ( OTF2_Reader reader,
uint64_t *  id 
)

Get the identifier of the trace file.

Parameters:
readerReader handle.
[out]idTrace identifier.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_GetVersion ( OTF2_Reader reader,
uint8_t *  major,
uint8_t *  minor,
uint8_t *  bugfix 
)

Get OTF2 version.

Parameters:
readerValid reader handle.
[out]majorMajor version.
[out]minorMinor version.
[out]bugfixBugfix revision.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_HasGlobalEvent ( OTF2_Reader reader,
OTF2_GlobalEvtReader evtReader,
int *  flag 
)

Has the global event reader at least one more event to deliver.

Parameters:
readerGlobal event reader handle.
evtReaderGlobal event reader handle.
[out]flagIn case of success, the flag will be set to 1 when there is at least more more event to read. To 0 if not. Otherwise the value is undefined.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_Reader* OTF2_Reader_Open ( const char *  anchorFilePath)

Create a new reader handle.

Creates a new reader handle, opens an according archive handle, and calls a routine to register all necessary function pointers.

Parameters:
anchorFilePathPath to the anchor file e.g. 'trace.otf2'. This can be a relative as well as an absolute path.
Returns:
Returns a handle to the reader if successful, NULL otherwise.
Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_ErrorCode OTF2_Reader_OpenDefFiles ( OTF2_Reader reader)

Open the local definitions file container.

This function is an collective operation.

Parameters:
readerReader handle.
Since:
Version 1.3
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_ErrorCode OTF2_Reader_OpenEvtFiles ( OTF2_Reader reader)

Open the events file container.

This function is an collective operation.

Parameters:
readerReader handle.
Since:
Version 1.3
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_ErrorCode OTF2_Reader_OpenSnapFiles ( OTF2_Reader reader)

Open the snapshots file container.

This function is an collective operation.

Parameters:
readerReader handle.
Since:
Version 1.3
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_ReadAllGlobalDefinitions ( OTF2_Reader reader,
OTF2_GlobalDefReader defReader,
uint64_t *  definitionsRead 
)

Read all definitions via a global definition reader.

Parameters:
readerReader handle.
defReaderGlobal definition reader handle.
[out]definitionsReadReturn pointer to the number of definitions actually read.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_ErrorCode OTF2_Reader_ReadAllGlobalEvents ( OTF2_Reader reader,
OTF2_GlobalEvtReader evtReader,
uint64_t *  eventsRead 
)

Read all events via a global event reader.

Parameters:
readerReader handle.
evtReaderGlobal event reader handle.
[out]eventsReadReturn pointer to the number of events actually read.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_ErrorCode OTF2_Reader_ReadAllGlobalSnapshots ( OTF2_Reader reader,
OTF2_GlobalSnapReader snapReader,
uint64_t *  recordsRead 
)

Read all records via a global snapshot reader.

Parameters:
readerReader handle.
snapReaderGlobal snapshot reader handle.
[out]recordsReadReturn pointer to the number of records
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Since:
Version 1.2
OTF2_ErrorCode OTF2_Reader_ReadAllLocalDefinitions ( OTF2_Reader reader,
OTF2_DefReader defReader,
uint64_t *  definitionsRead 
)

Read all definitions via a local definition reader.

Parameters:
readerReader handle.
defReaderLocal definition reader handle.
[out]definitionsReadReturn pointer to the number of definitions actually read.
Returns:
OTF2_SUCCESS

if successful

OTF2_ERROR_INTERRUPTED_BY_CALLBACK

if an user supplied callback returned OTF2_CALLBACK_INTERRUPT

OTF2_ERROR_DUPLICATE_MAPPING_TABLE

if an duplicate mapping table definition was read

otherwise

the error code

Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_ErrorCode OTF2_Reader_ReadAllLocalEvents ( OTF2_Reader reader,
OTF2_EvtReader evtReader,
uint64_t *  eventsRead 
)

Read all events via a local event reader.

Parameters:
readerReader handle.
evtReaderLocal event reader handle.
[out]eventsReadReturn pointer to the number of events actually read.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_ReadAllLocalSnapshots ( OTF2_Reader reader,
OTF2_SnapReader snapReader,
uint64_t *  recordsRead 
)

Read all records via a local snapshot reader.

Parameters:
readerReader handle.
snapReaderLocal snapshot reader handle.
[out]recordsReadReturn pointer to the number of records
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Since:
Version 1.2
OTF2_ErrorCode OTF2_Reader_ReadAllMarkers ( OTF2_Reader reader,
OTF2_MarkerReader markerReader,
uint64_t *  markersRead 
)

Read all markers via a marker reader.

Parameters:
readerReader handle.
markerReaderMarker reader handle.
[out]markersReadReturn pointer to the number of markers actually read.
Since:
Version 1.2
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_ReadGlobalDefinitions ( OTF2_Reader reader,
OTF2_GlobalDefReader defReader,
uint64_t  definitionsToRead,
uint64_t *  definitionsRead 
)

Read a given number of definitions via a global definition reader.

Parameters:
readerReader handle.
defReaderGlobal definition reader handle.
definitionsToReadNumber definitions to be read.
[out]definitionsReadReturn pointer to the number of definitions actually read.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_ReadGlobalEvent ( OTF2_Reader reader,
OTF2_GlobalEvtReader evtReader 
)

Read an event via a global event reader.

Parameters:
readerReader handle.
evtReaderGlobal event reader handle.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_ReadGlobalEvents ( OTF2_Reader reader,
OTF2_GlobalEvtReader evtReader,
uint64_t  eventsToRead,
uint64_t *  eventsRead 
)

Read a given number of events via a global event reader.

Parameters:
readerReader handle.
evtReaderGlobal event reader handle.
eventsToReadNumber events to be read.
[out]eventsReadReturn pointer to the number of events actually read.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_ReadGlobalSnapshots ( OTF2_Reader reader,
OTF2_GlobalSnapReader snapReader,
uint64_t  recordsToRead,
uint64_t *  recordsRead 
)

Read a given number of records via a global snapshot reader.

Parameters:
readerReader handle.
snapReaderGlobal snapshot reader handle.
recordsToReadNumber records to be read.
[out]recordsReadReturn pointer to the number of records actually read.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Since:
Version 1.2
OTF2_ErrorCode OTF2_Reader_ReadLocalDefinitions ( OTF2_Reader reader,
OTF2_DefReader defReader,
uint64_t  definitionsToRead,
uint64_t *  definitionsRead 
)

Read a given number of definitions via a local definition reader.

Parameters:
readerReader handle.
defReaderLocal definition reader handle.
definitionsToReadNumber definitions to be read.
[out]definitionsReadReturn pointer to the number of definitions actually read.
Returns:
OTF2_SUCCESS

if successful

OTF2_ERROR_INTERRUPTED_BY_CALLBACK

if an user supplied callback returned OTF2_CALLBACK_INTERRUPT

OTF2_ERROR_DUPLICATE_MAPPING_TABLE

if an duplicate mapping table definition was read

otherwise

the error code

OTF2_ErrorCode OTF2_Reader_ReadLocalEvents ( OTF2_Reader reader,
OTF2_EvtReader evtReader,
uint64_t  eventsToRead,
uint64_t *  eventsRead 
)

Read a given number of events via a local event reader.

Parameters:
readerReader handle.
evtReaderLocal event reader handle.
eventsToReadNumber events to be read.
eventsReadReturn pointer to the number of events actually read.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_ReadLocalEventsBackward ( OTF2_Reader reader,
OTF2_EvtReader evtReader,
uint64_t  eventsToRead,
uint64_t *  eventsRead 
)

Read a given number of events via a local event reader backwards.

Parameters:
readerReader handle.
evtReaderLocal event reader handle.
eventsToReadNumber events to be read.
[out]eventsReadReturn pointer to the number of events actually read.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_ReadLocalSnapshots ( OTF2_Reader reader,
OTF2_SnapReader snapReader,
uint64_t  recordsToRead,
uint64_t *  recordsRead 
)

Read a given number of records via a local snapshot reader.

Parameters:
readerReader handle.
snapReaderLocal snapshot reader handle.
recordsToReadNumber records to be read.
recordsReadReturn pointer to the number of records actually read.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Since:
Version 1.2
OTF2_ErrorCode OTF2_Reader_ReadMarkers ( OTF2_Reader reader,
OTF2_MarkerReader markerReader,
uint64_t  markersToRead,
uint64_t *  markersRead 
)

Read a given number of markers via a marker reader.

Parameters:
readerReader handle.
markerReaderMarker reader handle.
markersToReadNumber markers to be read.
[out]markersReadReturn pointer to the number of markers actually read.
Since:
Version 1.2
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_RegisterDefCallbacks ( OTF2_Reader reader,
OTF2_DefReader defReader,
const OTF2_DefReaderCallbacks callbacks,
void *  userData 
)

Register local definition reader callbacks.

Parameters:
readerOTF2_Reader handle.
defReaderLocal definition reader handle.
callbacksCallbacks for the local definition readers.
userDataAddition user data.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_RegisterEvtCallbacks ( OTF2_Reader reader,
OTF2_EvtReader evtReader,
const OTF2_EvtReaderCallbacks callbacks,
void *  userData 
)

Register event reader callbacks.

Parameters:
readerOTF2_Reader handle.
evtReaderLocal event reader handle.
callbacksCallbacks for the event readers.
userDataAddition user data.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_RegisterGlobalDefCallbacks ( OTF2_Reader reader,
OTF2_GlobalDefReader defReader,
const OTF2_GlobalDefReaderCallbacks callbacks,
void *  userData 
)

Register global definition reader callbacks.

Parameters:
readerOTF2_Reader handle.
defReaderGlobal definition reader handle.
callbacksCallbacks for the global definition readers.
userDataAddition user data.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_ErrorCode OTF2_Reader_RegisterGlobalEvtCallbacks ( OTF2_Reader reader,
OTF2_GlobalEvtReader evtReader,
const OTF2_GlobalEvtReaderCallbacks callbacks,
void *  userData 
)

Register global event reader callbacks.

Parameters:
readerOTF2_Reader handle.
evtReaderGlobal event reader handle.
callbacksCallbacks for the global event reader.
userDataAddition user data.
Returns:
Returns OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_ErrorCode OTF2_Reader_RegisterGlobalSnapCallbacks ( OTF2_Reader reader,
OTF2_GlobalSnapReader evtReader,
const OTF2_GlobalSnapReaderCallbacks callbacks,
void *  userData 
)

Register global event reader callbacks.

Parameters:
readerOTF2_Reader handle.
evtReaderGlobal event reader handle.
callbacksCallbacks for the global event reader.
userDataAddition user data.
Since:
Version 1.2
Returns:
Returns OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_RegisterMarkerCallbacks ( OTF2_Reader reader,
OTF2_MarkerReader markerReader,
const OTF2_MarkerReaderCallbacks callbacks,
void *  userData 
)

Register marker reader callbacks.

Parameters:
readerOTF2_Reader handle.
markerReaderMarker reader handle.
callbacksCallbacks for the marker reader.
userDataAddition user data.
Since:
Version 1.2
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_RegisterSnapCallbacks ( OTF2_Reader reader,
OTF2_SnapReader snapReader,
const OTF2_SnapReaderCallbacks callbacks,
void *  userData 
)

Register snapshot event reader callbacks.

Parameters:
readerOTF2_Reader handle.
snapReaderLocal snap reader handle.
callbacksCallbacks for the event readers.
userDataAddition user data.
Since:
Version 1.2
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_SelectLocation ( OTF2_Reader reader,
OTF2_LocationRef  location 
)

Select a location to be read.

Parameters:
readerReader handle.
locationLocation ID.
Since:
Version 1.3
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.
OTF2_ErrorCode OTF2_Reader_SetCollectiveCallbacks ( OTF2_Reader reader,
const OTF2_CollectiveCallbacks collectiveCallbacks,
void *  collectiveData,
OTF2_CollectiveContext globalCommContext,
OTF2_CollectiveContext localCommContext 
)

Set the collective callbacks for the reader.

The reader has as the default the serial collectives set.

This function is an collective operation.

Parameters:
readerReader handle.
collectiveCallbacksStruct holding the collective callback functions.
collectiveDataData passed to the collective callbacks in the userData argument.
globalCommContextGlobal communication context.
localCommContextLocal communication context. Unsued in reading mode. A local communication context may be created via the callbacks which fits the one used when the given trace was written.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Reader_SetHint ( OTF2_Reader reader,
OTF2_Hint  hint,
void *  value 
)

Set the hint in the reader to the given value.

Hints can only be set once and only before OTF2 itself uses the hint the first time.

Parameters:
readerReader handle.
hintName of the hint.
valueReference to the hint value.
Since:
Version 1.5
Returns:
OTF2_SUCCESS

if successful

OTF2_ERROR_INVALID_ARGUMENT

in case of NULL pointers for archive or value, or an unknown hint value

OTF2_ERROR_HINT_INVALID

in case the hint is not valid for this handle

OTF2_ERROR_HINT_LOCKED

in case the hint was already set or was queried at least once by the handle

OTF2_ERROR_HINT_INVALID_VALUE

in case the provided value is invalid for this hint

OTF2_ErrorCode OTF2_Reader_SetLockingCallbacks ( OTF2_Reader reader,
const OTF2_LockingCallbacks lockingCallbacks,
void *  lockingData 
)

Set the locking callbacks for the reader.

Can be called any time, but only once. Before this call no thread-safety is guaranteed.

Parameters:
readerReader handle.
lockingCallbacksStruct holding the locking callback functions.
lockingDataData passed to the locking callbacks in the userData argument.
Returns:
OTF2_SUCCESS

if successful

OTF2_ERROR_INVALID_ARGUMENT

in case of NULL pointers for archive or lockingCallbacks, or mandatory callbacks in lockingCallbacks are missing

OTF2_ERROR_INVALID_CALL

in case there were locking callbacks already set

OTF2_ErrorCode OTF2_Reader_SetSerialCollectiveCallbacks ( OTF2_Reader reader)

Convenient function to set the collective callbacks to an serial implementation.

Parameters:
readerReader handle.
Returns:
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_reader_example.c.