OpenMPI  0.1.1
Handler Interface

In the following, the handler interfaces for all record types are specified. More...

Files

file  OTF_HandlerArray.h
 Provides read access to OTF traces which consist of multiple streams.
 

Functions

int OTF_Handler_DefinitionComment (void *userData, uint32_t stream, const char *comment, OTF_KeyValueList *list)
 Provides a comment record. More...
 
int OTF_Handler_DefTimerResolution (void *userData, uint32_t stream, uint64_t ticksPerSecond, OTF_KeyValueList *list)
 Provides the timer resolution. More...
 
int OTF_Handler_DefProcess (void *userData, uint32_t stream, uint32_t process, const char *name, uint32_t parent, OTF_KeyValueList *list)
 Provides a process definition. More...
 
int OTF_Handler_DefProcessGroup (void *userData, uint32_t stream, uint32_t procGroup, const char *name, uint32_t numberOfProcs, const uint32_t *procs, OTF_KeyValueList *list)
 Provides a process group definition. More...
 
int OTF_Handler_DefAttributeList (void *userData, uint32_t stream, uint32_t attr_token, uint32_t num, OTF_ATTR_TYPE *array, OTF_KeyValueList *list)
 Provides a list of attributes that is assigned to a unique token. More...
 
int OTF_Handler_DefProcessOrGroupAttributes (void *userData, uint32_t stream, uint32_t proc_token, uint32_t attr_token, OTF_KeyValueList *list)
 Provides a process or group attributes definition. More...
 
int OTF_Handler_DefFunction (void *userData, uint32_t stream, uint32_t func, const char *name, uint32_t funcGroup, uint32_t source, OTF_KeyValueList *list)
 Provides a function definition. More...
 
int OTF_Handler_DefFunctionGroup (void *userData, uint32_t stream, uint32_t funcGroup, const char *name, OTF_KeyValueList *list)
 Provides a function group definition. More...
 
int OTF_Handler_DefCollectiveOperation (void *userData, uint32_t stream, uint32_t collOp, const char *name, uint32_t type, OTF_KeyValueList *list)
 Provides a collective operation definition. More...
 
int OTF_Handler_DefCounter (void *userData, uint32_t stream, uint32_t counter, const char *name, uint32_t properties, uint32_t counterGroup, const char *unit, OTF_KeyValueList *list)
 Provides a counter definition. More...
 
int OTF_Handler_DefCounterGroup (void *userData, uint32_t stream, uint32_t counterGroup, const char *name, OTF_KeyValueList *list)
 Provides a counter group definition. More...
 
int OTF_Handler_DefScl (void *userData, uint32_t stream, uint32_t source, uint32_t sourceFile, uint32_t line, OTF_KeyValueList *list)
 Provides a source code location (SCL). More...
 
int OTF_Handler_DefSclFile (void *userData, uint32_t stream, uint32_t sourceFile, const char *name, OTF_KeyValueList *list)
 Provides a source code location (SCL) file. More...
 
int OTF_Handler_DefCreator (void *userData, uint32_t stream, const char *creator, OTF_KeyValueList *list)
 Provides file creator information. More...
 
int OTF_Handler_DefVersion (void *userData, uint32_t stream, uint8_t major, uint8_t minor, uint8_t sub, const char *string, OTF_KeyValueList *list)
 Provides information on the traceĀ“s otf-version. More...
 
int OTF_Handler_DefFile (void *userData, uint32_t stream, uint32_t token, const char *name, uint32_t group, OTF_KeyValueList *list)
 Provides a file definition NOTE: this is experimental. More...
 
int OTF_Handler_DefFileGroup (void *userData, uint32_t stream, uint32_t token, const char *name, OTF_KeyValueList *list)
 Provides a file group definition NOTE: this is experimental. More...
 
int OTF_Handler_DefKeyValue (void *userData, uint32_t stream, uint32_t key, OTF_Type type, const char *name, const char *description, OTF_KeyValueList *list)
 Provides a KeyValue definition. More...
 
int OTF_Handler_DefTimeRange (void *userData, uint32_t stream, uint64_t minTime, uint64_t maxTime, OTF_KeyValueList *list)
 Provides a TimeRange definition. More...
 
int OTF_Handler_DefCounterAssignments (void *userData, uint32_t stream, uint32_t counter, uint32_t number_of_members, const uint32_t *procs_or_groups, OTF_KeyValueList *list)
 Provides a CounterAssignments definition. More...
 
int OTF_Handler_NoOp (void *userData, uint64_t time, uint32_t process, OTF_KeyValueList *list)
 Provides a no-operation event. More...
 
int OTF_Handler_Enter (void *userData, uint64_t time, uint32_t function, uint32_t process, uint32_t source, OTF_KeyValueList *list)
 Provides a function entry event. More...
 
int OTF_Handler_Leave (void *userData, uint64_t time, uint32_t function, uint32_t process, uint32_t source, OTF_KeyValueList *list)
 Provides a function leave event. More...
 
int OTF_Handler_SendMsg (void *userData, uint64_t time, uint32_t sender, uint32_t receiver, uint32_t group, uint32_t type, uint32_t length, uint32_t source, OTF_KeyValueList *list)
 Provides a message send event. More...
 
int OTF_Handler_RecvMsg (void *userData, uint64_t time, uint32_t recvProc, uint32_t sendProc, uint32_t group, uint32_t type, uint32_t length, uint32_t source, OTF_KeyValueList *list)
 Provides a message retrieval event. More...
 
int OTF_Handler_Counter (void *userData, uint64_t time, uint32_t process, uint32_t counter, uint64_t value, OTF_KeyValueList *list)
 Provides a counter measurement. More...
 
