Upgrades for performanceConsultant thread.
[dyninst.git] / paradyn / h / dataManager.I
1 /* 
2  *  Copyright 1993 Jeff Hollingsworth.  All rights reserved.
3  *
4  */
5
6 /*
7  * mmthread.h - exported services of the mmthread of paradyn.
8  *
9  * $Log: dataManager.I,v $
10  * Revision 1.2  1994/02/01 18:47:33  hollings
11  * Upgrades for performanceConsultant thread.
12  *
13 # Revision 1.1  1994/01/27  00:41:37  hollings
14 # First version of data manager interfaces.
15 #
16  *
17  */
18
19 #ifndef MMTHREAD_H
20 #define MMTHREAD_H
21
22 #include "util/h/list.h"
23 #include "rtinst/h/trace.h"
24 #include "util/h/hist.h"
25 #include "dyninstRPC.h"
26
27 /* one or more program working together */
28 class applicationContext;       
29
30 /* sequence of peformance data (trace|sample) */
31 class performanceStream;        
32
33 /* time */
34 // typedef double timeStamp;            
35
36 /* something that data can be collected for */
37 class resource;         
38
39 /* descriptive information about a resource */
40 typedef struct {
41     char *name;                 /* name of actual resource */
42     char *fullName;             /* full path name of resource */
43     timeStamp creation;         /* when did it get created */
44 } resourceInfo;         
45
46 /* list of resources */
47 class resourceList;             
48
49 /* a metric */
50 class metric;                   
51
52 /* a list of metrics */
53 typedef metric *metricList;             
54
55 /* a metric/resourceList pair */
56 class metricInstance;           
57
58 typedef enum { Trace, Sample } dataType;
59
60 /*
61  * error handler call back.
62  *
63  */
64 typedef (*errorHandler)(int errno, char *message);
65
66 /*
67  * Handler that gets called when new sample data is delivered.
68  *
69  *   ps - a performanceStream from createPerformanceStream
70  *   mi - a metricInstance returned by enableDataCollection
71  *   startTimeStamp - starting time of the interval covered by this sample.
72  *   endTimeStamp - ending time of the interval covered by this sample.
73  *   value - the value of this sample
74  *    
75  */
76 typedef (*sampleDataCallbackFunc)(performanceStream *ps, 
77                                   metricInstance *mi,
78                                   timeStamp startTimeStamp, 
79                                   timeStamp endTimeStamp, 
80                                   sampleValue value);
81
82 /*
83  * Handler that gets called when new trace data is available.
84  *   
85  *   ps - a performanceStream from createPerformanceStream
86  *   mi - a metricInstance returned by enableDataCollection
87  *   time - time of the event.
88  *   eventSize - size of the event specific data.
89  *   eventData - event specific data.
90  */
91 typedef (*traceDataCallbackFunc)(performanceStream *ps, metricInstance *mi,
92     timeStamp time, int eventSize, void *eventData);
93
94 /*
95  * union to hold two types of data callback.
96  *
97  */
98 union dataCallback {
99     sampleDataCallbackFunc      sample;
100     traceDataCallbackFunc       trace;
101 };
102
103 typedef union dataCallback dataCallback;
104
105 /*
106  * Handler that gets called when a new metric is defined.
107  *
108  * performanceStream    - a stream returned by createPerformanceStream
109  * metric               - a metric
110  *
111  */
112 typedef void (*metricInfoCallback)(performanceStream*, metric*);
113
114 /*
115  * Handler that gets called when a new resource is defined.
116  *
117  * performanceStream    - a stream returned by createPerformanceStream
118  * parent               - parent of new resource
119  * newResource          - new resource being created
120  * name                 - name of the new resource
121  *
122  */
123 typedef void (*resourceInfoCallback)(performanceStream*, resource *parent, 
124     resource *newResource, char *name);
125
126 struct controlCallback {
127     metricInfoCallback mFunc;
128     resourceInfoCallback rFunc;
129 };
130
131 typedef struct controlCallback controlCallback;
132
133
134 $remote dataManager {
135     $base 2000;
136     $version 1;
137
138     //
139     // Create an applicationContext (an application to be studied)
140     //
141     applicationContext *createApplicationContext(errorHandler foo);
142
143     //
144     // Define a program to run. 
145     //
146     Boolean addExecutable(applicationContext *app,
147                           char  *machine, 
148                           char *login, 
149                           char *name, 
150                           int argc,
151                           char **argv);
152
153     //
154     // Find out if an application has been defined yet.
155     //
156     Boolean applicationDefined(applicationContext *app);
157
158     //
159     // Start an application running (This starts the actual execution).
160     //   app - an application context from createPerformanceConext.
161     // 
162     Boolean startApplication(applicationContext *app);
163
164     //
165     //   Stop all processes associted with the application.
166     //      app - an application context from createPerformanceConext.
167     //
168     // Pause an application (I am not sure about this but I think we want it).
169     //      - Does this force buffered data to be delivered?
170     //  - Does a paused application respond to enable/disable commands?
171     //
172     Boolean pauseApplication(applicationContext *app);
173
174     //
175     // Continue a paused application.
176     //    app - an application context from createPerformanceConext.
177     //
178     Boolean continueApplication(applicationContext *app);
179
180     //
181     // Disconnect the tool from the process.
182     //    app - an application context from createPerformanceConext.
183     //    pause - leave the process in a stopped state.
184     //
185     Boolean detachApplication(applicationContext *app,Boolean pause);
186
187     // 
188     // Create a performanceStream.  This a flow of performance information
189     //   to a destination. 
190     //
191     // applicationContext       - an application context.
192     // dataType                 - Sample or Trace
193     // dataCallback     - Function to call when new data arrives
194     // controlCallback  - Function to call when new structure info arrives
195     // sampleInterval   - nominal interval between samples (sample only)
196     //
197     performanceStream *createPerformanceStream(applicationContext*, 
198                                                dataType, 
199                                                dataCallback, 
200                                                controlCallback);
201         
202
203     void setSampleRate(performanceStream *stream, timeStamp sampleInterval);
204
205     //
206     // Routines to control data collection on a performanceStream.
207     //
208     // performanceStream        - a stream returned by createPerformanceStream
209     // resourceList             - a list of resources
210     // metric           - what metric to collect data for
211     //
212     metricInstance *enableDataCollection(performanceStream*,
213                                          resourceList*,
214                                          metric*);
215
216     //
217     // stop collecting data for the named metricInstance.
218     // performanceStream        - a stream returned by createPerformanceStream
219     // metricInstance   - a metricInstance returned by enableDataCollection.
220     //
221     void disableDataCollection(performanceStream*, metricInstance*);
222
223     //
224     // Return the expected cost of collecting performance data for a single
225     //    metric at a given focus.  The value returned is the fraction of
226     //    perturbation expected (i.e. 0.10 == 10% slow down expected).
227     //
228     float getPredictedDataCost(applicationContext*, resourceList*, metric*);
229
230     //
231     // Control information arriving about a resource Classes
232     //
233     // performanceStream        - a stream returned by createPerformanceStream
234     // resource         - enable notification of children of this resource
235     //
236     void enableResourceCreationNotification(performanceStream*, resource*);
237
238     //
239     // Turn off notification of creation of descendants of this resource.
240     // 
241     // performanceStream        - a stream returned by createPerformanceStream
242     // resource         - disable notification of descendants of this resource
243     //
244     //
245     void disableResourceCreationNotification(performanceStream*, resource*);
246
247     //
248     // Resource utility functions.
249     //
250     resource *getRootResource();
251
252     resourceList *getRootResources();
253
254     char *getResourceName(resource*);
255
256     resource *getResourceParent(resource*);
257
258     resource *newResource(applicationContext *app,
259                           resource *parent, 
260                           char *name);
261
262     resourceList *getResourceChildren(resource*);
263
264     Boolean isResourceDescendent(resource *parent, resource *child);
265
266     resource *findChildResource(resource *parent, char *name);
267
268     int getResourceCount(resourceList*);
269
270     resource *getNthResource(resourceList*, int n);
271
272     resourceList *createResourceList();
273
274     void addResourceList(resourceList*, resource*);
275
276     // Get the static config. information for the passed applicationContext.
277     //
278     $array String getAvailableMetrics(applicationContext*);
279
280     //
281     // looks for a specifc metric instance in an application context.
282     //
283     metric *findMetric(applicationContext *context, char *name);
284
285     //
286     // Metric utility functions.
287     //
288     char *getMetricName(metric*);
289
290     //
291     // get the supporting info about a metric.
292     metricInfo *getMetricInfo(metric*);
293
294     //
295     // Get metric out of a metric instance.
296     //
297     metric *getMetric(metricInstance*);
298     char *getMetricNameFromMI(metricInstance*);
299
300     //
301     // Get the value of a metric.
302     //
303     sampleValue getMetricValue(metricInstance*);
304
305     //
306     // Debugger style calls.
307     //
308     void printResources();
309     void printStatus(applicationContext*);
310     void coreProcess(applicationContext*, int pid);
311
312     //
313     // upcalls for indications of events.
314     //
315     $upcall $async void newMetricDefined(metricInfoCallback, 
316                                          performanceStream*, 
317                                          metric*);
318
319     $upcall $async void newPerfData(sampleDataCallbackFunc, 
320                                     performanceStream *ps,
321                                     metricInstance *mi,
322                                     timeStamp startTimeStamp, 
323                                     timeStamp endTimeStamp, 
324                                     sampleValue value);
325 };
326
327 #endif