paradyn/h/dataManager.I

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