int OTF_Handler_CollectiveOperation (void *userData, uint64_t time, uint32_t process, uint32_t collective, uint32_t procGroup, uint32_t rootProc, uint32_t sent, uint32_t received, uint64_t duration, uint32_t source, OTF_KeyValueList *list)
 Provides a collective operation member event. More...
 
int OTF_Handler_BeginCollectiveOperation (void *userData, uint64_t time, uint32_t process, uint32_t collOp, uint64_t matchingId, uint32_t procGroup, uint32_t rootProc, uint64_t sent, uint64_t received, uint32_t scltoken, OTF_KeyValueList *list)
 Provides a begin collective operation member event. More...
 
int OTF_Handler_EndCollectiveOperation (void *userData, uint64_t time, uint32_t process, uint64_t matchingId, OTF_KeyValueList *list)
 Provides an end collective operation member event. More...
 
int OTF_Handler_EventComment (void *userData, uint64_t time, uint32_t process, const char *comment, OTF_KeyValueList *list)
 Provide a comment record. More...
 
int OTF_Handler_BeginProcess (void *userData, uint64_t time, uint32_t process, OTF_KeyValueList *list)
 Provides a process creation event. More...
 
int OTF_Handler_EndProcess (void *userData, uint64_t time, uint32_t process, OTF_KeyValueList *list)
 Provides a process destruction event. More...
 
int OTF_Handler_FileOperation (void *userData, uint64_t time, uint32_t fileid, uint32_t process, uint64_t handleid, uint32_t operation, uint64_t bytes, uint64_t duration, uint32_t source, OTF_KeyValueList *list)
 Provides a file operation event NOTE: this is experimental. More...
 
int OTF_Handler_BeginFileOperation (void *userData, uint64_t time, uint32_t process, uint64_t matchingId, uint32_t scltoken, OTF_KeyValueList *list)
 Write a begin file operation record. More...
 
int OTF_Handler_EndFileOperation (void *userData, uint64_t time, uint32_t process, uint32_t fileid, uint64_t matchingId, uint64_t handleId, uint32_t operation, uint64_t bytes, uint32_t scltoken, OTF_KeyValueList *list)
 Write an end file operation record. More...
 
int OTF_Handler_RMAPut (void *userData, uint64_t time, uint32_t process, uint32_t origin, uint32_t target, uint32_t communicator, uint32_t tag, uint64_t bytes, uint32_t source, OTF_KeyValueList *list)
 Provides a RMA put event - end marker is anticipated on initiating Process. More...
 
int OTF_Handler_RMAPutRemoteEnd (void *userData, uint64_t time, uint32_t process, uint32_t origin, uint32_t target, uint32_t communicator, uint32_t tag, uint64_t bytes, uint32_t source, OTF_KeyValueList *list)
 Provides a RMA put event with remote finalization marker, i.e. More...
 
int OTF_Handler_RMAGet (void *userData, uint64_t time, uint32_t process, uint32_t origin, uint32_t target, uint32_t communicator, uint32_t tag, uint64_t bytes, uint32_t source, OTF_KeyValueList *list)
 Provides a RMA get event - end marker is anticipated on initiating Process. More...
 
int OTF_Handler_RMAEnd (void *userData, uint64_t time, uint32_t process, uint32_t remote, uint32_t communicator, uint32_t tag, uint32_t source, OTF_KeyValueList *list)
 Provide a RMA end event. More...
 
int OTF_Handler_SnapshotComment (void *userData, uint64_t time, uint32_t process, const char *comment, OTF_KeyValueList *list)
 Provides a snapshot comment. More...
 
int OTF_Handler_EnterSnapshot (void *userData, uint64_t time, uint64_t originaltime, uint32_t function, uint32_t process, uint32_t source, OTF_KeyValueList *list)
 provides information about a past function call at the time 'originaltime'. More...
 
int OTF_Handler_SendSnapshot (void *userData, uint64_t time, uint64_t originaltime, uint32_t sender, uint32_t receiver, uint32_t procGroup, uint32_t tag, uint32_t length, uint32_t source, OTF_KeyValueList *list)
 provides information about a past message send operation at the time 'originaltime'. More...
 
int OTF_Handler_OpenFileSnapshot (void *userData, uint64_t time, uint64_t originaltime, uint32_t fileid, uint32_t process, uint64_t handleid, uint32_t source, OTF_KeyValueList *list)
 Provides a snapshot record for opened(and not yet closed) files. More...
 
int OTF_Handler_BeginCollopSnapshot (void *userData, uint64_t time, uint64_t originaltime, uint32_t process, uint32_t collOp, uint64_t matchingId, uint32_t procGroup, uint32_t rootProc, uint64_t sent, uint64_t received, uint32_t scltoken, OTF_KeyValueList *list)
 Provides a snapshot record for unfinished collective operations. More...
 
int OTF_Handler_BeginFileOpSnapshot (void *userData, uint64_t time, uint64_t originaltime, uint32_t process, uint64_t matchingId, uint32_t scltoken, OTF_KeyValueList *list)
 
int OTF_Handler_SummaryComment (void *userData, uint64_t time, uint32_t process, const char *comment, OTF_KeyValueList *list)
 Provides a summary comment. More...
 
int OTF_Handler_FunctionSummary (void *userData, uint64_t time, uint32_t function, uint32_t process, uint64_t invocations, uint64_t exclTime, uint64_t inclTime, OTF_KeyValueList *list)
 Provides summarized information for a given function. More...
 
int OTF_Handler_FunctionGroupSummary (void *userData, uint64_t time, uint32_t funcGroup, uint32_t process, uint64_t invocations, uint64_t exclTime, uint64_t inclTime, OTF_KeyValueList *list)
 Provides summarized information for a given group of functiongroups. More...
 
