Platform migration
[dyninst.git] / visi / h / visualization.h
1 /*
2  * Copyright (c) 1996 Barton P. Miller
3  * 
4  * We provide the Paradyn Parallel Performance Tools (below
5  * described as Paradyn") on an AS IS basis, and do not warrant its
6  * validity or performance.  We reserve the right to update, modify,
7  * or discontinue this software at any time.  We shall have no
8  * obligation to supply such updates or modifications or any other
9  * form of support to you.
10  * 
11  * This license is for research uses.  For such uses, there is no
12  * charge. We define "research use" to mean you may freely use it
13  * inside your organization for whatever purposes you see fit. But you
14  * may not re-distribute Paradyn or parts of Paradyn, in any form
15  * source or binary (including derivatives), electronic or otherwise,
16  * to any other organization or entity without our permission.
17  * 
18  * (for other uses, please contact us at paradyn@cs.wisc.edu)
19  * 
20  * All warranties, including without limitation, any warranty of
21  * merchantability or fitness for a particular purpose, are hereby
22  * excluded.
23  * 
24  * By your use of Paradyn, you understand and agree that we (or any
25  * other person or entity with proprietary rights in Paradyn) are
26  * under no obligation to provide either maintenance services,
27  * update services, notices of latent defects, or correction of
28  * defects for Paradyn.
29  * 
30  * Even if advised of the possibility of such damages, under no
31  * circumstances shall we (or any other person or entity with
32  * proprietary rights in the software licensed hereunder) be liable
33  * to you or any third party for direct, indirect, or consequential
34  * damages of any character regardless of type of action, including,
35  * without limitation, loss of profits, loss of use, loss of good
36  * will, or computer failure or malfunction.  You agree to indemnify
37  * us (and any other person or entity with proprietary rights in the
38  * software licensed hereunder) for any and all liability it may
39  * incur to third parties resulting from your use of Paradyn.
40  */
41
42 #ifndef _visualization_h
43 #define _visualization_h
44
45 /**********************************************************************
46  *  This file should be included in all visualizations. It 
47  *  contains definitions for all the Paradyn visi interface routines.  
48  * 
49  *  This file should not contain any C++ code (nor C++-style comments!). 
50  *  It is intended to be used by either C or C++ visis, and therefore 
51  *  it should be able to be compiled by a C compiler.
52  **********************************************************************/
53
54 #if defined(__cplusplus)
55 extern "C" {
56 #endif
57
58 #include "visiTypes.h"
59 /***********************************************************************
60  * these functions invoke upcalls to a visi interface client
61  * (call from visualization process to paradyn)
62  ***********************************************************************/
63
64 /* get a new set of metrics and resources from Paradyn
65  * currently, passing a list of met-res pairs is not supported 
66  * (i.e. these parameters are ignored)
67  */
68 extern void visi_GetMetsRes(char *metres,  /* predefined met-res pair list */
69                             int numElements); 
70
71 /* stop data collection for a metric/resource pair
72  * arguments are the datagrid indicies associated with the
73  * metric and resource to stop
74  */
75 extern void visi_StopMetRes(int metricIndex, int resourceIndex); 
76
77 /* define a new phase to paradyn, can specify a name for the phase:
78  * passing 0 for name argument will cause visiLib to create a 
79  * unique name for the phase,
80  * passing 1 for withPerfConsult or withVisis will cause a new
81  * new PerfConsult search or visi to be started with the new phase, 
82  * passing 0 will just start a new phase.
83  */
84 extern void visi_DefinePhase(char *phase_name,
85                              unsigned withPerfConsult,
86                              unsigned withVisis);
87
88 /* request to Paradyn to display error message
89  */
90 extern void visi_showErrorVisiCallback(const char *msg);
91
92 /************************************************************************
93  *   initialization routines 
94  ************************************************************************/
95
96 /* Visi Initialization routine, returns a file descriptor that  
97  * is used to communicate with Paradyn.  This file descriptor 
98  * should be added by the visi as a source of input with the
99  * visiLib routine "visi_callback" as the callback routine 
100  * associated with this file descriptor.
101  * This routine should be called before entering the visualization's
102  * main loop, and before calling any other visi-interface routines.
103  */
104 extern PDSOCKET visi_Init();
105
106 /* callback associated with paradyn-visualization interface routines
107  */
108 extern int visi_callback();
109
110 /* registration callback routine for Paradyn events
111  * sets eventCallbacks[event] to callback routine provided by user
112  * returns -1 on error, otherwise returns 0 
113  */
114 extern int visi_RegistrationCallback(visi_msgTag event, int (*callBack)(int));
115
116 /* clean up visi interface data structs:
117  * Visualizations should call this routine before exiting 
118  */
119 extern void visi_QuitVisi();
120
121 /*******************************************************************
122  *  Data Grid Routines
123  *******************************************************************/
124
125 /* returns the ith metric name or 0 on error   
126  */
127 extern const char *visi_MetricName(int metric_num);
128
129 /* returns the ith metric units name or 0 on error   
130  */
131 extern const char *visi_MetricUnits(int metric_num);
132
133 /* returns the ith metric units label for data values or 0 on error   
134  */
135 extern const char *visi_MetricLabel(int metric_num);
136
137 /* returns the ith metric units label for average aggregate data values,
138  * or 0 on error   
139  */
140 extern const char *visi_MetricAveLabel(int metric_num);
141
142 /* returns the ith metric units label for sum aggregate data values,
143  * or 0 on error   
144  */
145 extern const char *visi_MetricSumLabel(int metric_num);
146
147 /* returns the ith resource's name,  or 0 on error   
148  */
149 extern const char *visi_ResourceName(int resource_num);
150
151 /* returns the number of metrics in the data grid
152  */
153 extern int visi_NumMetrics();
154
155 /* returns the number of resources in the data grid
156  */
157 extern int visi_NumResources();
158
159 /* returns the number of phases currently defined in the system   
160  */
161 extern unsigned visi_NumPhases();
162
163 /* returns the start time of the phase for which this visi is defined
164  */
165 extern visi_timeType visi_GetStartTime();
166
167 /* returns the name of the phase for which this visi is defined
168  */
169 extern const char *visi_GetMyPhaseName();
170
171 /* returns the handle of the phase for which this visi is defined or
172  * -1 on error
173  */
174 extern int visi_GetMyPhaseHandle();
175
176 /* returns the handle of the ith phase or -1 on error
177  */
178 extern int visi_GetPhaseHandle(unsigned phase_num);
179
180 /* returns phase name for the ith phase, or returns 0 on error
181  */
182 extern const char *visi_GetPhaseName(unsigned phase_num);
183
184 /* returns phase start time for the ith phase, or returns -1.0 on error
185  */
186 extern visi_timeType visi_GetPhaseStartTime(unsigned phase_num);
187
188 /* returns phase end time for the ith phase, or returns -1.0 on error
189  */
190 extern visi_timeType visi_GetPhaseEndTime(unsigned phase_num);
191
192 /* returns phase bucket width for the ith phase, or returns -1.0 on error
193  */
194 extern visi_timeType visi_GetPhaseBucketWidth(unsigned phase_num);
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 /* returns the sum of all the data bucket values for the metric/resource
202  * pair "metric_num" and "resource_num", returns NaN value on error 
203  */
204 extern visi_sampleType visi_SumValue(int metric_num, int resource_num);
205
206 /* returns the data value in bucket "bucket_num" for the metric/resource pair 
207  * "metric_num" and "resource_num", returns NaN value on error 
208  */
209 extern visi_sampleType visi_DataValue(int metric_num, int resource_num, 
210                                       int bucket_num);
211
212 /* returns the data values for the metric/resource pair "metric_num" 
213  * and "resource_num", returns NaN value on error 
214  */
215 extern const visi_sampleType *visi_DataValues(int metric_num, int resource_num);
216
217 /* returns 1 if the data grid cell corresponding to metric_num   
218  * and resource_num contains data, otherwise returns 0 
219  */
220 extern int visi_Valid(int metric_num, int resource_num);
221
222 /* returns 1 if the data collection has been enabled for metric_num   
223  * and resource_num, otherwise returns 0  
224  */
225 extern int visi_Enabled(int metric_num, int resource_num);
226
227 /* returns the number of buckets in each data grid cell's histogram  
228  */
229 extern int visi_NumBuckets();
230
231 /* returns the bucket width (in seconds) of each data grid cell's histogram  
232  */
233 extern visi_timeType visi_BucketWidth();
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 /* returns the last data bucket with valid data values 
240  */
241 extern int visi_LastBucketFilled(int metric_num,int resource_num);
242
243 /* returns 1 if there are invalid spans of data between the first
244  * valid bucket and the last bucket filled, otherwise returns 0
245  */
246 extern int visi_InvalidSpans(int metric_num,int resource_num);
247
248 /* returns the user data associated with metric_num and resource_num
249  * returns 0 on error
250  */
251 extern void *visi_GetUserData(int metric_num, int resource_num);
252
253 /* sets the user data associated with metric_num and resource_num
254  * returns 1 on success, or returns 0 on error
255  */
256 extern int visi_SetUserData(int metric_num, int resource_num, void *data);
257
258 /* print every stepth bucket to stderr
259  */
260 extern void visi_PrintDataBuckets(int step);
261
262 #if defined(__cplusplus)
263 };
264 #endif /* defined(__cplusplus) */
265
266 #endif