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