int OTF_Handler_MessageSummary (void *userData, uint64_t time, uint32_t process, uint32_t peer, uint32_t comm, uint32_t type, uint64_t sentNumber, uint64_t receivedNumber, uint64_t sentBytes, uint64_t receivedBytes, OTF_KeyValueList *list)
 Provides summarized information for a given message type. More...
 
int OTF_Handler_CollopSummary (void *userData, uint64_t time, uint32_t process, uint32_t comm, uint32_t collective, uint64_t sentNumber, uint64_t receivedNumber, uint64_t sentBytes, uint64_t receivedBytes, OTF_KeyValueList *list)
 Provides summarized information for collective operations. More...
 
int OTF_Handler_FileOperationSummary (void *userData, uint64_t time, uint32_t fileid, uint32_t process, uint64_t nopen, uint64_t nclose, uint64_t nread, uint64_t nwrite, uint64_t nseek, uint64_t bytesread, uint64_t byteswrite, OTF_KeyValueList *list)
 Provides summarized information about file operations. More...
 
int OTF_Handler_FileGroupOperationSummary (void *userData, uint64_t time, uint32_t groupid, uint32_t process, uint64_t nopen, uint64_t nclose, uint64_t nread, uint64_t nwrite, uint64_t nseek, uint64_t bytesread, uint64_t byteswrite, OTF_KeyValueList *list)
 Provides summarized information about file operations in a file group. More...
 
int OTF_Handler_UnknownRecord (void *userData, uint64_t time, uint32_t process, const char *record)
 Can be used to handle records which cannot be read. More...
 
int OTF_Handler_DefMarker (void *userData, uint32_t stream, uint32_t token, const char *name, uint32_t type, OTF_KeyValueList *list)
 Define a marker. More...
 
int OTF_Handler_Marker (void *userData, uint64_t time, uint32_t process, uint32_t token, const char *text, OTF_KeyValueList *list)
 Define a marker. More...
 

Detailed Description

In the following, the handler interfaces for all record types are specified.

The signature of callback handler functions is equal to the signature of corresponding record write functions except for the first argument. The first argument common to all callback handler functions is userData – a generic pointer to custom user data. The second common argument to all callback hander functions is stream which identifies the stream where the definition occurred. A stream parameter = 0 indicates a global definition which is the default.

Function Documentation

int OTF_Handler_BeginCollectiveOperation ( void *  userData,
uint64_t  time,
uint32_t  process,
uint32_t  collOp,
uint64_t  matchingId,
uint32_t  procGroup,
uint32_t  rootProc,
uint64_t  sent,
uint64_t  received,
uint32_t  scltoken,
OTF_KeyValueList list 
)

Provides a begin collective operation member event.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime when collective operation was entered by member.
processProcess identifier i.e. collective member.
collOpCollective identifier to be defined with OTF_Writer_writeDefCollectiveOperation().
matchingIdIdentifier for finding the associated end collective event record. It must be unique within this process.
procGroupGroup of processes participating in this collective.
rootProcRoot process if != 0.
sentData volume sent by member or 0.
receivedData volume received by member or 0.
scltokenExplicit source code location or 0.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
1 on success, 0 if an error occurs.
int OTF_Handler_BeginCollopSnapshot ( void *  userData,
uint64_t  time,
uint64_t  originaltime,
uint32_t  process,
uint32_t  collOp,
uint64_t  matchingId,
uint32_t  procGroup,
uint32_t  rootProc,
uint64_t  sent,
uint64_t  received,
uint32_t  scltoken,
OTF_KeyValueList list 
)

Provides a snapshot record for unfinished collective operations.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeCurrent timestamp.
originaltimeTime when the collective operation began.
processProcess identifier.
collOpCollective identifier to be defined with OTF_Writer_writeDefCollectiveOperation().
matchingIdIdentifier for finding the associated end collective event record. It must be unique within this procGroup.
procGroupGroup of processes participating in this collective.
rootProcRoot process if != 0.
sentData volume sent by member or 0.
receivedData volume received by member or 0.
scltokenOptional reference to source code.
listPointer to an OTF_KeyValueList() that contains individual data.
int OTF_Handler_BeginFileOperation ( void *  userData,
uint64_t  time,
uint32_t  process,
uint64_t  matchingId,
uint32_t  scltoken,
OTF_KeyValueList list 
)

Write a begin file operation record.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeStart time of file operation.
processProcess identifier > 0.
matchingIdOperation identifier, used for finding the associated end file operation event record.
scltokenOptional reference to source code.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
1 on success, 0 if an error occurs.
int OTF_Handler_BeginFileOpSnapshot ( void *  userData,
uint64_t  time,
uint64_t  originaltime,
uint32_t  process,
uint64_t  matchingId,
uint32_t  scltoken,
OTF_KeyValueList list 
)
Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeCurrent timestamp.
originaltimeTimestamp when the file has been opened.
processProcess identifier.
matchingIdIdentifier for finding the associated end file operation event record. It must be unique.
scltokenOptional reference to source code.
listPointer to an OTF_KeyValueList() that contains individual data.
int OTF_Handler_BeginProcess ( void *  userData,
uint64_t  time,
uint32_t  process,
OTF_KeyValueList list 
)

Provides a process creation event.

Marks the explicit begin of a process. This event precedes the very first event of the respective process and should carry the same time stamp. This is especially useful with on-line analysis. It tells whether there will be additional records for the given process or not. Without this record type, it could only be guessed that there might not follow more events after a process has reached the bottom of the call stack.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime when process was referenced for the first time.
processProcess identifier > 0.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_CollectiveOperation ( void *  userData,
uint64_t  time,
uint32_t  process,
uint32_t  collective,
uint32_t  procGroup,
uint32_t  rootProc,
uint32_t  sent,
uint32_t  received,
uint64_t  duration,
uint32_t  source,
OTF_KeyValueList list 
)

