added 2 bool params to visi_DefinePhase
[dyninst.git] / visi / h / visualization.h
1 #ifndef _visualization_h
2 #define _visualization_h
3 /*
4  * Copyright (c) 1993, 1994 Barton P. Miller, Jeff Hollingsworth,
5  *     Bruce Irvin, Jon Cargille, Krishna Kunchithapadam, Karen
6  *     Karavanic, Tia Newhall, Mark Callaghan.  All rights reserved.
7  * 
8  * This software is furnished under the condition that it may not be
9  * provided or otherwise made available to, or used by, any other
10  * person, except as provided for by the terms of applicable license
11  * agreements.  No title to or ownership of the software is hereby
12  * transferred.  The name of the principals may not be used in any
13  * advertising or publicity related to this software without specific,
14  * written prior authorization.  Any use of this software must include
15  * the above copyright notice.
16  *
17  */
18 /////////////////////////////////////////////////////////
19 //  This file should be included in all visualizations.
20 //  It contains definitions for all the Paradyn visi
21 //  interface routines.  
22 /////////////////////////////////////////////////////////
23
24 #if defined(__cplusplus)
25 extern "C" {
26 #endif
27
28 #include "visiTypes.h"
29 /////////////////////////////////////////////////////////////
30 // these functions invoke upcalls to a visi interface client
31 // (call from visualization process to paradyn)
32 /////////////////////////////////////////////////////////////
33 //
34 // get a new set of metrics and resources from Paradyn
35 // currently, passing a list of met-res pairs is not supported 
36 // (i.e. these parameters are ignored)
37 //
38 extern void visi_GetMetsRes(char *metres,  // predefined list met-res pairs
39                             int numElements); 
40
41 //
42 // stop data collection for a metric/resource pair
43 // arguments are the datagrid indicies associated with the
44 // metric and resource to stop
45 //
46 extern void visi_StopMetRes(int metricIndex,int resourceIndex); 
47
48 //
49 // define a new phase to paradyn, can specify a name for the phase
50 // passing 0 for name argument will cause visiLib to create a 
51 // unique name for the phase
52 //
53 extern void visi_DefinePhase(char *phase_name,
54                              bool withPerfConsult,
55                              bool withVisis);
56
57 //
58 // request to Paradyn to display error message
59 //
60 extern void visi_showErrorVisiCallback(const char *msg);
61
62 ////////////////////////////////////////////////////////////////
63 //   initialization routines 
64 ////////////////////////////////////////////////////////////////
65 //
66 // Visi Initialization routine, returns a file descriptor that  
67 // is used to communicate with Paradyn.  This file descriptor 
68 // should be added by the visi as a source of input with the
69 // visiLib routine "visi_callback" as the callback routine 
70 // associated with this file descriptor.
71 // This routine should be called before entering the visualization's
72 // main loop, and before calling any other visi-interface routines
73 //
74 extern int  visi_Init();
75
76 //
77 // callback associated with paradyn-visualization interface routines
78 //
79 extern int visi_callback();
80
81 //
82 // registration callback routine for paradyn events
83 // sets eventCallbacks[event] to callback routine provided by user
84 // returns -1 on error, otherwise returns 0 
85 //
86 extern int visi_RegistrationCallback(visi_msgTag event,int (*callBack)(int));
87
88 //
89 // cleans up visi interface data structs
90 // Visualizations should call this routine before exiting 
91 extern void visi_QuitVisi();
92
93 // **********************************************
94 //
95 //  Data Grid Routines
96 //
97 // **********************************************
98 //
99 // returns the ith metric name or 0 on error   
100 //
101 extern const char *visi_MetricName(int metric_num);
102
103 //
104 // returns the ith metric units name or 0 on error   
105 //
106 extern const char *visi_MetricUnits(int metric_num);
107
108 //
109 // returns the ith metric units label for data values or 0 on error   
110 //
111 extern const char *visi_MetricLabel(int metric_num);
112
113 //
114 // returns the ith metric units label for average aggregate data values,
115 // or 0 on error   
116 //
117 extern const char *visi_MetricAveLabel(int metric_num);
118
119 //
120 // returns the ith metric units label for sum aggregate data values,
121 // or 0 on error   
122 //
123 extern const char *visi_MetricSumLabel(int metric_num);
124
125 //
126 // returns the ith resource's name,  or 0 on error   
127 //
128 extern const char *visi_ResourceName(int resource_num);
129
130 //
131 //  returns the number of metrics in the data grid
132 //
133 extern int visi_NumMetrics();
134
135 //
136 //  returns the number of resources in the data grid
137 //
138 extern int visi_NumResources();
139
140 //
141 //  returns the number of phases currently defined in the system   
142 //
143 extern u_int visi_NumPhases();
144
145 //
146 // returns the start time of the phase for which this visi is defined
147 //
148 extern visi_timeType visi_GetStartTime();
149
150 //
151 // returns the name of the phase for which this visi is defined
152 //
153 extern const char *visi_GetMyPhaseName();
154
155 //
156 // returns the handle of the phase for which this visi is defined or
157 // -1 on error
158 //
159 extern int visi_GetMyPhaseHandle();
160
161 //
162 // returns the handle of the ith phase or -1 on error
163 //
164 extern int visi_GetPhaseHandle(u_int phase_num);
165
166 //
167 // returns phase name for the ith phase, or returns 0 on error
168 //
169 extern const char *visi_GetPhaseName(u_int phase_num);
170
171 //
172 // returns phase start time for the ith phase, or returns -1.0 on error
173 //
174 extern visi_timeType visi_GetPhaseStartTime(u_int phase_num);
175
176 //
177 // returns phase end time for the ith phase, or returns -1.0 on error
178 //
179 extern visi_timeType visi_GetPhaseEndTime(u_int phase_num);
180
181 //
182 // returns phase bucket width for the ith phase, or returns -1.0 on error
183 //
184 extern visi_timeType visi_GetPhaseBucketWidth(u_int phase_num);
185
186 //
187 // returns the average of all the data bucket values for the metric/resource
188 // pair "metric_num" and "resource_num", returns NaN value on error 
189 //
190 extern visi_sampleType visi_AverageValue(int metric_num, int resource_num);
191
192 //
193 // returns the sum of all the data bucket values for the metric/resource
194 // pair "metric_num" and "resource_num", returns NaN value on error 
195 //
196 extern visi_sampleType visi_SumValue(int metric_num, int resource_num);
197
198 //
199 // returns the data value in bucket "bucket_num" for the metric/resource pair 
200 // "metric_num" and "resource_num", returns NaN value on error 
201 //
202 extern visi_sampleType visi_DataValue(int metric_num, int resource_num, 
203                                       int bucket_num);
204
205 //
206 // returns the data values for the metric/resource pair "metric_num" 
207 // and "resource_num", returns NaN value on error 
208 //
209 extern const visi_sampleType *visi_DataValues(int metric_num, int resource_num);
210
211 //
212 //  returns 1 if the data grid cell corresponding to metric_num   
213 //  and resource_num contains data, otherwise returns 0 
214 //
215 extern int visi_Valid(int metric_num, int resource_num);
216
217 //
218 //  returns 1 if the data collection has been enabled for metric_num   
219 //  and resource_num, otherwise returns 0  
220 //
221 extern int visi_Enabled(int metric_num, int resource_num);
222
223
224 //
225 //  returns the number of buckets in each data grid cell's histogram  
226 //
227 extern int visi_NumBuckets();
228
229 //
230 //  returns the buckets width (in seconds) of each data grid cell's histogram  
231 //
232 extern visi_timeType visi_BucketWidth();
233
234 //
235 // returns the first data bucket with valid data values 
236 //
237 extern int visi_FirstValidBucket(int metric_num, int resource_num);
238
239 //
240 // returns the last data bucket with valid data values 
241 //
242 extern int visi_LastBucketFilled(int metric_num,int resource_num);
243
244 //
245 // returns 1 if there are invalid spans of data between the first
246 // valid bucket and the last bucket filled, otherwise returns 0
247 //
248 extern int visi_InvalidSpans(int metric_num,int resource_num);
249
250 //
251 // returns the user data associated with metric_num and resource_num
252 // returns 0 on error
253 //
254 extern void *visi_GetUserData(int metric_num, int resource_num);
255
256 //
257 // sets the user data associated with metric_num and resource_num
258 // returns 1 on success, or returns 0 on error
259 //
260 extern int visi_SetUserData(int metric_num, int resource_num, void *data);
261
262 #if defined(__cplusplus)
263 };
264 #endif /* defined(__cplusplus) */
265
266 #endif