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