Provides a collective operation member event.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime when collective operation was entered by member.
processProcess identifier i.e. collective member.
collectiveCollective identifier as defined with OTF_Handler_DefCollectiveOperation().
procGroupGroup of processes participating in this collective.
rootProcRoot process if != 0.
sentData volume sent by member or 0.
receivedData volume received by member or 0.
durationTime spent in collective operation.
sourceExplicit source code location or 0.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_CollopSummary ( void *  userData,
uint64_t  time,
uint32_t  process,
uint32_t  comm,
uint32_t  collective,
uint64_t  sentNumber,
uint64_t  receivedNumber,
uint64_t  sentBytes,
uint64_t  receivedBytes,
OTF_KeyValueList list 
)

Provides summarized information for collective operations.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime when summary was computed.
processProcess identifier i.e. collective member.
commCommunicator of collective operation summary.
collectiveCollective identifier as defined with OTF_Handler_DefCollectiveOperation().
sentNumberThe number of messages sent by member or 0.
receivedNumberThe number of messages received by member or 0.
sentBytesThe number of bytes sent by member or 0.
receivedBytesThe number of bytes received by member or 0.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_Counter ( void *  userData,
uint64_t  time,
uint32_t  process,
uint32_t  counter,
uint64_t  value,
OTF_KeyValueList list 
)

Provides a counter measurement.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime when counter was measured.
processProcess where counter measurment took place.
counterCounter which was measured.
valueCounter value.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_DefAttributeList ( void *  userData,
uint32_t  stream,
uint32_t  attr_token,
uint32_t  num,
OTF_ATTR_TYPE array,
OTF_KeyValueList list 
)

Provides a list of attributes that is assigned to a unique token.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
attr_tokenArbitrary but unique attribute list identifier > 0.
numNumber of elements in the attribute list array.
arrayAn array of different attributes with type of OTF_ATTR_TYPE().
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_DefCollectiveOperation ( void *  userData,
uint32_t  stream,
uint32_t  collOp,
const char *  name,
uint32_t  type,
OTF_KeyValueList list 
)

Provides a collective operation definition.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
collOpAn arbitrary but unique collective op. identifier > 0.
nameName of the collective operation e.g. "MPI_Bcast".
typeOne of the five supported collective classes: OTF_COLLECTIVE_TYPE_UNKNOWN (default), OTF_COLLECTIVE_TYPE_BARRIER, OTF_COLLECTIVE_TYPE_ONE2ALL, OTF_COLLECTIVE_TYPE_ALL2ONE, OTF_COLLECTIVE_TYPE_ALL2ALL.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_DefCounter ( void *  userData,
uint32_t  stream,
uint32_t  counter,
const char *  name,
uint32_t  properties,
uint32_t  counterGroup,
const char *  unit,
OTF_KeyValueList list 
)

Provides a counter definition.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
counterAn arbitrary but unique counter identifier.
nameName of the counter e.g. "Cache Misses".
propertiesA combination of a type, scope and vartype counter property. OTF_COUNTER_TYPE_ACC (default) represents a counter with monotonously increasing values e.g. a FLOP counter. OTF_COUNTER_TYPE_ABS on the other hand defines a counter with alternating absolute values e.g. the memory usage of a process. The following counter measurement scopes are supported: OTF_COUNTER_SCOPE_START (default) always refers to the start of the process, OTF_COUNTER_SCOPE_POINT refers to exactly this moment in time, OTF_COUNTER_SCOPE_LAST relates to the previous measurement, and OTF_COUNTER_SCOPE_NEXT to the next measurement. Examples: OTF_COUNTER_TYPE_ACC + OTF_COUNTER_SCOPE_START should be used for most standard hardware (PAPI) counters. OTF_COUNTER_TYPE_ABS + OTF_COUNTER_SCOPE_POINT could be used to record information 'spikes'. OTF_COUNTER_TYPE_ABS + OTF_COUNTER_SCOPE_NEXT works for memory allocation recording. The data type can be one of the following: COUNTER_VARTYPE_{UNSIGNED8,SIGNED8,UNSIGNED4,SIGNED4, UNSIGNED2,SIGNED2,DOUBLE,FLOAT} You may also use COUNTER_VARTYPE_IS{INTEGER,SIGNED, UNSIGNED}(property) to a get a clue about the data type.
counterGroupA previously defined counter group identifier or 0 for no group.
unitUnit of the counter e.g. "#" for "number of..." or 0 for no unit.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_DefCounterAssignments ( void *  userData,
uint32_t  stream,
uint32_t  counter,
uint32_t  number_of_members,
const uint32_t *  procs_or_groups,
OTF_KeyValueList list 
)

Provides a CounterAssignments definition.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
counterCounter id.
number_of_membersNumber of entries in array.
procs_or_groupsThe processes or process groups which have recorded counter data for counter .
listPointer to an OTF_KeyValueList() that contains individual data.
int OTF_Handler_DefCounterGroup ( void *  userData,
uint32_t  stream,
uint32_t  counterGroup,
const char *  name,
OTF_KeyValueList list 
)

Provides a counter group definition.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
counterGroupAn arbitrary but unique counter group identifier > 0.
nameCounter group name.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_DefCreator ( void *  userData,
uint32_t  stream,
const char *  creator,
OTF_KeyValueList list 
)

Provides file creator information.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
creatorString which identifies the creator of the file e.g. "TAU Version x.y.z".
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_DefFile ( void *  userData,
uint32_t  stream,
uint32_t  token,
const char *  name,
uint32_t  group,
OTF_KeyValueList list 
)

