added way to request unique resource name.
[dyninst.git] / dyninstAPI / src / dyninst.h
1 /*
2  *  Copyright 1993 Jeff Hollingsworth.  All rights reserved.
3  *
4  */
5
6 /*
7  * dyninst.h - exported interface to instrumentation.
8  *
9  * $Log: dyninst.h,v $
10  * Revision 1.7  1994/05/16 22:31:49  hollings
11  * added way to request unique resource name.
12  *
13  * Revision 1.6  1994/04/09  18:34:52  hollings
14  * Changed {pause,continue}Application to {pause,continue}AllProceses, and
15  * made the RPC interfaces use these.  This makes the computation of pause
16  * Time correct.
17  *
18  * Revision 1.5  1994/03/31  01:48:32  markc
19  * Added default args to addProcess definition.
20  *
21  * Revision 1.4  1994/03/24  16:41:58  hollings
22  * Moved sample aggregation to lib/util (so paradyn could use it).
23  *
24  * Revision 1.3  1994/03/20  01:53:04  markc
25  * Added a buffer to each process structure to allow for multiple writers on the
26  * traceStream.  Replaced old inst-pvm.C.  Changed addProcess to return type
27  * int.
28  *
29  * Revision 1.2  1994/02/01  18:46:50  hollings
30  * Changes for adding perfConsult thread.
31  *
32  * Revision 1.1  1994/01/27  20:31:17  hollings
33  * Iinital version of paradynd speaking dynRPC igend protocol.
34  *
35  * Revision 1.5  1994/01/26  06:57:07  hollings
36  * new header location
37  *
38  * Revision 1.4  1993/12/13  20:02:23  hollings
39  * added applicationDefined
40  *
41  * Revision 1.3  1993/08/26  18:22:24  hollings
42  * added cost model
43  *
44  * Revision 1.2  1993/07/01  17:03:17  hollings
45  * added debugger calls and process control calls
46  *
47  * Revision 1.1  1993/03/19  22:51:05  hollings
48  * Initial revision
49  *
50  *
51  */
52
53 #ifndef INSTRUMENTATION_H
54 #define INSTRUMENTATION_H
55
56 #include "rtinst/h/trace.h"
57
58 /* time */
59 typedef double timeStamp;               
60
61 /* something that data can be collected for */
62 typedef struct _resourceRec *resource;          
63
64 /* descriptive information about a resource */
65 typedef struct {
66     char *name;                 /* name of actual resource */
67     char *fullName;             /* full path name of resource */
68     timeStamp creation;         /* when did it get created */
69 } resourceInfo;         
70
71 /* list of resources */
72 typedef struct _resourceListRec *resourceList;          
73
74 /* a metric */
75 typedef struct _metricRec *metric;                      
76
77 /* a list of metrics */
78 typedef struct _metricListRec *metricList;              
79
80 /* a metric/resourceList pair */
81 typedef class metricDefinitionNode *metricInstance;             
82
83 typedef enum { Trace, Sample } dataType;
84
85 /*
86  * error handler call back.
87  *
88  */
89 typedef (*errorHandler)(int errno, char *message);
90
91 /*
92  * Define a program to run (this is very tentative!)
93  *
94  *   argv - arguments to command
95  *   envp - environment args, for pvm
96  */
97 int addProcess(int argc, char*argv[], int nenv=0, char *envp[]=0);
98
99 /*
100  * Find out if an application has been defined yet.
101  *
102  */
103 Boolean applicationDefined();
104
105 /*
106  * Start an application running (This starts the actual execution).
107  *  app - an application context from createPerformanceConext.
108  */
109 Boolean startApplication();
110
111 /*
112  *   Stop all processes associted with the application.
113  *      app - an application context from createPerformanceConext.
114  *
115  * Pause an application (I am not sure about this but I think we want it).
116  *      - Does this force buffered data to be delivered?
117  *      - Does a paused application respond to enable/disable commands?
118  */
119 Boolean pauseAllProcesses();
120
121 /*
122  * Continue a paused application.
123  *    app - an application context from createPerformanceConext.
124  */
125 Boolean continueAllProcesses();
126
127
128 /*
129  * Disconnect the tool from the process.
130  *    pause - leave the process in a stopped state.
131  *
132  */
133 Boolean detachProcess(int pid, Boolean pause);
134
135 /*
136  * Routines to control data collection.
137  *
138  * resourceList         - a list of resources
139  * metric               - what metric to collect data for
140  *
141  */
142 int startCollecting(resourceList, metric);
143
144
145 /*
146  * Return the expected cost of collecting performance data for a single
147  *    metric at a given focus.  The value returned is the fraction of
148  *    perturbation expected (i.e. 0.10 == 10% slow down expected).
149  */
150 float guessCost(resourceList, metric);
151
152 /*
153  * Control information arriving about a resource Classes
154  *
155  * resource             - enable notification of children of this resource
156  */
157 Boolean enableResourceCreationNotification(resource);
158
159 /*
160  * Resource utility functions.
161  *
162  */
163 resourceList getRootResources();
164
165 extern resource rootResource;
166
167 char *getResourceName(resource);
168
169 resource getResourceParent(resource);
170
171 resourceList getResourceChildren(resource);
172
173 Boolean isResourceDescendent(resource parent, resource child);
174
175 resource findChildResource(resource parent, char *name);
176
177 int getResourceCount(resourceList);
178
179 resource getNthResource(resourceList, int n);
180
181 resourceInfo *getResourceInfo(resource);
182
183 resourceList createResourceList();
184
185 Boolean addResourceList(resourceList, resource);
186
187 resource newResource(resource parent,
188                      void *handle,
189                      char *name,
190                      timeStamp creation,
191                      Boolean unique);
192
193 /*
194  * manipulate user handle (a single void * to permit mapping between low level
195  *   resource's and the resource consumer.
196  *
197  */
198 void *getResourceHandle(resource);
199
200 void setResourceHandle(resource, void*);
201
202 resourceList findFocus(int count, char **foucsString);
203
204 /*
205  * Get the static configuration information.
206  *
207  */
208 metricList getMetricList();
209
210 /*
211  * looks for a specifc metric instance in an application context.
212  *
213  */
214 metric findMetric(char *name);
215
216 /*
217  * Metric utility functions.
218  *
219  */
220 char *getMetricName(metric);
221
222 /*
223  * Get metric out of a metric instance.
224  *
225  */
226 metric getMetric(metricInstance);
227
228 #endif