OpenMPI  0.1.1
vt_plugin_cntr.h
1 /**
2  * VampirTrace
3  * http://www.tu-dresden.de/zih/vampirtrace
4  *
5  * Copyright (c) 2005-2012, ZIH, TU Dresden, Federal Republic of Germany
6  *
7  * Copyright (c) 1998-2005, Forschungszentrum Juelich, Juelich Supercomputing
8  * Centre, Federal Republic of Germany
9  *
10  * See the file COPYING in the package base directory for details
11  **/
12 
13 #ifndef _VT_PLUGIN_CNTR_H
14 #define _VT_PLUGIN_CNTR_H
15 
16 #include "vt_inttypes.h"
17 
18 
19 
20 /* use this enum to define the synch type of your plugin */
21 enum vt_plugin_cntr_synch {
22  VT_PLUGIN_CNTR_SYNCH = 0,
23  VT_PLUGIN_CNTR_ASYNCH_EVENT,
24  VT_PLUGIN_CNTR_ASYNCH_POST_MORTEM,
25  VT_PLUGIN_CNTR_ASYNCH_CALLBACK,
26  VT_PLUGIN_CNTR_SYNCH_TYPE_MAX /* NON-ABI, don't use it!*/
27 };
28 
29 /* use this enum to define how often a metric should be measured*/
30 
31 enum vt_plugin_cntr_per {
32  VT_PLUGIN_CNTR_PER_THREAD = 0,
33  VT_PLUGIN_CNTR_PER_PROCESS,
34  VT_PLUGIN_CNTR_PER_HOST,
35  VT_PLUGIN_CNTR_ONCE,
36  VT_PLUGIN_CNTR_RUN_PER_MAX /* NON-ABI, don't use it!*/
37 };
38 
39 /* use this enum to check your callback function's return value
40  * (only use it with VT_PLUGIN_CNTR_ASYNCH_CALLBACK plugins) */
41 enum vt_plugin_callback_return {
42  VT_PLUGIN_CNTR_CALLBACK_OK = 0,
43  VT_PLUGIN_CNTR_CALLBACK_BUFFER_FULL = 1,
44  VT_PLUGIN_CNTR_CALLBACK_TRACE_OFF_PERMANENT = 2
45 };
46 
47 /* Use these definitions to define the counter properties */
48 
49 /* The counter has an increasing value */
50 #define VT_PLUGIN_CNTR_ACC 1<<0
51 /* The counter has an absolute value */
52 #define VT_PLUGIN_CNTR_ABS 1<<1
53 /* The counter values belong to the time interval since
54  * the beginning of the measurement*/
55 #define VT_PLUGIN_CNTR_START 1<<2
56 /* value is only valid at a point in time but
57 not necessarily for any interval of time */
58 #define VT_PLUGIN_CNTR_POINT 1<<3
59 /* The counter values are related to the time interval since the last counter
60  * sample of the same counter, i.e. the immediate past */
61 #define VT_PLUGIN_CNTR_LAST 1<<4
62 /* The counter values are valid from now until the next counter sample,
63  * i.e. the future right ahead. */
64 #define VT_PLUGIN_CNTR_NEXT 1<<5
65 
66 /* For integer values (which have to have a length of 64 bit) */
67 #define VT_PLUGIN_CNTR_SIGNED 1<<6
68 #define VT_PLUGIN_CNTR_UNSIGNED 1<<7
69 /* For floating point values */
70 #define VT_PLUGIN_CNTR_FLOAT 1<<8
71 #define VT_PLUGIN_CNTR_DOUBLE 1<<9
72 
73 #define VT_PLUGIN_CNTR_VERSION 2;
74 
75 /* used for add_counter */
77  /* generated id by plugin */
78  char * name;
79  /* name of the function */
80  char * unit;
81  /* name of the function */
82  uint32_t cntr_property;
84 
85 /* used for get_results */
87  /* in vampir trace time! */
88  uint64_t timestamp;
89  /* current value */
90  uint64_t value;
92 
94  /* for all */
95 
96  /* should be set to VT_PLUGIN_VERSION (needed for back- and forward
97  * compatiblity)
98  */
99  uint32_t vt_plugin_cntr_version;
100 
101  /* this is called once per process
102  * should return 0 if successful
103  */
104  int32_t(*init)(void);
105 
106  /* this is called once per process */
107  vt_plugin_cntr_metric_info * (*get_event_info)(char *);
108 
109  /* add counter, returns ID
110  * is called PER THREAD
111  */
112  int32_t (*add_counter)(char * event_name);
113 
114  /* enable counter with ID
115  * is called PER THREAD
116  * can be set to NULL
117  */
118  int32_t (*enable_counter)(int32_t ID);
119 
120  /* disable counter with ID
121  * is called PER THREAD
122  * can be set to NULL
123  */
124  int32_t (*disable_counter)(int32_t ID);
125 
126  /* register a asynchronous plugin's own threads within the plugin!
127  * the threads may ask whether they are registered.
128  * (use pthread_self to get the tid)
129  */
130  int32_t (*is_thread_registered)(void);
131 
132  /* runs per host / per thread / ... */
133  int32_t run_per;
134  /* runs synchronous/asynch. */
135  int32_t synch;
136 
137  /* for synchronous plugins */
138  uint64_t (*get_current_value)(int32_t ID);
139 
140  /* for asynchronous plugins */
141  void (*set_pform_wtime_function)(uint64_t(*pform_wtime)(void));
142 
143  /* asynch post_mortem/event
144  * Input 1: ID
145  * Input 2: used as output: pointer to list with return values
146  * return : length of list with return values
147  */
148  uint64_t (*get_all_values)(int32_t, vt_plugin_cntr_timevalue **);
149 
150  /* asynch_callback */
151  /* Input 1: an ID, which should be used as first argument when calling the
152  * callback function
153  * Input 2: is a counter id the plugin provided previously
154  * Input 3: is the function to be called by the plugin
155  * whenever there is new data, the plugin should call
156  * callback_function(Input1,currentValue)
157  * return 0 if successful
158  */
159  int32_t (*set_callback_function)(void *, int32_t,
160  int32_t(*callback_function)(void *, vt_plugin_cntr_timevalue));
161 
162  /* called once per process */
163  void (*finalize)(void);
164 
165  /* some space for future stuff, should be zeroed */
166  uint64_t reserved[100];
167 
169 
170 
171 /**
172  * should be implemented by a plugin
173  */
174 vt_plugin_cntr_info get_info(void);
175 
176 #endif /* _VT_PLUGIN_CNTR_H */
Definition: vt_plugin_cntr.h:86
Definition: vt_plugin_cntr.h:93
Definition: vt_plugin_cntr.h:76