Provides a file definition NOTE: this is experimental.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
tokenArbitrary, unique identifier of the file. Has to be > 0.
namename of the file
listPointer to an OTF_KeyValueList() that contains individual data.
groupA previously defined file group identifier or 0 for no group.
int OTF_Handler_DefFileGroup ( void *  userData,
uint32_t  stream,
uint32_t  token,
const char *  name,
OTF_KeyValueList list 
)

Provides a file group definition NOTE: this is experimental.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
tokenArbitrary, unique identifier of the file group Has to be > 0.
listPointer to an OTF_KeyValueList() that contains individual data.
nameName of the file group
int OTF_Handler_DefFunction ( void *  userData,
uint32_t  stream,
uint32_t  func,
const char *  name,
uint32_t  funcGroup,
uint32_t  source,
OTF_KeyValueList list 
)

Provides a function definition.

Defines a function of the given name. Functions can optionally belong to a certain function group provided by the OTF_Handler_DefFunctionGroup() handler. A source code reference can be provided aswell.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
funcArbitrary but unique function identifier > 0.
nameName of the function e.g. "DoSomething".
funcGroupA function group identifier preliminary provided by OTF_Handler_DefFunctionGroup() or 0 for no function group assignment.
sourceReference to the function's source code location preliminary provided by OTF_Handler_DefScl() or 0 for no source code location assignment.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_DefFunctionGroup ( void *  userData,
uint32_t  stream,
uint32_t  funcGroup,
const char *  name,
OTF_KeyValueList list 
)

Provides a function group definition.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
funcGroupAn arbitrary but unique function group identifier > 0.
nameName of the function group e.g. "Computation".
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_DefinitionComment ( void *  userData,
uint32_t  stream,
const char *  comment,
OTF_KeyValueList list 
)

Provides a comment record.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
commentArbitrary comment string.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_DefKeyValue ( void *  userData,
uint32_t  stream,
uint32_t  key,
OTF_Type  type,
const char *  name,
const char *  description,
OTF_KeyValueList list 
)

Provides a KeyValue definition.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
keyArbitrary, unique identifier of the KeyValue.
typeType of the KeyValue. See OTF_Type().
listPointer to an OTF_KeyValueList() that contains individual data.
nameName of the KeyValue.
descriptionDescription of the KeyValue.
int OTF_Handler_DefMarker ( void *  userData,
uint32_t  stream,
uint32_t  token,
const char *  name,
uint32_t  type,
OTF_KeyValueList list 
)

Define a marker.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamstream ID is ignored here
tokenThe newly defined marker token.
nameIts name
typeMarker type, one of OTF_MARKER_TYPE_xxx
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_DefProcess ( void *  userData,
uint32_t  stream,
uint32_t  process,
const char *  name,
uint32_t  parent,
OTF_KeyValueList list 
)

Provides a process definition.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
processArbitrary but unique process identifier > 0.
nameName of the process e.g. "Process X".
parentPreviously declared parent process identifier or 0 if process has no parent.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_DefProcessGroup ( void *  userData,
uint32_t  stream,
uint32_t  procGroup,
const char *  name,
uint32_t  numberOfProcs,
const uint32_t *  procs,
OTF_KeyValueList list 
)

Provides a process group definition.

OTF supports groups of processes. Their main objective is to classify processes depending on arbitrary characteristics. Processes can reside in multiple groups. This record type is optional.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
procGroupArbitrary but unique process group identifier > 0.
nameName of the process group e.g. "Well Balanced".
numberOfProcsThe number of processes in the process group.
procsVector of process identifiers as provided by OTF_Handler_DefProcess().
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_DefProcessOrGroupAttributes ( void *  userData,
uint32_t  stream,
uint32_t  proc_token,
uint32_t  attr_token,
OTF_KeyValueList list 
)

Provides a process or group attributes definition.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
proc_tokenArbitrary but unique process or process group identifier > 0.
attr_tokenA unique token that was defined with OTF_Writer_writeDefAttributeList().
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_DefScl ( void *  userData,
uint32_t  stream,
uint32_t  source,
uint32_t  sourceFile,
uint32_t  line,
OTF_KeyValueList list 
)

Provides a source code location (SCL).

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
sourceArbitrary but unique source code location identifier > 0.
sourceFilePreviously defined source file identifier. See OTW_Handler_DefSclFile().
lineLine number.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_DefSclFile ( void *  userData,
uint32_t  stream,
uint32_t  sourceFile,
const char *  name,
OTF_KeyValueList list 
)

Provides a source code location (SCL) file.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
sourceFileArbitrary but unique source code location identifier != 0.
nameFile name.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_DefTimeRange ( void *  userData,
uint32_t  stream,
uint64_t  minTime,
uint64_t  maxTime,
OTF_KeyValueList list 
)

Provides a TimeRange definition.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
minTimeThe smallest timestamp of the events in this stream.
maxTimeThe greates timestamp of the events in this stream (inclusive).
listPointer to an OTF_KeyValueList() that contains individual data.
int OTF_Handler_DefTimerResolution ( void *  userData,
uint32_t  stream,
uint64_t  ticksPerSecond,
OTF_KeyValueList list 
)

Provides the timer resolution.

All timed event records need to be interpreted according to this definition. By default, a timer resolution of 1 us i.e. 1,000,000 clock ticks is assumed.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
ticksPerSecondClock ticks per second of the timer.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_DefVersion ( void *  userData,
uint32_t  stream,
uint8_t  major,
uint8_t  minor,
uint8_t  sub,
const char *  string,
OTF_KeyValueList list 
)

Provides information on the trace“s otf-version.

