reorginization of visiLib
[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 #include "visiTypes.h"
24
25 //
26 // callback associated with paradyn-visualization interface routines
27 //
28 extern int visi_callback();
29
30 /////////////////////////////////////////////////////////////
31 // these functions invoke upcalls to a visi interface client
32 // (call from visualization process to paradyn)
33 /////////////////////////////////////////////////////////////
34 //
35 // get a new set of metrics and resources from Paradyn
36 //
37 extern void visi_GetMetsRes(char *metres,  // predefined list met-res pairs 
38                        int numElements,  
39                        int type);      // 0-histogram, 1-scalar
40
41 //
42 // equivalent to a call to GetMetRes(0,0,0)
43 //
44 extern void visi_GetMetsRes();
45
46 //
47 // stop data collection for a metric/resource pair
48 // arguments are the datagrid indicies associated with the
49 // metric and resource to stop
50 //
51 extern void visi_StopMetRes(int metricIndex,    // datagrid index of metric
52                        int resourceIndex); // datagrid index of resource
53
54 //
55 // define a new phase to paradyn, can specify some time in the future
56 // for the phase to begin or a begin value of -1 means now
57 //
58 extern void visi_DefinePhase(visi_timeType begin,  // in seconds 
59                         char *name);     // name of phase 
60
61 ////////////////////////////////////////////////////////////////
62 //   initialization routines 
63 ////////////////////////////////////////////////////////////////
64 //
65 // connects to parent socket and registers the mainLoop routine
66 // as a callback on events on fileDesc[0]
67 // This routine should be called before entering the visualization's
68 // main loop, and before calling any other visi-interface routines
69 //
70 extern int  visi_Init();
71
72
73 //
74 //  Makes initial call to get Metrics and Resources.
75 //  For visualizations that do not provide an event that
76 //  invokes the GetMetsRes upcall this routine should be
77 //  called by the visualization before entrering the mainloop.
78 //  (this will be the only chance to get metrics and resources
79 //  for the visualization).
80 //  For other visualizaitons, calling this routine before
81 //  entering the mainloop is optional. 
82 //
83 extern int  visi_StartVisi(int argc,char *argv[]);
84
85 //
86 // cleans up visi interface data structs
87 // Visualizations should call this routine before exiting 
88 extern void visi_QuitVisi();
89
90
91 //
92 // registration callback routine for paradyn events
93 // sets eventCallbacks[event] to callback routine provided by user
94 //
95 extern int visi_RegistrationCallback(visi_msgTag event,int (*callBack)(int));
96
97 //
98 // request to Paradyn to display error message
99 //
100 extern void visi_showErrorVisiCallback(const char *msg);
101
102 // **********************************************
103 //
104 //  Data Grid Routines
105 //
106 // **********************************************
107 //
108 // returns the ith metric name or 0 on error   
109 //
110 extern const char *visi_MetricName(int metric_num);
111
112 //
113 // returns the ith metric units name or 0 on error   
114 //
115 extern const char *visi_MetricUnits(int metric_num);
116
117 //
118 // returns the ith metric units label for data values or 0 on error   
119 //
120 extern const char *visi_MetricLabel(int metric_num);
121
122 //
123 // returns the ith metric units label for average aggregate data values,
124 // or 0 on error   
125 //
126 extern const char *visi_MetricAveLabel(int metric_num);
127
128 //
129 // returns the ith metric units label for sum aggregate data values,
130 // or 0 on error   
131 //
132 extern const char *visi_MetricSumLabel(int metric_num);
133
134 //
135 // returns the ith resource's name,  or 0 on error   
136 //
137 extern const char *visi_ResourceName(int resource_num);
138
139 //
140 //  returns the number of metrics in the data grid
141 //
142 extern int visi_NumMetrics();
143
144 //
145 //  returns the number of resources in the data grid
146 //
147 extern int visi_NumResources();
148
149 //
150 //  returns the number of phases currently defined in the system   
151 //
152 extern u_int visi_NumPhases();
153
154 //
155 // returns the start time of the phase for which this visi is defined
156 //
157 extern visi_timeType visi_GetStartTime();
158
159 //
160 // returns the name of the phase for which this visi is defined
161 //
162 extern const char *visi_GetMyPhaseName();
163
164 //
165 // returns the handle of the phase for which this visi is defined or
166 // -1 on error
167 //
168 extern int visi_GetPhaseHandle();
169
170 //
171 // returns the handle of the ith phase or -1 on error
172 //
173 extern int visi_GetPhaseHandle();
174
175 //
176 // returns phase name for the ith phase, or returns 0 on error
177 //
178 extern const char *visi_GetPhaseName(u_int phase_num);
179
180 //
181 // returns phase start time for the ith phase, or returns -1.0 on error
182 //
183 extern visi_timeType visi_GetPhaseStartTime(u_int phase_num);
184
185 //
186 // returns phase end time for the ith phase, or returns -1.0 on error
187 //
188 extern visi_timeType visi_GetPhaseEndTime(u_int phase_num);
189
190 //
191 // returns phase bucket width for the ith phase, or returns -1.0 on error
192 //
193 extern visi_timeType visi_GetPhaseBucketWidth(u_int phase_num);
194
195 //
196 // returns the average of all the data bucket values for the metric/resource
197 // pair "metric_num" and "resource_num", returns NaN value on error 
198 //
199 extern visi_sampleType visi_AverageValue(int metric_num, int resource_num);
200
201 //
202 // returns the sum of all the data bucket values for the metric/resource
203 // pair "metric_num" and "resource_num", returns NaN value on error 
204 //
205 extern visi_sampleType visi_SumValue(int metric_num, int resource_num);
206
207 //
208 // returns the data value in bucket "bucket_num" for the metric/resource pair 
209 // "metric_num" and "resource_num", returns NaN value on error 
210 //
211 extern visi_sampleType visi_DataValue(int metric_num, int resource_num, 
212                                  int bucket_num);
213
214 //
215 // returns the data values for the metric/resource pair "metric_num" 
216 // and "resource_num", returns NaN value on error 
217 //
218 extern visi_sampleType *visi_DataValues(int metric_num, int resource_num);
219
220 //
221 //  returns true if the data grid cell corresponding to metric_num   
222 //  and resource_num contains data 
223 //
224 extern bool visi_Valid(int metric_num, int resource_num);
225
226 //
227 //  returns true if the data collection has been enabled for metric_num   
228 //  and resource_num  
229 //
230 extern bool visi_Enabled(int metric_num, int resource_num);
231
232
233 //
234 //  returns the number of buckets in each data grid cell's histogram  
235 //
236 extern int visi_NumBuckets();
237
238 //
239 //  returns the buckets width (in seconds) of each data grid cell's histogram  
240 //
241 extern visi_timeType visi_BucketWidth();
242
243 //
244 // returns the first data bucket with valid data values 
245 //
246 extern int visi_FirstValidBucket(int metric_num, int resource_num);
247
248 //
249 // returns the last data bucket with valid data values 
250 //
251 extern int visi_LastBucketFilled(int metric_num,int resource_num);
252
253 //
254 // returns true if there are invalid spans of data between the first
255 // valid bucket and the last bucket filled
256 //
257 extern bool visi_InvalidSpans(int metric_num,int resource_num);
258
259 //
260 // returns the user data associated with metric_num and resource_num
261 // returns 0 on error
262 //
263 extern void *visi_GetUserData(int metric_num, int resource_num);
264
265 //
266 // sets the user data associated with metric_num and resource_num
267 //
268 extern bool visi_SetUserData(int metric_num, int resource_num, void *data);
269
270 #endif