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