This record can only be read and not be written.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
streamIdentifies the stream to which this definition belongs to. stream = 0 represents a global definition.
majormajor version number
minorminor version number
subsub version number
stringstring identifing the version
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_EndCollectiveOperation ( void *  userData,
uint64_t  time,
uint32_t  process,
uint64_t  matchingId,
OTF_KeyValueList list 
)

Provides an end collective operation member event.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime when collective operation was entered by member.
processProcess identifier i.e. collective member.
matchingIdMatching identifier, must match a previous start collective operation.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
1 on success, 0 if an error occurs.
int OTF_Handler_EndFileOperation ( void *  userData,
uint64_t  time,
uint32_t  process,
uint32_t  fileid,
uint64_t  matchingId,
uint64_t  handleId,
uint32_t  operation,
uint64_t  bytes,
uint32_t  scltoken,
OTF_KeyValueList list 
)

Write an end file operation record.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeEnd time of file operation.
processProcess identifier > 0.
fileidFile identifier > 0.
matchingIdOperation identifier, must match a previous start file operation event record.
handleIdUnique file open identifier.
operationType of file operation. See OTF_Handler_FileOperation().
bytesDepends on operation. See OTF_Handler_FileOperation().
scltokenOptional reference to source code.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
1 on success, 0 if an error occurs.
int OTF_Handler_EndProcess ( void *  userData,
uint64_t  time,
uint32_t  process,
OTF_KeyValueList list 
)

Provides a process destruction event.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime when process is referenced for the last time. Process identifiers must not be recycled!
processProcess identifier > 0.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_Enter ( void *  userData,
uint64_t  time,
uint32_t  function,
uint32_t  process,
uint32_t  source,
OTF_KeyValueList list 
)

Provides a function entry event.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeThe time when the function entry took place.
functionFunction which has been entered as defined with OTF_Writer_defFunction.
processProcess where action took place.
sourceExplicit source code location identifier > 0 or 0 if no source information available.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_EnterSnapshot ( void *  userData,
uint64_t  time,
uint64_t  originaltime,
uint32_t  function,
uint32_t  process,
uint32_t  source,
OTF_KeyValueList list 
)

provides information about a past function call at the time 'originaltime'.

Parameters 'time', 'function', 'process' ,'source' and the return value have the same meaning as in OTF_Handler_Enter().

int OTF_Handler_EventComment ( void *  userData,
uint64_t  time,
uint32_t  process,
const char *  comment,
OTF_KeyValueList list 
)

Provide a comment record.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeComments need a timestamp for a proper positioning in the trace.
processComments also need a process identifier for a proper positioning in the trace.
commentArbitrary comment string.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_FileGroupOperationSummary ( void *  userData,
uint64_t  time,
uint32_t  groupid,
uint32_t  process,
uint64_t  nopen,
uint64_t  nclose,
uint64_t  nread,
uint64_t  nwrite,
uint64_t  nseek,
uint64_t  bytesread,
uint64_t  byteswrite,
OTF_KeyValueList list 
)

Provides summarized information about file operations in a file group.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime when summary was computed.
groupidGroup identifier or 0 for all files.
processProcess where file operations occured.
nopenNumber of open events.
ncloseNumber of close events.
nreadNumber of read events.
nwriteNumber of write events.
nseekNumber of seek events.
bytesreadNumber of bytes read.
byteswriteNumber of bytes written.
listPointer to an OTF_KeyValueList() that contains individual data.
int OTF_Handler_FileOperation ( void *  userData,
uint64_t  time,
uint32_t  fileid,
uint32_t  process,
uint64_t  handleid,
uint32_t  operation,
uint64_t  bytes,
uint64_t  duration,
uint32_t  source,
OTF_KeyValueList list 
)

Provides a file operation event NOTE: this is experimental.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime when process is referenced for the last time. Process identifiers must not be recycled!
processProcess identifier > 0.
handleidUnique identifier. This parameter is important for files that are opened multiple times at the same time, to match the close to the correct open. This number has to be unique for every opened file ( Files with the same id must have different handleid !!! ). Recommendation: use the timestamp of the openfile record, or an increasing(with every fileopen record) variable for this.
operationKind of operation done on the file and flags further describing the operation. The macro OTF_FILEOP(operation) should be used to check for the kind of I/O operation.
  • OTF_FILEOP(operation) can be checked for equality on
    • OTF_FILEOP_OPEN – open a file
    • OTF_FILEOP_CLOSE – close a file
    • OTF_FILEOP_READ – read some bytes off a file
    • OTF_FILEOP_WRITE – write some bytes to a file
    • OTF_FILEOP_SEEK – set the file pointer
    • OTF_FILEOP_UNLINK – delete a file
    • OTF_FILEOP_RENAME – rename a file
    • OTF_FILEOP_DUP – duplicate a file desriptor
    • OTF_FILEOP_SYNC – write dirty buffers to disk
    • OTF_FILEOP_LOCK – acquire a file lock
    • OTF_FILEOP_UNLOCK – release a file lock
    • OTF_FILEOP_OTHER – none of the above
  • The following flags are supported and can be checked bit-wise for existence in operation:
    • OTF_IOFLAG_IOFAILED – e.g. could not open file, could not read or write all bytes, a lock could not be acquired, a rename operation failed, etc.
    • OTF_IOFLAG_ASYNC – I/O is done asynchronously
    • OTF_IOFLAG_COLL – this is a collective I/O operation
    • OTF_IOFLAG_DIRECT – I/O is done bypassing the cache
    • OTF_IOFLAG_SYNC – I/O is done synchronously
    • OTF_IOFLAG_ISREADLOCK – lock is a read-only file lock
