OpenMPI  0.1.1
OTF_Handler.h
Go to the documentation of this file.
1 /*
2  This is part of the OTF library. Copyright by ZIH, TU Dresden 2005-2012.
3  Authors: Andreas Knuepfer, Holger Brunst, Ronny Brendel, Thomas Kriebitzsch
4 */
5 
6 /**
7  * @file OTF_Handler.h
8  *
9  * @brief Provides read access to OTF traces which consist of multiple
10  * streams.
11  *
12  */
13 
14 /** \defgroup handler Handler Interface
15  *
16  * In the following, the handler interfaces for all record types are
17  * specified. The signature of callback handler functions is equal to the
18  * signature of corresponding record write functions except for the first
19  * argument. The first argument common to all callback handler functions is
20  * \em userData -- a generic pointer to custom user data. The second common
21  * argument to all callback hander functions is \em stream which identifies the
22  * stream where the definition occurred. A stream parameter = 0 indicates a
23  * global definition which is the default.
24  */
25 
26 /**
27  * \defgroup ha Handler Array Interface
28  *
29  * Using this interface you can setup a handler array for reading traces.
30  *
31  */
32 
33 #include "OTF_KeyValue.h"
34 
35 
36 /* Handlers for OTF definition records *****+++***************************** */
37 
38 
39 /**
40  * Provides a comment record.
41  *
42  * @param userData Pointer to user data which can be set with
43  * OTF_HandlerArray_setFirstHandlerArg().
44  * @param stream Identifies the stream to which this definition
45  * belongs to. stream = 0 represents a global
46  * definition.
47  * @param comment Arbitrary comment string.
48  *
49  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
50  *
51  * @return OTF_RETURN_ABORT for aborting the reading process immediately
52  * OTF_RETURN_OK for continue reading
53  *
54  * \ingroup handler
55  */
56 int OTF_Handler_DefinitionComment( void* userData, uint32_t stream, const char* comment, OTF_KeyValueList *list );
57 
58 
59 
60 /**
61  * Provides the timer resolution. All timed event records need to be
62  * interpreted according to this definition. By default, a timer resolution of
63  * 1 us i.e. 1,000,000 clock ticks is assumed.
64  *
65  * @param userData Pointer to user data which can be set with
66  * OTF_HandlerArray_setFirstHandlerArg().
67  * @param stream Identifies the stream to which this definition
68  * belongs to. stream = 0 represents a global
69  * definition.
70  * @param ticksPerSecond Clock ticks per second of the timer.
71  *
72  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
73  *
74  * @return OTF_RETURN_ABORT for aborting the reading process immediately
75  * OTF_RETURN_OK for continue reading
76  *
77  * \ingroup handler
78  */
79 int OTF_Handler_DefTimerResolution( void* userData,
80  uint32_t stream,
81  uint64_t ticksPerSecond,
83 
84 
85 /**
86  * Provides a process definition.
87  *
88  * @param userData Pointer to user data which can be set with
89  * OTF_HandlerArray_setFirstHandlerArg().
90  * @param stream Identifies the stream to which this definition
91  * belongs to. stream = 0 represents a global
92  * definition.
93  * @param process Arbitrary but unique process identifier > 0.
94  * @param name Name of the process e.g. "Process X".
95  * @param parent Previously declared parent process identifier or 0 if
96  * process has no parent.
97  *
98  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
99  *
100  * @return OTF_RETURN_ABORT for aborting the reading process immediately
101  * OTF_RETURN_OK for continue reading
102  *
103  * \ingroup handler
104  */
105 int OTF_Handler_DefProcess( void* userData,
106  uint32_t stream,
107  uint32_t process,
108  const char* name,
109  uint32_t parent,
111 
112 
113 /**
114  * Provides a process group definition.
115  *
116  * OTF supports groups of processes. Their main objective is to classify
117  * processes depending on arbitrary characteristics. Processes can reside
118  * in multiple groups. This record type is optional.
119  *
120  * @param userData Pointer to user data which can be set with
121  * OTF_HandlerArray_setFirstHandlerArg().
122  * @param stream Identifies the stream to which this definition
123  * belongs to. stream = 0 represents a global
124  * definition.
125  * @param procGroup Arbitrary but unique process group identifier > 0.
126  * @param name Name of the process group e.g. "Well Balanced".
127  * @param numberOfProcs The number of processes in the process group.
128  * @param procs Vector of process identifiers as provided by
129  * OTF_Handler_DefProcess().
130  *
131  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
132  *
133  * @return OTF_RETURN_ABORT for aborting the reading process immediately
134  * OTF_RETURN_OK for continue reading
135  *
136  * \ingroup handler
137  */
138 int OTF_Handler_DefProcessGroup( void* userData,
139  uint32_t stream,
140  uint32_t procGroup,
141  const char* name,
142  uint32_t numberOfProcs,
143  const uint32_t* procs,
145 
146 
147 /**
148  * Provides a list of attributes that is assigned to a unique token.
149  *
150  * @param userData Pointer to user data which can be set with
151  * OTF_HandlerArray_setFirstHandlerArg().
152  * @param stream Identifies the stream to which this definition
153  * belongs to. stream = 0 represents a global
154  * definition.
155  * @param attr_token Arbitrary but unique attribute list identifier > 0.
156  * @param num Number of elements in the attribute list array.
157  * @param array An array of different attributes with type of OTF_ATTR_TYPE().
158  *
159  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
160  *
161  * @return OTF_RETURN_ABORT for aborting the reading process immediately
162  * OTF_RETURN_OK for continue reading
163  *
164  * \ingroup handler
165  */
166 int OTF_Handler_DefAttributeList( void* userData,
167  uint32_t stream,
168  uint32_t attr_token,
169  uint32_t num,
170  OTF_ATTR_TYPE* array,
172 
173 
174 /**
175  * Provides a process or group attributes definition.
176  *
177  * @param userData Pointer to user data which can be set with
178  * OTF_HandlerArray_setFirstHandlerArg().
179  * @param stream Identifies the stream to which this definition
180  * belongs to. stream = 0 represents a global
181  * definition.
182  * @param proc_token Arbitrary but unique process or process group identifier > 0.
183  * @param attr_token A unique token that was defined with OTF_Writer_writeDefAttributeList().
184  *
185  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
186  *
187  * @return OTF_RETURN_ABORT for aborting the reading process immediately
188  * OTF_RETURN_OK for continue reading
189  *
190  * \ingroup handler
191  */
192 int OTF_Handler_DefProcessOrGroupAttributes( void* userData,
193  uint32_t stream,
194  uint32_t proc_token,
195  uint32_t attr_token,
197 
198 
199 /**
200  * Provides a function definition.
201  *
202  * Defines a function of the given name. Functions can optionally belong to a
203  * certain function group provided by the
204  * OTF_Handler_DefFunctionGroup() handler. A source code reference can
205  * be provided aswell.
206  *
207  * @param userData Pointer to user data which can be set with
208  * OTF_HandlerArray_setFirstHandlerArg().
209  * @param stream Identifies the stream to which this definition
210  * belongs to. stream = 0 represents a global
211  * definition.
212  * @param func Arbitrary but unique function identifier > 0.
213  * @param name Name of the function e.g. "DoSomething".
214  * @param funcGroup A function group identifier preliminary provided by
215  * OTF_Handler_DefFunctionGroup() or 0 for no
216  * function group assignment.
217  * @param source Reference to the function's source code location
218  * preliminary provided by OTF_Handler_DefScl() or
219  * 0 for no source code location assignment.
220  *
221  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
222  *
223  * @return OTF_RETURN_ABORT for aborting the reading process immediately
224  * OTF_RETURN_OK for continue reading
225  *
226  * \ingroup handler
227  */
228 int OTF_Handler_DefFunction( void* userData,
229  uint32_t stream,
230  uint32_t func,
231  const char* name,
232  uint32_t funcGroup,
233  uint32_t source,
235 
236 
237 /**
238  * Provides a function group definition.
239  *
240  * @param userData Pointer to user data which can be set with
241  * OTF_HandlerArray_setFirstHandlerArg().
242  * @param stream Identifies the stream to which this definition
243  * belongs to. stream = 0 represents a global
244  * definition.
245  * @param funcGroup An arbitrary but unique function group identifier > 0.
246  * @param name Name of the function group e.g. "Computation".
247  *
248  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
249  *
250  * @return OTF_RETURN_ABORT for aborting the reading process immediately
251  * OTF_RETURN_OK for continue reading
252  *
253  * \ingroup handler
254  */
255 int OTF_Handler_DefFunctionGroup( void* userData,
256  uint32_t stream,
257  uint32_t funcGroup,
258  const char* name,
260 
261 
262 /**
263  * Provides a collective operation definition.
264  *
265  * @param userData Pointer to user data which can be set with
266  * OTF_HandlerArray_setFirstHandlerArg().
267  * @param stream Identifies the stream to which this definition
268  * belongs to. stream = 0 represents a global
269  * definition.
270  * @param collOp An arbitrary but unique collective op. identifier > 0.
271  * @param name Name of the collective operation e.g. "MPI_Bcast".
272  * @param type One of the five supported collective classes:
273  * OTF_COLLECTIVE_TYPE_UNKNOWN (default),
274  * OTF_COLLECTIVE_TYPE_BARRIER,
275  * OTF_COLLECTIVE_TYPE_ONE2ALL,
276  * OTF_COLLECTIVE_TYPE_ALL2ONE,
277  * OTF_COLLECTIVE_TYPE_ALL2ALL.
278  *
279  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
280  *
281  * @return OTF_RETURN_ABORT for aborting the reading process immediately
282  * OTF_RETURN_OK for continue reading
283  *
284  * \ingroup handler
285  */
286 int OTF_Handler_DefCollectiveOperation( void* userData,
287  uint32_t stream,
288  uint32_t collOp,
289  const char* name,
290  uint32_t type,
292 
293 
294 /**
295  * Provides a counter definition.
296  *
297  * @param userData Pointer to user data which can be set with
298  * OTF_HandlerArray_setFirstHandlerArg().
299  * @param stream Identifies the stream to which this definition
300  * belongs to. stream = 0 represents a global
301  * definition.
302  * @param counter An arbitrary but unique counter identifier.
303  * @param name Name of the counter e.g. "Cache Misses".
304  * @param properties A combination of a type, scope and vartype counter property.
305  * OTF_COUNTER_TYPE_ACC (default) represents a counter
306  * with monotonously increasing values e.g. a FLOP
307  * counter. OTF_COUNTER_TYPE_ABS on the other hand
308  * defines a counter with alternating absolute values e.g.
309  * the memory usage of a process. The following counter
310  * measurement scopes are supported:
311  * OTF_COUNTER_SCOPE_START (default) always refers to the
312  * start of the process, OTF_COUNTER_SCOPE_POINT refers
313  * to exactly this moment in time, OTF_COUNTER_SCOPE_LAST
314  * relates to the previous measurement, and
315  * OTF_COUNTER_SCOPE_NEXT to the next measurement.
316  * Examples: OTF_COUNTER_TYPE_ACC +
317  * OTF_COUNTER_SCOPE_START should be used for most
318  * standard hardware (PAPI) counters.
319  * OTF_COUNTER_TYPE_ABS + OTF_COUNTER_SCOPE_POINT could
320  * be used to record information 'spikes'.
321  * OTF_COUNTER_TYPE_ABS + OTF_COUNTER_SCOPE_NEXT works
322  * for memory allocation recording.
323  * The data type can be one of the following:
324  * COUNTER_VARTYPE_{UNSIGNED8,SIGNED8,UNSIGNED4,SIGNED4,
325  * UNSIGNED2,SIGNED2,DOUBLE,FLOAT}
326  * You may also use COUNTER_VARTYPE_IS{INTEGER,SIGNED,
327  * UNSIGNED}(property) to a get a clue about the data type.
328  * @param counterGroup A previously defined counter group identifier or 0 for
329  * no group.
330  * @param unit Unit of the counter e.g. "#" for "number of..." or 0
331  * for no unit.
332  *
333  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
334  *
335  * @return OTF_RETURN_ABORT for aborting the reading process immediately
336  * OTF_RETURN_OK for continue reading
337  *
338  * \ingroup handler
339  */
340 int OTF_Handler_DefCounter( void* userData,
341  uint32_t stream,
342  uint32_t counter,
343  const char* name,
344  uint32_t properties,
345  uint32_t counterGroup,
346  const char* unit,
348 
349 
350 /**
351  * Provides a counter group definition.
352  *
353  * @param userData Pointer to user data which can be set with
354  * OTF_HandlerArray_setFirstHandlerArg().
355  * @param stream Identifies the stream to which this definition
356  * belongs to. stream = 0 represents a global
357  * definition.
358  * @param counterGroup An arbitrary but unique counter group identifier > 0.
359  * @param name Counter group name.
360  *
361  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
362  *
363  * @return OTF_RETURN_ABORT for aborting the reading process immediately
364  * OTF_RETURN_OK for continue reading
365  *
366  * \ingroup handler
367  */
368 int OTF_Handler_DefCounterGroup( void* userData,
369  uint32_t stream,
370  uint32_t counterGroup,
371  const char* name,
373 
374 
375 /**
376  * Provides a source code location (SCL).
377  *
378  * @param userData Pointer to user data which can be set with
379  * OTF_HandlerArray_setFirstHandlerArg().
380  * @param stream Identifies the stream to which this definition
381  * belongs to. stream = 0 represents a global
382  * definition.
383  * @param source Arbitrary but unique source code location
384  * identifier > 0.
385  * @param sourceFile Previously defined source file identifier. See
386  * OTW_Handler_DefSclFile().
387  * @param line Line number.
388  *
389  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
390  *
391  * @return OTF_RETURN_ABORT for aborting the reading process immediately
392  * OTF_RETURN_OK for continue reading
393  *
394  * \ingroup handler
395  */
396 int OTF_Handler_DefScl( void* userData,
397  uint32_t stream,
398  uint32_t source,
399  uint32_t sourceFile,
400  uint32_t line,
402 
403 
404 /**
405  * Provides a source code location (SCL) file.
406  *
407  * @param userData Pointer to user data which can be set with
408  * OTF_HandlerArray_setFirstHandlerArg().
409  * @param stream Identifies the stream to which this definition
410  * belongs to. stream = 0 represents a global
411  * definition.
412  * @param sourceFile Arbitrary but unique source code location
413  * identifier != 0.
414  * @param name File name.
415  *
416  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
417  *
418  * @return OTF_RETURN_ABORT for aborting the reading process immediately
419  * OTF_RETURN_OK for continue reading
420  *
421  * \ingroup handler
422  */
423 int OTF_Handler_DefSclFile( void* userData,
424  uint32_t stream,
425  uint32_t sourceFile,
426  const char* name,
428 
429 
430 /**
431  * Provides file creator information.
432  *
433  * @param userData Pointer to user data which can be set with
434  * OTF_HandlerArray_setFirstHandlerArg().
435  * @param stream Identifies the stream to which this definition
436  * belongs to. stream = 0 represents a global
437  * definition.
438  * @param creator String which identifies the creator of the
439  * file e.g. "TAU Version x.y.z".
440  *
441  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
442  *
443  * @return OTF_RETURN_ABORT for aborting the reading process immediately
444  * OTF_RETURN_OK for continue reading
445  *
446  * \ingroup handler
447  */
448 int OTF_Handler_DefCreator( void* userData,
449  uint32_t stream,
450  const char* creator,
452 
453 
454 /**
455  * Provides information on the traceĀ“s otf-version. This record can only be read
456  * and not be written.
457  *
458  * @param userData Pointer to user data which can be set with
459  * OTF_HandlerArray_setFirstHandlerArg().
460  * @param stream Identifies the stream to which this definition
461  * belongs to. stream = 0 represents a global
462  * definition.
463  * @param major major version number
464  * @param minor minor version number
465  * @param sub sub version number
466  * @param string string identifing the version
467  *
468  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
469  *
470  * @return OTF_RETURN_ABORT for aborting the reading process immediately
471  * OTF_RETURN_OK for continue reading
472  *
473  * \ingroup handler
474  */
475 int OTF_Handler_DefVersion( void* userData,
476  uint32_t stream,
477  uint8_t major,
478  uint8_t minor,
479  uint8_t sub,
480  const char* string,
482 
483 
484 /**
485  * Provides a file definition
486  * NOTE: this is experimental
487  *
488  * @param userData Pointer to user data which can be set with
489  * OTF_HandlerArray_setFirstHandlerArg().
490  * @param stream Identifies the stream to which this definition
491  * belongs to. stream = 0 represents a global
492  * definition.
493  *
494  * @param token Arbitrary, unique identifier of the file.
495  * Has to be > 0.
496  *
497  * @param name name of the file
498  *
499  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
500  *
501  * @param group A previously defined file group identifier or 0 for
502  * no group.
503  *
504  * \ingroup handler
505  */
506 int OTF_Handler_DefFile( void* userData,
507  uint32_t stream,
508  uint32_t token,
509  const char *name,
510  uint32_t group,
512 
513 
514 /**
515  * Provides a file group definition
516  * NOTE: this is experimental
517  *
518  * @param userData Pointer to user data which can be set with
519  * OTF_HandlerArray_setFirstHandlerArg().
520  * @param stream Identifies the stream to which this definition
521  * belongs to. stream = 0 represents a global
522  * definition.
523  *
524  * @param token Arbitrary, unique identifier of the file group
525  * Has to be > 0.
526  *
527  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
528  *
529  * @param name Name of the file group
530  *
531  * \ingroup handler
532  */
533 int OTF_Handler_DefFileGroup( void* userData,
534  uint32_t stream,
535  uint32_t token,
536  const char *name,
538 
539 
540 /**
541  * Provides a KeyValue definition
542  *
543  * @param userData Pointer to user data which can be set with
544  * OTF_HandlerArray_setFirstHandlerArg().
545  * @param stream Identifies the stream to which this definition
546  * belongs to. stream = 0 represents a global
547  * definition.
548  *
549  * @param key Arbitrary, unique identifier of the KeyValue.
550  *
551  * @param type Type of the KeyValue. See OTF_Type().
552  *
553  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
554  *
555  * @param name Name of the KeyValue.
556  *
557  * @param description Description of the KeyValue.
558  *
559  * \ingroup handler
560  */
561 int OTF_Handler_DefKeyValue( void* userData,
562  uint32_t stream,
563  uint32_t key,
564  OTF_Type type,
565  const char *name,
566  const char *description,
568 
569 
570 /**
571  * Provides a TimeRange definition
572  *
573  * @param userData Pointer to user data which can be set with
574  * OTF_HandlerArray_setFirstHandlerArg().
575  * @param stream Identifies the stream to which this definition
576  * belongs to. stream = 0 represents a global
577  * definition.
578  *
579  * @param minTime The smallest timestamp of the events in this @a stream.
580  *
581  * @param maxTime The greates timestamp of the events in this @a stream (inclusive).
582  *
583  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
584  *
585  * \ingroup handler
586  */
587 int OTF_Handler_DefTimeRange( void* userData,
588  uint32_t stream,
589  uint64_t minTime,
590  uint64_t maxTime,
592 
593 
594 /**
595  * Provides a CounterAssignments definition
596  *
597  * @param userData Pointer to user data which can be set with
598  * OTF_HandlerArray_setFirstHandlerArg().
599  * @param stream Identifies the stream to which this definition
600  * belongs to. stream = 0 represents a global
601  * definition.
602  *
603  * @param counter Counter id.
604  *
605  * @param number_of_members Number of entries in @procs_or_groups array.
606  *
607  * @param procs_or_groups The processes or process groups which have recorded
608  * counter data for counter @counter.
609  *
610  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
611  *
612  * \ingroup handler
613  */
614 int OTF_Handler_DefCounterAssignments( void* userData,
615  uint32_t stream,
616  uint32_t counter,
617  uint32_t number_of_members,
618  const uint32_t* procs_or_groups,
620 
621 
622 /* Handlers for OTF event records ****************************************** */
623 
624 /**
625  * Provides a no-operation event. This event only stores a OTF_KeyValueList
626  * together with a process number and a timestamp.
627  *
628  * @param userData Pointer to user data which can be set with
629  * OTF_HandlerArray_setFirstHandlerArg().
630  * @param time The time associated with this event.
631  * @param process Process where action took place.
632  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
633  *
634  * @return OTF_RETURN_ABORT for aborting the reading process immediately
635  * OTF_RETURN_OK for continue reading
636  *
637  * \ingroup handler
638  */
639 int OTF_Handler_NoOp( void* userData,
640  uint64_t time,
641  uint32_t process,
643 
644 
645 /**
646  * Provides a function entry event.
647  *
648  * @param userData Pointer to user data which can be set with
649  * OTF_HandlerArray_setFirstHandlerArg().
650  * @param time The time when the function entry took place.
651  * @param function Function which has been entered as defined with
652  * OTF_Writer_defFunction.
653  * @param process Process where action took place.
654  * @param source Explicit source code location identifier > 0 or 0 if
655  * no source information available.
656  *
657  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
658  *
659  * @return OTF_RETURN_ABORT for aborting the reading process immediately
660  * OTF_RETURN_OK for continue reading
661  *
662  * \ingroup handler
663  */
664 int OTF_Handler_Enter( void* userData,
665  uint64_t time,
666  uint32_t function,
667  uint32_t process,
668  uint32_t source,
670 
671 
672 /**
673  * Provides a function leave event.
674  *
675  * @param userData Pointer to user data which can be set with
676  * OTF_HandlerArray_setFirstHandlerArg().
677  * @param time The time when the function leave took place.
678  * @param function Function which was left or 0 if stack integrety checking
679  * is not available.
680  * @param process Process where action took place.
681  * @param source Explicit source code location identifier > 0 or 0 if
682  * no source information available.
683  *
684  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
685  *
686  * @return OTF_RETURN_ABORT for aborting the reading process immediately
687  * OTF_RETURN_OK for continue reading
688  *
689  * \ingroup handler
690  */
691 int OTF_Handler_Leave( void* userData,
692  uint64_t time,
693  uint32_t function,
694  uint32_t process,
695  uint32_t source,
697 
698 
699 /**
700  * Provides a message send event.
701  *
702  * @param userData Pointer to user data which can be set with
703  * OTF_HandlerArray_setFirstHandlerArg().
704  * @param time The time when the message was send.
705  * @param sender Sender of the message.
706  * @param receiver Receiver of the message.
707  * @param group Process-group to which sender and receiver belong to or
708  * 0 for no group assignment.
709  * @param type Message type information > 0 or 0 for no information.
710  * @param length Optional message length information.
711  * @param source Explicit source code location identifier > 0 or 0 if
712  * no source information available.
713  *
714  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
715  *
716  * @return OTF_RETURN_ABORT for aborting the reading process immediately
717  * OTF_RETURN_OK for continue reading
718  *
719  * \ingroup handler
720  */
721 int OTF_Handler_SendMsg( void* userData,
722  uint64_t time,
723  uint32_t sender,
724  uint32_t receiver,
725  uint32_t group,
726  uint32_t type,
727  uint32_t length,
728  uint32_t source,
730 
731 
732 /**
733  * Provides a message retrieval event.
734  *
735  * @param userData Pointer to user data which can be set with
736  * OTF_HandlerArray_setFirstHandlerArg().
737  * @param time The time when the message was received.
738  * @param recvProc Identifier of receiving process.
739  * @param sendProc Identifier of sending process.
740  * @param group Process-group to which sender and receiver belong to or
741  * 0 for no group assignment.
742  * @param type Message type information > 0 or 0 for no information.
743  * @param length Optional message length information.
744  * @param source Explicit source code location identifier > 0 or 0 if
745  * no source information available.
746  *
747  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
748  *
749  * @return OTF_RETURN_ABORT for aborting the reading process immediately
750  * OTF_RETURN_OK for continue reading
751  *
752  * \ingroup handler
753  */
754 int OTF_Handler_RecvMsg( void* userData,
755  uint64_t time,
756  uint32_t recvProc,
757  uint32_t sendProc,
758  uint32_t group,
759  uint32_t type,
760  uint32_t length,
761  uint32_t source,
763 
764 
765 /**
766  * Provides a counter measurement.
767  *
768  * @param userData Pointer to user data which can be set with
769  * OTF_HandlerArray_setFirstHandlerArg().
770  * @param time Time when counter was measured.
771  * @param process Process where counter measurment took place.
772  * @param counter Counter which was measured.
773  * @param value Counter value.
774  *
775  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
776  *
777  * @return OTF_RETURN_ABORT for aborting the reading process immediately
778  * OTF_RETURN_OK for continue reading
779  *
780  * \ingroup handler
781  */
782 int OTF_Handler_Counter( void* userData,
783  uint64_t time,
784  uint32_t process,
785  uint32_t counter,
786  uint64_t value,
788 
789 
790 /**
791  * Provides a collective operation member event.
792  *
793  * @param userData Pointer to user data which can be set with
794  * OTF_HandlerArray_setFirstHandlerArg().
795  * @param time Time when collective operation was entered by member.
796  * @param process Process identifier i.e. collective member.
797  * @param collective Collective identifier as defined with
798  * OTF_Handler_DefCollectiveOperation().
799  * @param procGroup Group of processes participating in this collective.
800  * @param rootProc Root process if != 0.
801  * @param sent Data volume sent by member or 0.
802  * @param received Data volume received by member or 0.
803  * @param duration Time spent in collective operation.
804  * @param source Explicit source code location or 0.
805  *
806  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
807  *
808  * @return OTF_RETURN_ABORT for aborting the reading process immediately
809  * OTF_RETURN_OK for continue reading
810  *
811  * \ingroup handler
812  */
813 int OTF_Handler_CollectiveOperation( void* userData,
814  uint64_t time,
815  uint32_t process,
816  uint32_t collective,
817  uint32_t procGroup,
818  uint32_t rootProc,
819  uint32_t sent,
820  uint32_t received,
821  uint64_t duration,
822  uint32_t source,
824 
825 
826 /**
827  * Provides a begin collective operation member event.
828  *
829  * @param userData Pointer to user data which can be set with
830  * OTF_HandlerArray_setFirstHandlerArg().
831  * @param time Time when collective operation was entered by member.
832  * @param process Process identifier i.e. collective member.
833  * @param collOp Collective identifier to be defined with
834  * OTF_Writer_writeDefCollectiveOperation().
835  * @param matchingId Identifier for finding the associated end collective event
836  * record. It must be unique within this process.
837  * @param procGroup Group of processes participating in this collective.
838  * @param rootProc Root process if != 0.
839  * @param sent Data volume sent by member or 0.
840  * @param received Data volume received by member or 0.
841  * @param scltoken Explicit source code location or 0.
842  *
843  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
844  *
845  * @return 1 on success, 0 if an error occurs.
846  *
847  * \ingroup handler
848  */
849 int OTF_Handler_BeginCollectiveOperation( void* userData,
850  uint64_t time,
851  uint32_t process,
852  uint32_t collOp,
853  uint64_t matchingId,
854  uint32_t procGroup,
855  uint32_t rootProc,
856  uint64_t sent,
857  uint64_t received,
858  uint32_t scltoken,
860 
861 
862 /**
863  * Provides an end collective operation member event.
864  *
865  * @param userData Pointer to user data which can be set with
866  * OTF_HandlerArray_setFirstHandlerArg().
867  * @param time Time when collective operation was entered by member.
868  * @param process Process identifier i.e. collective member.
869  * @param matchingId Matching identifier, must match a previous start
870  * collective operation.
871  *
872  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
873  *
874  * @return 1 on success, 0 if an error occurs.
875  *
876  * \ingroup handler
877  */
878 int OTF_Handler_EndCollectiveOperation( void* userData,
879  uint64_t time,
880  uint32_t process,
881  uint64_t matchingId,
883 
884 
885 /**
886  * Provide a comment record.
887  *
888  * @param userData Pointer to user data which can be set with
889  * OTF_HandlerArray_setFirstHandlerArg().
890  * @param time Comments need a timestamp for a proper positioning in the
891  * trace.
892  * @param process Comments also need a process identifier for a proper
893  * positioning in the trace.
894  * @param comment Arbitrary comment string.
895  *
896  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
897  *
898  * @return OTF_RETURN_ABORT for aborting the reading process immediately
899  * OTF_RETURN_OK for continue reading
900  *
901  * \ingroup handler
902  */
903 int OTF_Handler_EventComment( void* userData,
904  uint64_t time,
905  uint32_t process,
906  const char* comment,
908 
909 
910 /**
911  * Provides a process creation event.
912  *
913  * Marks the explicit begin of a process. This event precedes the very first
914  * event of the respective process and should carry the same time stamp. This
915  * is especially useful with on-line analysis. It tells whether there will be
916  * additional records for the given process or not. Without this record type,
917  * it could only be guessed that there might not follow more events after a
918  * process has reached the bottom of the call stack.
919  *
920  * @param userData Pointer to user data which can be set with
921  * OTF_HandlerArray_setFirstHandlerArg().
922  * @param time Time when process was referenced for the first time.
923  * @param process Process identifier > 0.
924  *
925  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
926  *
927  * @return OTF_RETURN_ABORT for aborting the reading process immediately
928  * OTF_RETURN_OK for continue reading
929  *
930  * \ingroup handler
931  */
932 int OTF_Handler_BeginProcess( void* userData,
933  uint64_t time,
934  uint32_t process,
936 
937 
938 /**
939  * Provides a process destruction event.
940  *
941  * @param userData Pointer to user data which can be set with
942  * OTF_HandlerArray_setFirstHandlerArg().
943  * @param time Time when process is referenced for the last time.
944  * Process identifiers must not be recycled!
945  * @param process Process identifier > 0.
946  *
947  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
948  *
949  * @return OTF_RETURN_ABORT for aborting the reading process immediately
950  * OTF_RETURN_OK for continue reading
951  *
952  * \ingroup handler
953  */
954 int OTF_Handler_EndProcess( void* userData,
955  uint64_t time,
956  uint32_t process,
958 
959 
960 /**
961  * Provides a file operation event
962  * NOTE: this is experimental
963  *
964  * @param userData Pointer to user data which can be set with
965  * OTF_HandlerArray_setFirstHandlerArg().
966  * @param time Time when process is referenced for the last time.
967  * Process identifiers must not be recycled!
968  * @param process Process identifier > 0.
969  *
970  * @param handleid Unique identifier. This parameter is important
971  * for files that are opened multiple times at the same time,
972  * to match the close to the correct open.
973  * This number has to be unique for every opened file (
974  * Files with the same id must have different handleid !!! ).
975  * Recommendation: use the timestamp of the openfile record,
976  * or an increasing(with every fileopen record) variable for
977  * this.
978  *
979  * @param operation Kind of operation done on the file and flags further
980  * describing the operation.
981  * The macro OTF_FILEOP(operation) should be used to check
982  * for the kind of I/O operation.
983  * - OTF_FILEOP(operation) can be checked for equality on
984  * - OTF_FILEOP_OPEN -- open a file
985  * - OTF_FILEOP_CLOSE -- close a file
986  * - OTF_FILEOP_READ -- read some bytes off a file
987  * - OTF_FILEOP_WRITE -- write some bytes to a file
988  * - OTF_FILEOP_SEEK -- set the file pointer
989  * - OTF_FILEOP_UNLINK -- delete a file
990  * - OTF_FILEOP_RENAME -- rename a file
991  * - OTF_FILEOP_DUP -- duplicate a file desriptor
992  * - OTF_FILEOP_SYNC -- write dirty buffers to disk
993  * - OTF_FILEOP_LOCK -- acquire a file lock
994  * - OTF_FILEOP_UNLOCK -- release a file lock
995  * - OTF_FILEOP_OTHER -- none of the above
996  * - The following flags are supported and can be checked
997  * bit-wise for existence in operation:
998  * - OTF_IOFLAG_IOFAILED -- e.g. could not open file,
999  * could not read or write all bytes, a lock could not be
1000  * acquired, a rename operation failed, etc.
1001  * - OTF_IOFLAG_ASYNC -- I/O is done asynchronously
1002  * - OTF_IOFLAG_COLL -- this is a collective I/O operation
1003  * - OTF_IOFLAG_DIRECT -- I/O is done bypassing the cache
1004  * - OTF_IOFLAG_SYNC -- I/O is done synchronously
1005  * - OTF_IOFLAG_ISREADLOCK -- lock is a read-only file
1006  * lock
1007  *
1008  * @param bytes Should be 0 for open and close.
1009  * Number of read/written bytes for read/write operations.
1010  * New position in the file after a seek operation.
1011  *
1012  * @param duration Time spent in the file operation.
1013  *
1014  * @param source Explicit source code location or 0.
1015  *
1016  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1017  *
1018  * \ingroup handler
1019  */
1020 int OTF_Handler_FileOperation( void* userData,
1021  uint64_t time,
1022  uint32_t fileid,
1023  uint32_t process,
1024  uint64_t handleid,
1025  uint32_t operation,
1026  uint64_t bytes,
1027  uint64_t duration,
1028  uint32_t source,
1030 
1031 
1032 /**
1033  * Write a begin file operation record
1034  *
1035  * @param userData Pointer to user data which can be set with
1036  * OTF_HandlerArray_setFirstHandlerArg().
1037  * @param time Start time of file operation.
1038  * @param process Process identifier > 0.
1039  * @param matchingId Operation identifier, used for finding the associated end
1040  * file operation event record.
1041  * @param scltoken Optional reference to source code.
1042  *
1043  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1044  *
1045  * @return 1 on success, 0 if an error occurs.
1046  *
1047  * \ingroup handler
1048  */
1049 int OTF_Handler_BeginFileOperation( void* userData,
1050  uint64_t time,
1051  uint32_t process,
1052  uint64_t matchingId,
1053  uint32_t scltoken,
1055 
1056 
1057 /**
1058  * Write an end file operation record
1059  *
1060  * @param userData Pointer to user data which can be set with
1061  * OTF_HandlerArray_setFirstHandlerArg().
1062  * @param time End time of file operation.
1063  * @param process Process identifier > 0.
1064  * @param fileid File identifier > 0.
1065  * @param matchingId Operation identifier, must match a previous start file
1066  * operation event record.
1067  * @param handleId Unique file open identifier.
1068  * @param operation Type of file operation. See OTF_Handler_FileOperation().
1069  * @param bytes Depends on operation. See OTF_Handler_FileOperation().
1070  * @param scltoken Optional reference to source code.
1071  *
1072  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1073  *
1074  * @return 1 on success, 0 if an error occurs.
1075  *
1076  * \ingroup handler
1077  */
1078 int OTF_Handler_EndFileOperation( void* userData,
1079  uint64_t time,
1080  uint32_t process,
1081  uint32_t fileid,
1082  uint64_t matchingId,
1083  uint64_t handleId,
1084  uint32_t operation,
1085  uint64_t bytes,
1086  uint32_t scltoken,
1088 
1089 
1090 /**
1091  * Provides a RMA put event - end marker is anticipated on initiating Process.
1092  * NOTE: this is experimental
1093  *
1094  * @param userData Pointer to user data which can be set with
1095  * OTF_HandlerArray_setFirstHandlerArg().
1096  * @param time Time when process is referenced for the last time.
1097  * Process identifiers must not be recycled!
1098  * @param process Process identifier > 0.
1099  * This is the Process that initiates the transfer.
1100  * @param origin If >0, Process whose memory will be transferred, instead
1101  of this <process>.
1102  * @param target Process whose memory will be written.
1103  * @param communicator Together with tag, it is used to identify the
1104  * corresponding RMA end record. This will be the process
1105  * group of the RMA Window in case of MPI one-sided
1106  * communication.
1107  * @param tag Together with communicator, it is used to identify the
1108  * corresponding RMA end record. Usually this will be counted
1109  * upwards to distinguish multiple transfer sections with the
1110  * same communicator BUT THIS IS NOT MANDATORY, i.e. multiple
1111  * RMA end records with the same comm/tag combination may
1112  * exist.
1113  * @param bytes Number of bytes that have been transferred by this call.
1114  * @param source Explicit source code location or 0.
1115  *
1116  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1117  *
1118  * @return 1 on success, 0 if an error occurs.
1119  *
1120  * \ingroup handler
1121  */
1122 int OTF_Handler_RMAPut( void* userData,
1123  uint64_t time,
1124  uint32_t process,
1125  uint32_t origin,
1126  uint32_t target,
1127  uint32_t communicator,
1128  uint32_t tag,
1129  uint64_t bytes,
1130  uint32_t source,
1132 
1133 /**
1134  * Provides a RMA put event with remote finalization marker, i.e. RMA end marker
1135  * is anticipated on target Process.
1136  * NOTE: this is experimental
1137  *
1138  * @param userData Pointer to user data which can be set with
1139  * OTF_HandlerArray_setFirstHandlerArg().
1140  * @param time Time when process is referenced for the last time.
1141  * Process identifiers must not be recycled!
1142  * @param process Process identifier > 0.
1143  * This is the Process that initiates the transfer.
1144  * @param origin If >0, Process whose memory will be transferred, instead
1145  of this <process>.
1146  * @param target Process whose memory will be written.
1147  * That Process' stream will also carry the end record for
1148  * this transaction.
1149  * @param communicator Together with tag, it is used to identify the
1150  * corresponding RMA end record. This will be the process
1151  * group of the RMA Window in case of MPI one-sided
1152  * communication.
1153  * @param tag Together with communicator, it is used to identify the
1154  * corresponding RMA end record. Usually this will be counted
1155  * upwards to distinguish multiple transfer sections with the
1156  * same communicator BUT THIS IS NOT MANDATORY, i.e. multiple
1157  * RMA end records with the same comm/tag combination may
1158  * exist.
1159  * @param bytes Number of bytes that have been transferred by this call.
1160  * @param source Explicit source code location or 0.
1161  *
1162  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1163  *
1164  * @return 1 on success, 0 if an error occurs.
1165  *
1166  * \ingroup handler
1167  */
1168 int OTF_Handler_RMAPutRemoteEnd( void* userData,
1169  uint64_t time,
1170  uint32_t process,
1171  uint32_t origin,
1172  uint32_t target,
1173  uint32_t communicator,
1174  uint32_t tag,
1175  uint64_t bytes,
1176  uint32_t source,
1178 
1179 /**
1180  * Provides a RMA get event - end marker is anticipated on initiating Process.
1181  * NOTE: this is experimental
1182  *
1183  * @param userData Pointer to user data which can be set with
1184  * OTF_HandlerArray_setFirstHandlerArg().
1185  * @param time Time when process is referenced for the last time.
1186  * Process identifiers must not be recycled!
1187  * @param process Process identifier > 0.
1188  * This is the Process that initiates the transfer.
1189  * @param origin If >0, the Process whose memory will receive the data
1190  * from <target>, instead of this <process>.
1191  * @param target Process whose memory will be read.
1192  * @param communicator Together with tag, it is used to identify the
1193  * corresponding RMA end record. This will be the process
1194  * group of the RMA Window in case of MPI one-sided
1195  * communication.
1196  * @param tag Together with communicator, it is used to identify the
1197  * corresponding RMA end record. Usually this will be counted
1198  * upwards to distinguish multiple transfer sections with the
1199  * same communicator BUT THIS IS NOT MANDATORY, i.e. multiple
1200  * RMA end records with the same comm/tag combination may
1201  * exist.
1202  * @param bytes Number of bytes that have been transferred by this call.
1203  * @param source Explicit source code location or 0.
1204  *
1205  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1206  *
1207  * @return 1 on success, 0 if an error occurs.
1208  *
1209  * \ingroup handler
1210  */
1211 int OTF_Handler_RMAGet( void* userData,
1212  uint64_t time,
1213  uint32_t process,
1214  uint32_t origin,
1215  uint32_t target,
1216  uint32_t communicator,
1217  uint32_t tag,
1218  uint64_t bytes,
1219  uint32_t source,
1221 
1222 /**
1223  * Provide a RMA end event.
1224  * The end record marks the finalization of all RMA operations with the
1225  * communicator and tag.
1226  *
1227  * @param userData Pointer to user data which can be set with
1228  * OTF_HandlerArray_setFirstHandlerArg().
1229  * @param time Time when process is referenced for the last time.
1230  * Process identifiers must not be recycled!
1231  * @param process Process identifier > 0.
1232  * @param remote If >0, ends RMA transfers on Process <remote>, instead of
1233  this <process>.
1234  * @param communicator Together with tag, it is used to identify the related RMA
1235  * transfer records.
1236  * @param tag Together with communicator, it is used to identify the
1237  * related RMA transfer records.
1238  * @param source Explicit source code location or 0.
1239  *
1240  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1241  *
1242  * @return 1 on success, 0 if an error occurs.
1243  *
1244  * \ingroup handler
1245  */
1246 int OTF_Handler_RMAEnd( void* userData,
1247  uint64_t time,
1248  uint32_t process,
1249  uint32_t remote,
1250  uint32_t communicator,
1251  uint32_t tag,
1252  uint32_t source,
1254 
1255 
1256 /* Handlers for OTF snapshot records *************************************** */
1257 
1258 
1259 /**
1260  * Provides a snapshot comment.
1261  *
1262  * @param userData Pointer to user data which can be set with
1263  * OTF_HandlerArray_setFirstHandlerArg().
1264  * @param time Comments need a timestamp for a proper positioning in the
1265  * trace.
1266  * @param process Comments also need a process identifier for a proper
1267  * positioning in the trace.
1268  * @param comment Arbitrary comment string.
1269  *
1270  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1271  *
1272  * @return OTF_RETURN_ABORT for aborting the reading process immediately
1273  * OTF_RETURN_OK for continue reading
1274  *
1275  * \ingroup handler
1276  */
1277 
1278 int OTF_Handler_SnapshotComment( void* userData,
1279  uint64_t time,
1280  uint32_t process,
1281  const char* comment,
1283 
1284 
1285 /** provides information about a past function call at the time 'originaltime'.
1286 Parameters 'time', 'function', 'process' ,'source' and the return value have the
1287 same meaning as in OTF_Handler_Enter().
1288 \ingroup handler */
1289 int OTF_Handler_EnterSnapshot( void *userData,
1290  uint64_t time,
1291  uint64_t originaltime,
1292  uint32_t function,
1293  uint32_t process,
1294  uint32_t source,
1296 
1297 
1298 /** provides information about a past message send operation at the time
1299 'originaltime'. Parameters 'time', 'sender', 'receiver', 'procGroup', 'tag', 'length',
1300 'source' and the return value have the same meaning as in OTF_Handler_SendMsg().
1301 \ingroup handler */
1302 int OTF_Handler_SendSnapshot( void *userData,
1303  uint64_t time,
1304  uint64_t originaltime,
1305  uint32_t sender,
1306  uint32_t receiver,
1307  uint32_t procGroup,
1308  uint32_t tag,
1309  uint32_t length,
1310  uint32_t source,
1312 
1313 
1314 /**
1315  * Provides a snapshot record for opened(and not yet closed) files
1316  *
1317  * @param userData Pointer to user data which can be set with
1318  * OTF_HandlerArray_setFirstHandlerArg().
1319  * @param time Current timestamp.
1320  * @param originaltime Timestamp when the file has been opened.
1321  * @param process Process identifier.
1322  * @param handleid Unique file open identifier. See
1323  * OTF_Handler_FileOperation().
1324  * @param source Optional reference to source code.
1325  *
1326  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1327  *
1328  * \ingroup handler
1329  */
1330 int OTF_Handler_OpenFileSnapshot( void* userData,
1331  uint64_t time,
1332  uint64_t originaltime,
1333  uint32_t fileid,
1334  uint32_t process,
1335  uint64_t handleid,
1336  uint32_t source,
1338 
1339 
1340 /**
1341  * Provides a snapshot record for unfinished collective operations
1342  *
1343  * @param userData Pointer to user data which can be set with
1344  * OTF_HandlerArray_setFirstHandlerArg().
1345  * @param time Current timestamp.
1346  * @param originaltime Time when the collective operation began.
1347  * @param process Process identifier.
1348  * @param collOp Collective identifier to be defined with
1349  * OTF_Writer_writeDefCollectiveOperation().
1350  * @param matchingId Identifier for finding the associated end collective event
1351  * record. It must be unique within this procGroup.
1352  * @param procGroup Group of processes participating in this collective.
1353  * @param rootProc Root process if != 0.
1354  * @param sent Data volume sent by member or 0.
1355  * @param received Data volume received by member or 0.
1356  * @param scltoken Optional reference to source code.
1357  *
1358  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1359  *
1360  * \ingroup handler
1361  */
1362 int OTF_Handler_BeginCollopSnapshot ( void* userData,
1363  uint64_t time,
1364  uint64_t originaltime,
1365  uint32_t process,
1366  uint32_t collOp,
1367  uint64_t matchingId,
1368  uint32_t procGroup,
1369  uint32_t rootProc,
1370  uint64_t sent,
1371  uint64_t received,
1372  uint32_t scltoken,
1374 /**
1375  * @param userData Pointer to user data which can be set with
1376  * OTF_HandlerArray_setFirstHandlerArg().
1377  * @param time Current timestamp.
1378  * @param originaltime Timestamp when the file has been opened.
1379  * @param process Process identifier.
1380  * @param matchingId Identifier for finding the associated end file operation event
1381  * record. It must be unique.
1382  * @param scltoken Optional reference to source code.
1383  *
1384  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1385  *
1386  * \ingroup handler
1387  */
1388 int OTF_Handler_BeginFileOpSnapshot ( void* userData,
1389  uint64_t time,
1390  uint64_t originaltime,
1391  uint32_t process,
1392  uint64_t matchingId,
1393  uint32_t scltoken,
1395 
1396 
1397 /* Handlers for OTF summary records **************************************** */
1398 
1399 
1400 /** Provides a summary comment.
1401  *
1402  * @param userData Pointer to user data which can be set with
1403  * OTF_HandlerArray_setFirstHandlerArg().
1404  * @param time Comments need a timestamp for a proper positioning in the
1405  * trace.
1406  * @param process Comments also need a process identifier for a proper
1407  * positioning in the trace.
1408  * @param comment Arbitrary comment string.
1409  *
1410  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1411  *
1412  * @return OTF_RETURN_ABORT for aborting the reading process immediately
1413  * OTF_RETURN_OK for continue reading
1414  *
1415  * \ingroup handler
1416  */
1417 
1418 int OTF_Handler_SummaryComment( void * userData,
1419  uint64_t time,
1420  uint32_t process,
1421  const char* comment,
1423 
1424 
1425 /**
1426  * Provides summarized information for a given function.
1427  *
1428  * @param userData Pointer to user data which can be set with
1429  * OTF_HandlerArray_setFirstHandlerArg().
1430  * @param time Time when summary was computed.
1431  * @param function Function as defined with
1432  * OTF_Handler_DefFunction.
1433  * @param process Process of the given function.
1434  * @param invocations Number of invocations.
1435  * @param exclTime Time spent exclusively in the given function.
1436  * @param inclTime Time spent in the given function including all
1437  * sub-routine calls.
1438  *
1439  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1440  *
1441  * @return OTF_RETURN_ABORT for aborting the reading process immediately
1442  * OTF_RETURN_OK for continue reading
1443  *
1444  * \ingroup handler
1445  */
1446 int OTF_Handler_FunctionSummary( void* userData,
1447  uint64_t time,
1448  uint32_t function,
1449  uint32_t process,
1450  uint64_t invocations,
1451  uint64_t exclTime,
1452  uint64_t inclTime,
1454 
1455 
1456 /**
1457  * Provides summarized information for a given group of functiongroups.
1458  *
1459  * @param userData Pointer to user data which can be set with
1460  * OTF_HandlerArray_setFirstHandlerArg().
1461  * @param time Time when summary was computed.
1462  * @param funcGroup Function group as defined with
1463  * OTF_Handler_DefFunctionGroup.
1464  * @param process Process of the given function group.
1465  * @param invocations Number of invocations.
1466  * @param exclTime Time spent exclusively in the given function group.
1467  * @param inclTime Time spent in the given function group including all
1468  * sub-routine calls.
1469  *
1470  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1471  *
1472  * @return OTF_RETURN_ABORT for aborting the reading process immediately
1473  * OTF_RETURN_OK for continue reading
1474  *
1475  * \ingroup handler
1476  */
1477 int OTF_Handler_FunctionGroupSummary( void* userData,
1478  uint64_t time,
1479  uint32_t funcGroup,
1480  uint32_t process,
1481  uint64_t invocations,
1482  uint64_t exclTime,
1483  uint64_t inclTime,
1485 
1486 
1487 /**
1488  * Provides summarized information for a given message type.
1489  *
1490  * @param userData Pointer to user data which can be set with
1491  * OTF_HandlerArray_setFirstHandlerArg().
1492  * @param time Time when summary was computed.
1493  * @param process Process where messages originated.
1494  * @param peer Process where the message is sent to
1495  * @param comm Communicator of message summary
1496  * @param type Message type/tag.
1497  * @param sentNumber The number of messages sent.
1498  * @param receivedNumber The number of messages received.
1499  * @param sentBytes The number of bytes sent via messages of the given
1500  * type.
1501  * @param receivedBytes The number of bytes received through messages of the
1502  * given type.
1503  *
1504  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1505  *
1506  * @return OTF_RETURN_ABORT for aborting the reading process immediately
1507  * OTF_RETURN_OK for continue reading
1508  *
1509  * \ingroup handler
1510  */
1511 int OTF_Handler_MessageSummary( void* userData,
1512  uint64_t time,
1513  uint32_t process,
1514  uint32_t peer,
1515  uint32_t comm,
1516  uint32_t type,
1517  uint64_t sentNumber,
1518  uint64_t receivedNumber,
1519  uint64_t sentBytes,
1520  uint64_t receivedBytes,
1522 
1523 
1524 /**
1525  * Provides summarized information for collective operations.
1526  *
1527  * @param userData Pointer to user data which can be set with
1528  * OTF_HandlerArray_setFirstHandlerArg().
1529  * @param time Time when summary was computed.
1530  * @param process Process identifier i.e. collective member.
1531  * @param comm Communicator of collective operation summary.
1532  * @param collective Collective identifier as defined with
1533  * OTF_Handler_DefCollectiveOperation().
1534  * @param sentNumber The number of messages sent by member or 0.
1535  * @param receivedNumber The number of messages received by member or 0.
1536  * @param sentBytes The number of bytes sent by member or 0.
1537  * @param receivedBytes The number of bytes received by member or 0.
1538  *
1539  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1540  *
1541  * @return OTF_RETURN_ABORT for aborting the reading process immediately
1542  * OTF_RETURN_OK for continue reading
1543  *
1544  * \ingroup handler
1545  */
1546 int OTF_Handler_CollopSummary( void *userData,
1547  uint64_t time,
1548  uint32_t process,
1549  uint32_t comm,
1550  uint32_t collective,
1551  uint64_t sentNumber,
1552  uint64_t receivedNumber,
1553  uint64_t sentBytes,
1554  uint64_t receivedBytes,
1556 
1557 
1558 /**
1559  * Provides summarized information about file operations.
1560  *
1561  * @param userData Pointer to user data which can be set with
1562  * OTF_HandlerArray_setFirstHandlerArg().
1563  * @param time Time when summary was computed.
1564  * @param fileid File identifier or 0 for all files.
1565  * @param process Process where file operations occured.
1566  * @param nopen Number of open events.
1567  * @param nclose Number of close events.
1568  * @param nread Number of read events.
1569  * @param nwrite Number of write events.
1570  * @param nseek Number of seek events.
1571  * @param bytesread Number of bytes read.
1572  * @param byteswrite Number of bytes written.
1573  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1574  *
1575  * \ingroup handler
1576  */
1577 int OTF_Handler_FileOperationSummary( void* userData,
1578  uint64_t time,
1579  uint32_t fileid,
1580  uint32_t process,
1581  uint64_t nopen,
1582  uint64_t nclose,
1583  uint64_t nread,
1584  uint64_t nwrite,
1585  uint64_t nseek,
1586  uint64_t bytesread,
1587  uint64_t byteswrite,
1589 
1590 
1591 /**
1592  * Provides summarized information about file operations in a file group.
1593  *
1594  * @param userData Pointer to user data which can be set with
1595  * OTF_HandlerArray_setFirstHandlerArg().
1596  * @param time Time when summary was computed.
1597  * @param groupid Group identifier or 0 for all files.
1598  * @param process Process where file operations occured.
1599  * @param nopen Number of open events.
1600  * @param nclose Number of close events.
1601  * @param nread Number of read events.
1602  * @param nwrite Number of write events.
1603  * @param nseek Number of seek events.
1604  * @param bytesread Number of bytes read.
1605  * @param byteswrite Number of bytes written.
1606  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1607  *
1608  * \ingroup handler
1609  */
1610 int OTF_Handler_FileGroupOperationSummary( void* userData,
1611  uint64_t time,
1612  uint32_t groupid,
1613  uint32_t process,
1614  uint64_t nopen,
1615  uint64_t nclose,
1616  uint64_t nread,
1617  uint64_t nwrite,
1618  uint64_t nseek,
1619  uint64_t bytesread,
1620  uint64_t byteswrite,
1622 
1623 
1624 /**
1625  * Can be used to handle records which cannot be read.
1626  *
1627  * @param userData Pointer to user data which can be set with
1628  * OTF_HandlerArray_setFirstHandlerArg().
1629  * @param time Time when summary was computed.
1630  * @param process If 'time' equals (uin64_t) -1, the unknown record
1631  * is a definiton record and 'process'
1632  * represents the streamid of the record.
1633  * If 'time' has a valid value ( not (uint64)-1 ) the
1634  * unknown record is an event-, statistics- or
1635  * snapshotrecord and 'process' represents
1636  * the processid of the record.
1637  * @param record string which contains the record.
1638  *
1639  * @return OTF_RETURN_ABORT for aborting the reading process immediately
1640  * OTF_RETURN_OK for continue reading
1641  *
1642  * \ingroup handler
1643  */
1644 int OTF_Handler_UnknownRecord( void *userData,
1645  uint64_t time,
1646  uint32_t process,
1647  const char *record );
1648 
1649 
1650 /*
1651  * Provides summarized information about a counter.
1652  *
1653  * @param userData Pointer to user data which can be set with
1654  * OTF_HandlerArray_setFirstHandlerArg().
1655  * @param time Time when summary was computed.
1656  * @param process Process where messages originated.
1657  * @param peer Token of counter.
1658  * @param value Counter Value at current time.
1659  *
1660  * \ingroup handler
1661  */
1662 /*int OTF_Handler_CounterSummary( void* userData,
1663  uint64_t time,
1664  uint32_t process,
1665  uint32_t counterid,
1666  uint64_t value );
1667 */
1668 
1669 
1670 /* Handlers for OTF marker records **************************************** */
1671 
1672 
1673 /**
1674  * Define a marker
1675  *
1676  * @param userData Pointer to user data which can be set with
1677  * OTF_HandlerArray_setFirstHandlerArg().
1678  * @param stream stream ID is ignored here
1679  * @param token The newly defined marker token.
1680  * @param name Its name
1681  * @param type Marker type, one of OTF_MARKER_TYPE_xxx
1682  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1683  *
1684  * @return OTF_RETURN_ABORT for aborting the reading process immediately
1685  * OTF_RETURN_OK for continue reading
1686  *
1687  * \ingroup handler
1688  */
1689 int OTF_Handler_DefMarker( void *userData,
1690  uint32_t stream,
1691  uint32_t token,
1692  const char* name,
1693  uint32_t type,
1695 
1696 
1697 /**
1698  * Define a marker
1699  *
1700  * @param userData Pointer to user data which can be set with
1701  * OTF_HandlerArray_setFirstHandlerArg().
1702  * @param time Time stamp of the marker record. Note that marker records are
1703  * not sorted according to time stamps!
1704  * @param process The process or process group of the marker.
1705  * @param token A marker token defined by 'DefMarker' before.
1706  * @param text Descriptive text.
1707  * @param list Pointer to an OTF_KeyValueList() that contains individual data.
1708  *
1709  * @return OTF_RETURN_ABORT for aborting the reading process immediately
1710  * OTF_RETURN_OK for continue reading
1711  *
1712  * \ingroup handler
1713  */
1714 int OTF_Handler_Marker( void *userData,
1715  uint64_t time,
1716  uint32_t process,
1717  uint32_t token,
1718  const char* text,
1720 
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.
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.
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.
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.
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.
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.
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'.
int OTF_Handler_DefTimeRange(void *userData, uint32_t stream, uint64_t minTime, uint64_t maxTime, OTF_KeyValueList *list)
Provides a TimeRange definition.
int OTF_Handler_DefFunctionGroup(void *userData, uint32_t stream, uint32_t funcGroup, const char *name, OTF_KeyValueList *list)
Provides a function group definition.
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.
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.
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.
int OTF_Handler_EventComment(void *userData, uint64_t time, uint32_t process, const char *comment, OTF_KeyValueList *list)
Provide a comment record.
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.
int OTF_Handler_BeginProcess(void *userData, uint64_t time, uint32_t process, OTF_KeyValueList *list)
Provides a process creation event.
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.
int OTF_Handler_DefCounterGroup(void *userData, uint32_t stream, uint32_t counterGroup, const char *name, OTF_KeyValueList *list)
Provides a counter group definition.
int OTF_Handler_Marker(void *userData, uint64_t time, uint32_t process, uint32_t token, const char *text, OTF_KeyValueList *list)
Define a marker.
int OTF_Handler_DefMarker(void *userData, uint32_t stream, uint32_t token, const char *name, uint32_t type, OTF_KeyValueList *list)
Define a marker.
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.
int OTF_Handler_NoOp(void *userData, uint64_t time, uint32_t process, OTF_KeyValueList *list)
Provides a no-operation event.
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.
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.
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.
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.
int OTF_Handler_SummaryComment(void *userData, uint64_t time, uint32_t process, const char *comment, OTF_KeyValueList *list)
Provides a summary comment.
int OTF_Handler_EndProcess(void *userData, uint64_t time, uint32_t process, OTF_KeyValueList *list)
Provides a process destruction event.
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.
OTF_FileList * list
list of objects of type OTF_RBuffer or OTF_WBuffer
Definition: OTF_FileManager.c:41
int OTF_Handler_DefinitionComment(void *userData, uint32_t stream, const char *comment, OTF_KeyValueList *list)
Provides a comment record.
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.
enum OTF_ATTR_TYPE_enum OTF_ATTR_TYPE
An enum which holds all values that are possible to set with datatype OTF_ATTR_TYPE().
enum OTF_Type_enum OTF_Type
An enum which holds all OTF datatypes that are relevant for OTF_KeyValueList.
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.
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.
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.
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).
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.
int OTF_Handler_DefCreator(void *userData, uint32_t stream, const char *creator, OTF_KeyValueList *list)
Provides file creator information.
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.
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.
int OTF_Handler_DefTimerResolution(void *userData, uint32_t stream, uint64_t ticksPerSecond, OTF_KeyValueList *list)
Provides the timer resolution.
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.
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.
Provides an additional list of key value pairs that can be added to records.
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.
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.
struct OTF_KeyValueList_struct OTF_KeyValueList
Object type which holds a key-value list.
Definition: OTF_KeyValue.h:242
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.
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.
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.
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.
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.
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.
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.
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_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.
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'.
int OTF_Handler_SnapshotComment(void *userData, uint64_t time, uint32_t process, const char *comment, OTF_KeyValueList *list)
Provides a snapshot comment.
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.