OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

Files | Functions
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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time when collective operation was entered by member.
  process | Process identifier i.e. collective member.
  collOp | Collective identifier to be defined with OTF_Writer_writeDefCollectiveOperation().
  matchingId | Identifier for finding the associated end collective event record. It must be unique within this process.
  procGroup | Group of processes participating in this collective.
  rootProc | Root process if != 0.
  sent | Data volume sent by member or 0.
  received | Data volume received by member or 0.
  scltoken | Explicit source code location or 0.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Current timestamp.
  originaltime | Time when the collective operation began.
  process | Process identifier.
  collOp | Collective identifier to be defined with OTF_Writer_writeDefCollectiveOperation().
  matchingId | Identifier for finding the associated end collective event record. It must be unique within this procGroup.
  procGroup | Group of processes participating in this collective.
  rootProc | Root process if != 0.
  sent | Data volume sent by member or 0.
  received | Data volume received by member or 0.
  scltoken | Optional reference to source code.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Start time of file operation.
  process | Process identifier > 0.
  matchingId | Operation identifier, used for finding the associated end file operation event record.
  scltoken | Optional reference to source code.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Current timestamp.
  originaltime | Timestamp when the file has been opened.
  process | Process identifier.
  matchingId | Identifier for finding the associated end file operation event record. It must be unique.
  scltoken | Optional reference to source code.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time when process was referenced for the first time.
  process | Process identifier > 0.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time when collective operation was entered by member.
  process | Process identifier i.e. collective member.
  collective | Collective identifier as defined with OTF_Handler_DefCollectiveOperation().
  procGroup | Group of processes participating in this collective.
  rootProc | Root process if != 0.
  sent | Data volume sent by member or 0.
  received | Data volume received by member or 0.
  duration | Time spent in collective operation.
  source | Explicit source code location or 0.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time when summary was computed.
  process | Process identifier i.e. collective member.
  comm | Communicator of collective operation summary.
  collective | Collective identifier as defined with OTF_Handler_DefCollectiveOperation().
  sentNumber | The number of messages sent by member or 0.
  receivedNumber | The number of messages received by member or 0.
  sentBytes | The number of bytes sent by member or 0.
  receivedBytes | The number of bytes received by member or 0.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time when counter was measured.
  process | Process where counter measurment took place.
  counter | Counter which was measured.
  value | Counter value.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  attr_token | Arbitrary but unique attribute list identifier > 0.
  num | Number of elements in the attribute list array.
  array | An array of different attributes with type of OTF_ATTR_TYPE().
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  collOp | An arbitrary but unique collective op. identifier > 0.
  name | Name of the collective operation e.g. "MPI_Bcast".
  type | One 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.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  counter | An arbitrary but unique counter identifier.
  name | Name of the counter e.g. "Cache Misses".
  properties | A 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.
  counterGroup | A previously defined counter group identifier or 0 for no group.
  unit | Unit of the counter e.g. "#" for "number of..." or 0 for no unit.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  counter | Counter id.
  number_of_members | Number of entries in array.
  procs_or_groups | The processes or process groups which have recorded counter data for counter .
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  counterGroup | An arbitrary but unique counter group identifier > 0.
  name | Counter group name.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  creator | String which identifies the creator of the file e.g. "TAU Version x.y.z".
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  token | Arbitrary, unique identifier of the file. Has to be > 0.
  name | name of the file
  list | Pointer to an OTF_KeyValueList() that contains individual data.
  group | A 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  token | Arbitrary, unique identifier of the file group Has to be > 0.
  list | Pointer to an OTF_KeyValueList() that contains individual data.
  name | Name 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  func | Arbitrary but unique function identifier > 0.
  name | Name of the function e.g. "DoSomething".
  funcGroup | A function group identifier preliminary provided by OTF_Handler_DefFunctionGroup() or 0 for no function group assignment.
  source | Reference to the function's source code location preliminary provided by OTF_Handler_DefScl() or 0 for no source code location assignment.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  funcGroup | An arbitrary but unique function group identifier > 0.
  name | Name of the function group e.g. "Computation".
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  comment | Arbitrary comment string.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  key | Arbitrary, unique identifier of the KeyValue.
  type | Type of the KeyValue. See OTF_Type().
  list | Pointer to an OTF_KeyValueList() that contains individual data.
  name | Name of the KeyValue.
  description | Description 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | stream ID is ignored here
  token | The newly defined marker token.
  name | Its name
  type | Marker type, one of OTF_MARKER_TYPE_xxx
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  process | Arbitrary but unique process identifier > 0.
  name | Name of the process e.g. "Process X".
  parent | Previously declared parent process identifier or 0 if process has no parent.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  procGroup | Arbitrary but unique process group identifier > 0.
  name | Name of the process group e.g. "Well Balanced".
  numberOfProcs | The number of processes in the process group.
  procs | Vector of process identifiers as provided by OTF_Handler_DefProcess().
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  proc_token | Arbitrary but unique process or process group identifier > 0.
  attr_token | A unique token that was defined with OTF_Writer_writeDefAttributeList().
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  source | Arbitrary but unique source code location identifier > 0.
  sourceFile | Previously defined source file identifier. See OTW_Handler_DefSclFile().
  line | Line number.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  sourceFile | Arbitrary but unique source code location identifier != 0.
  name | File name.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  minTime | The smallest timestamp of the events in this stream.
  maxTime | The greates timestamp of the events in this stream (inclusive).
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  ticksPerSecond | Clock ticks per second of the timer.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  stream | Identifies the stream to which this definition belongs to. stream = 0 represents a global definition.
  major | major version number
  minor | minor version number
  sub | sub version number
  string | string identifing the version
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time when collective operation was entered by member.
  process | Process identifier i.e. collective member.
  matchingId | Matching identifier, must match a previous start collective operation.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | End time of file operation.
  process | Process identifier > 0.
  fileid | File identifier > 0.
  matchingId | Operation identifier, must match a previous start file operation event record.
  handleId | Unique file open identifier.
  operation | Type of file operation. See OTF_Handler_FileOperation().
  bytes | Depends on operation. See OTF_Handler_FileOperation().
  scltoken | Optional reference to source code.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time when process is referenced for the last time. Process identifiers must not be recycled!
  process | Process identifier > 0.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | The time when the function entry took place.
  function | Function which has been entered as defined with OTF_Writer_defFunction.
  process | Process where action took place.
  source | Explicit source code location identifier > 0 or 0 if no source information available.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Comments need a timestamp for a proper positioning in the trace.
  process | Comments also need a process identifier for a proper positioning in the trace.
  comment | Arbitrary comment string.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time when summary was computed.
  groupid | Group identifier or 0 for all files.
  process | Process where file operations occured.
  nopen | Number of open events.
  nclose | Number of close events.
  nread | Number of read events.
  nwrite | Number of write events.
  nseek | Number of seek events.
  bytesread | Number of bytes read.
  byteswrite | Number of bytes written.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time when process is referenced for the last time. Process identifiers must not be recycled!
  process | Process identifier > 0.
  handleid | Unique 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.
  operation | Kind 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
  bytes | Should be 0 for open and close. Number of read/written bytes for read/write operations. New position in the file after a seek operation.
  duration | Time spent in the file operation.
  source | Explicit source code location or 0.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time when summary was computed.
  fileid | File identifier or 0 for all files.
  process | Process where file operations occured.
  nopen | Number of open events.
  nclose | Number of close events.
  nread | Number of read events.
  nwrite | Number of write events.
  nseek | Number of seek events.
  bytesread | Number of bytes read.
  byteswrite | Number of bytes written.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time when summary was computed.
  funcGroup | Function group as defined with OTF_Handler_DefFunctionGroup.
  process | Process of the given function group.
  invocations | Number of invocations.
  exclTime | Time spent exclusively in the given function group.
  inclTime | Time spent in the given function group including all sub-routine calls.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time when summary was computed.
  function | Function as defined with OTF_Handler_DefFunction.
  process | Process of the given function.
  invocations | Number of invocations.
  exclTime | Time spent exclusively in the given function.
  inclTime | Time spent in the given function including all sub-routine calls.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | The time when the function leave took place.
  function | Function which was left or 0 if stack integrety checking is not available.
  process | Process where action took place.
  source | Explicit source code location identifier > 0 or 0 if no source information available.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time stamp of the marker record. Note that marker records are not sorted according to time stamps!
  process | The process or process group of the marker.
  token | A marker token defined by 'DefMarker' before.
  text | Descriptive text.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time when summary was computed.
  process | Process where messages originated.
  peer | Process where the message is sent to
  comm | Communicator of message summary
  type | Message type/tag.
  sentNumber | The number of messages sent.
  receivedNumber | The number of messages received.
  sentBytes | The number of bytes sent via messages of the given type.
  receivedBytes | The number of bytes received through messages of the given type.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | The time associated with this event.
  process | Process where action took place.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Current timestamp.
  originaltime | Timestamp when the file has been opened.
  process | Process identifier.
  handleid | Unique file open identifier. See OTF_Handler_FileOperation().
  source | Optional reference to source code.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | The time when the message was received.
  recvProc | Identifier of receiving process.
  sendProc | Identifier of sending process.
  group | Process-group to which sender and receiver belong to or 0 for no group assignment.
  type | Message type information > 0 or 0 for no information.
  length | Optional message length information.
  source | Explicit source code location identifier > 0 or 0 if no source information available.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time when process is referenced for the last time. Process identifiers must not be recycled!
  process | Process identifier > 0.
  remote | If >0, ends RMA transfers on Process <remote>, instead of this <process>.
  communicator | Together with tag, it is used to identify the related RMA transfer records.
  tag | Together with communicator, it is used to identify the related RMA transfer records.
  source | Explicit source code location or 0.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time when process is referenced for the last time. Process identifiers must not be recycled!
  process | Process identifier > 0. This is the Process that initiates the transfer.
  origin | If >0, the Process whose memory will receive the data from <target>, instead of this <process>.
  target | Process whose memory will be read.
  communicator | Together 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.
  tag | Together 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.
  bytes | Number of bytes that have been transferred by this call.
  source | Explicit source code location or 0.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time when process is referenced for the last time. Process identifiers must not be recycled!
  process | Process identifier > 0. This is the Process that initiates the transfer.
  origin | If >0, Process whose memory will be transferred, instead of this <process>.
  target | Process whose memory will be written.
  communicator | Together 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.
  tag | Together 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.
  bytes | Number of bytes that have been transferred by this call.
  source | Explicit source code location or 0.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time when process is referenced for the last time. Process identifiers must not be recycled!
  process | Process identifier > 0. This is the Process that initiates the transfer.
  origin | If >0, Process whose memory will be transferred, instead of this <process>.
  target | Process whose memory will be written. That Process' stream will also carry the end record for this transaction.
  communicator | Together 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.
  tag | Together 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.
  bytes | Number of bytes that have been transferred by this call.
  source | Explicit source code location or 0.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | The time when the message was send.
  sender | Sender of the message.
  receiver | Receiver of the message.
  group | Process-group to which sender and receiver belong to or 0 for no group assignment.
  type | Message type information > 0 or 0 for no information.
  length | Optional message length information.
  source | Explicit source code location identifier > 0 or 0 if no source information available.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Comments need a timestamp for a proper positioning in the trace.
  process | Comments also need a process identifier for a proper positioning in the trace.
  comment | Arbitrary comment string.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Comments need a timestamp for a proper positioning in the trace.
  process | Comments also need a process identifier for a proper positioning in the trace.
  comment | Arbitrary comment string.
  list | Pointer 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

  userData | Pointer to user data which can be set with OTF_HandlerArray_setFirstHandlerArg().
  time | Time when summary was computed.
  process | If '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.
  record | string which contains the record.

Returns
  OTF_RETURN_ABORT for aborting the reading process immediately OTF_RETURN_OK for continue reading