bytesShould be 0 for open and close. Number of read/written bytes for read/write operations. New position in the file after a seek operation.
durationTime spent in the file operation.
sourceExplicit source code location or 0.
listPointer to an OTF_KeyValueList() that contains individual data.
int OTF_Handler_FileOperationSummary ( void *  userData,
uint64_t  time,
uint32_t  fileid,
uint32_t  process,
uint64_t  nopen,
uint64_t  nclose,
uint64_t  nread,
uint64_t  nwrite,
uint64_t  nseek,
uint64_t  bytesread,
uint64_t  byteswrite,
OTF_KeyValueList list 
)

Provides summarized information about file operations.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime when summary was computed.
fileidFile identifier or 0 for all files.
processProcess where file operations occured.
nopenNumber of open events.
ncloseNumber of close events.
nreadNumber of read events.
nwriteNumber of write events.
nseekNumber of seek events.
bytesreadNumber of bytes read.
byteswriteNumber of bytes written.
listPointer to an OTF_KeyValueList() that contains individual data.
int OTF_Handler_FunctionGroupSummary ( void *  userData,
uint64_t  time,
uint32_t  funcGroup,
uint32_t  process,
uint64_t  invocations,
uint64_t  exclTime,
uint64_t  inclTime,
OTF_KeyValueList list 
)

Provides summarized information for a given group of functiongroups.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime when summary was computed.
funcGroupFunction group as defined with OTF_Handler_DefFunctionGroup.
processProcess of the given function group.
invocationsNumber of invocations.
exclTimeTime spent exclusively in the given function group.
inclTimeTime spent in the given function group including all sub-routine calls.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_FunctionSummary ( void *  userData,
uint64_t  time,
uint32_t  function,
uint32_t  process,
uint64_t  invocations,
uint64_t  exclTime,
uint64_t  inclTime,
OTF_KeyValueList list 
)

Provides summarized information for a given function.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime when summary was computed.
functionFunction as defined with OTF_Handler_DefFunction.
processProcess of the given function.
invocationsNumber of invocations.
exclTimeTime spent exclusively in the given function.
inclTimeTime spent in the given function including all sub-routine calls.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_Leave ( void *  userData,
uint64_t  time,
uint32_t  function,
uint32_t  process,
uint32_t  source,
OTF_KeyValueList list 
)

Provides a function leave event.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeThe time when the function leave took place.
functionFunction which was left or 0 if stack integrety checking is not available.
processProcess where action took place.
sourceExplicit source code location identifier > 0 or 0 if no source information available.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_Marker ( void *  userData,
uint64_t  time,
uint32_t  process,
uint32_t  token,
const char *  text,
OTF_KeyValueList list 
)

Define a marker.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime stamp of the marker record. Note that marker records are not sorted according to time stamps!
processThe process or process group of the marker.
tokenA marker token defined by 'DefMarker' before.
textDescriptive text.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_MessageSummary ( void *  userData,
uint64_t  time,
uint32_t  process,
uint32_t  peer,
uint32_t  comm,
uint32_t  type,
uint64_t  sentNumber,
uint64_t  receivedNumber,
uint64_t  sentBytes,
uint64_t  receivedBytes,
OTF_KeyValueList list 
)

Provides summarized information for a given message type.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime when summary was computed.
processProcess where messages originated.
peerProcess where the message is sent to
commCommunicator of message summary
typeMessage type/tag.
sentNumberThe number of messages sent.
receivedNumberThe number of messages received.
sentBytesThe number of bytes sent via messages of the given type.
receivedBytesThe number of bytes received through messages of the given type.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_NoOp ( void *  userData,
uint64_t  time,
uint32_t  process,
OTF_KeyValueList list 
)

Provides a no-operation event.

This event only stores a OTF_KeyValueList together with a process number and a timestamp.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeThe time associated with this event.
processProcess where action took place.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_OpenFileSnapshot ( void *  userData,
uint64_t  time,
uint64_t  originaltime,
uint32_t  fileid,
uint32_t  process,
uint64_t  handleid,
uint32_t  source,
OTF_KeyValueList list 
)

Provides a snapshot record for opened(and not yet closed) files.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeCurrent timestamp.
originaltimeTimestamp when the file has been opened.
processProcess identifier.
handleidUnique file open identifier. See OTF_Handler_FileOperation().
sourceOptional reference to source code.
listPointer to an OTF_KeyValueList() that contains individual data.
int OTF_Handler_RecvMsg ( void *  userData,
uint64_t  time,
uint32_t  recvProc,
uint32_t  sendProc,
uint32_t  group,
uint32_t  type,
uint32_t  length,
uint32_t  source,
OTF_KeyValueList list 
)

Provides a message retrieval event.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeThe time when the message was received.
recvProcIdentifier of receiving process.
sendProcIdentifier of sending process.
groupProcess-group to which sender and receiver belong to or 0 for no group assignment.
typeMessage type information > 0 or 0 for no information.
lengthOptional message length information.
sourceExplicit source code location identifier > 0 or 0 if no source information available.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_RMAEnd ( void *  userData,
uint64_t  time,
uint32_t  process,
uint32_t  remote,
uint32_t  communicator,
uint32_t  tag,
uint32_t  source,
OTF_KeyValueList list 
)

Provide a RMA end event.

The end record marks the finalization of all RMA operations with the communicator and tag.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime when process is referenced for the last time. Process identifiers must not be recycled!
processProcess identifier > 0.
remoteIf >0, ends RMA transfers on Process <remote>, instead of this <process>.
communicatorTogether with tag, it is used to identify the related RMA transfer records.
tagTogether with communicator, it is used to identify the related RMA transfer records.
sourceExplicit source code location or 0.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
1 on success, 0 if an error occurs.
int OTF_Handler_RMAGet ( void *  userData,
uint64_t  time,
uint32_t  process,
uint32_t  origin,
uint32_t  target,
uint32_t  communicator,
uint32_t  tag,
uint64_t  bytes,
uint32_t  source,
OTF_KeyValueList list 
)

Provides a RMA get event - end marker is anticipated on initiating Process.

NOTE: this is experimental

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime when process is referenced for the last time. Process identifiers must not be recycled!
processProcess identifier > 0. This is the Process that initiates the transfer.
originIf >0, the Process whose memory will receive the data from <target>, instead of this <process>.
targetProcess whose memory will be read.
communicatorTogether with tag, it is used to identify the corresponding RMA end record. This will be the process group of the RMA Window in case of MPI one-sided communication.
tagTogether with communicator, it is used to identify the corresponding RMA end record. Usually this will be counted upwards to distinguish multiple transfer sections with the same communicator BUT THIS IS NOT MANDATORY, i.e. multiple RMA end records with the same comm/tag combination may exist.
bytesNumber of bytes that have been transferred by this call.
sourceExplicit source code location or 0.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
1 on success, 0 if an error occurs.
int OTF_Handler_RMAPut ( void *  userData,
uint64_t  time,
uint32_t  process,
uint32_t  origin,
uint32_t  target,
uint32_t  communicator,
uint32_t  tag,
uint64_t  bytes,
uint32_t  source,
OTF_KeyValueList list 
)

Provides a RMA put event - end marker is anticipated on initiating Process.

NOTE: this is experimental

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime when process is referenced for the last time. Process identifiers must not be recycled!
processProcess identifier > 0. This is the Process that initiates the transfer.
originIf >0, Process whose memory will be transferred, instead of this <process>.
targetProcess whose memory will be written.
communicatorTogether with tag, it is used to identify the corresponding RMA end record. This will be the process group of the RMA Window in case of MPI one-sided communication.
tagTogether with communicator, it is used to identify the corresponding RMA end record. Usually this will be counted upwards to distinguish multiple transfer sections with the same communicator BUT THIS IS NOT MANDATORY, i.e. multiple RMA end records with the same comm/tag combination may exist.
bytesNumber of bytes that have been transferred by this call.
sourceExplicit source code location or 0.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
1 on success, 0 if an error occurs.
int OTF_Handler_RMAPutRemoteEnd ( void *  userData,
uint64_t  time,
uint32_t  process,
uint32_t  origin,
uint32_t  target,
uint32_t  communicator,
uint32_t  tag,
uint64_t  bytes,
uint32_t  source,
OTF_KeyValueList list 
)

Provides a RMA put event with remote finalization marker, i.e.

RMA end marker is anticipated on target Process. NOTE: this is experimental

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime when process is referenced for the last time. Process identifiers must not be recycled!
processProcess identifier > 0. This is the Process that initiates the transfer.
originIf >0, Process whose memory will be transferred, instead of this <process>.
targetProcess whose memory will be written. That Process' stream will also carry the end record for this transaction.
communicatorTogether with tag, it is used to identify the corresponding RMA end record. This will be the process group of the RMA Window in case of MPI one-sided communication.
tagTogether with communicator, it is used to identify the corresponding RMA end record. Usually this will be counted upwards to distinguish multiple transfer sections with the same communicator BUT THIS IS NOT MANDATORY, i.e. multiple RMA end records with the same comm/tag combination may exist.
bytesNumber of bytes that have been transferred by this call.
sourceExplicit source code location or 0.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
1 on success, 0 if an error occurs.
int OTF_Handler_SendMsg ( void *  userData,
uint64_t  time,
uint32_t  sender,
uint32_t  receiver,
uint32_t  group,
uint32_t  type,
uint32_t  length,
uint32_t  source,
OTF_KeyValueList list 
)

Provides a message send event.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeThe time when the message was send.
senderSender of the message.
receiverReceiver of the message.
groupProcess-group to which sender and receiver belong to or 0 for no group assignment.
typeMessage type information > 0 or 0 for no information.
lengthOptional message length information.
sourceExplicit source code location identifier > 0 or 0 if no source information available.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_SendSnapshot ( void *  userData,
uint64_t  time,
uint64_t  originaltime,
uint32_t  sender,
uint32_t  receiver,
uint32_t  procGroup,
uint32_t  tag,
uint32_t  length,
uint32_t  source,
OTF_KeyValueList list 
)

provides information about a past message send operation at the time 'originaltime'.

Parameters 'time', 'sender', 'receiver', 'procGroup', 'tag', 'length', 'source' and the return value have the same meaning as in OTF_Handler_SendMsg().

int OTF_Handler_SnapshotComment ( void *  userData,
uint64_t  time,
uint32_t  process,
const char *  comment,
OTF_KeyValueList list 
)

Provides a snapshot comment.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeComments need a timestamp for a proper positioning in the trace.
processComments also need a process identifier for a proper positioning in the trace.
commentArbitrary comment string.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_SummaryComment ( void *  userData,
uint64_t  time,
uint32_t  process,
const char *  comment,
OTF_KeyValueList list 
)

Provides a summary comment.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeComments need a timestamp for a proper positioning in the trace.
processComments also need a process identifier for a proper positioning in the trace.
commentArbitrary comment string.
listPointer to an OTF_KeyValueList() that contains individual data.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading
int OTF_Handler_UnknownRecord ( void *  userData,
uint64_t  time,
uint32_t  process,
const char *  record 
)

Can be used to handle records which cannot be read.

Parameters
userDataPointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
timeTime when summary was computed.
processIf 'time' equals (uin64_t) -1, the unknown record is a definiton record and 'process' represents the streamid of the record. If 'time' has a valid value ( not (uint64)-1 ) the unknown record is an event-, statistics- or snapshotrecord and 'process' represents the processid of the record.
recordstring which contains the record.
Returns
OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading