*** empty log message ***
[dyninst.git] / paradyn / h / dataManager.I
1 /*
2  * dataManager.h - exported services of the Data Mgr thread of paradyn.
3  * $Id: dataManager.I,v 1.92 1999/06/04 16:04:28 cain Exp $
4  */
5
6 #ifndef MMTHREAD_H
7 #define MMTHREAD_H
8
9 #include "util/h/list.h"
10 #include "util/h/sys.h"
11 #include "dyninstRPC.xdr.h"
12 #include "visi.xdr.h"
13 #include "util/h/aggregation.h"
14 #include "util/h/stringPool.h"
15 #include "paradyn/src/DMthread/DMinclude.h"
16 #include "paradyn/src/DMthread/DVbufferpool.h"
17
18 typedef enum {Global, Phase, All} SaveRequestType;
19
20 typedef enum { Trace, Sample } dataType;
21
22 /*
23  * error handler call back.
24  *
25  */
26 typedef void (*errorHandler)(int errno, char *message);
27
28 /*
29  * Handler that gets called when new sample data is delivered.
30  *
31  *   handle - a performance stream handle from createPerformanceStream
32  *   mi - a metricInstance returned by enableDataCollection
33  *   buckets - array of sampleValue filled by the DM 
34  *   first - the first bucket value
35  *   count - number of bucket values in buckets
36  *    
37  */
38 typedef void (*sampleDataCallbackFunc)(vector<dataValueType> *data,
39                                        u_int num_data_values);
40
41 /*
42  * Handler that gets called when new trace data is available.
43  *   
44  *   handle - a performance stream handle from createPerformanceStream
45  *   mi - a metricInstance returned by enableDataCollection
46  *   time - time of the event.
47  *   eventSize - size of the event specific data.
48  *   eventData - event specific data.
49  */
50 typedef void (*traceDataCallbackFunc)(perfStreamHandle handle, 
51                                       metricInstanceHandle mi, 
52                                       timeStamp time, 
53                                       int eventSize, 
54                                       void *eventData);
55
56 /*
57  * union to hold two types of data callback.
58  *
59  */
60 union dataCallback {
61     sampleDataCallbackFunc      sample;
62     traceDataCallbackFunc       trace;
63 };
64
65 typedef union dataCallback dataCallback;
66
67 /*
68  * Handler that gets called when a new metric is defined.
69  *
70  * handle - a performance stream handle from createPerformanceStream
71  * metricInfo - info about metric, client is resp. for deleting this struct
72  *
73  */
74 typedef void (*metricInfoCallback)(perfStreamHandle, 
75                                    const char *name,
76                                    int style,
77                                    int aggregate,
78                                    const char *units,
79                                    metricHandle handle,
80                                    dm_MetUnitsType units_type);
81
82 /*
83  * Handler that gets called when a new resource is defined.
84  *
85  * handle - a performance stream handle from createPerformanceStream
86  * parent               - parent of new resource
87  * newResource          - new resource being created
88  * name                 - name of the new resource, client must delete
89  *
90  */
91 typedef void (*resourceInfoCallback)(perfStreamHandle handle, 
92                                      resourceHandle parent, 
93                                      resourceHandle newResource, 
94                                      const char *name,
95                                      const char *abstraction);
96 typedef void (*memoryInfoCallback)(perfStreamHandle handle,
97                                 const char *data_structure,
98                                 int virtual_address,
99                                 u_int memory_size,
100                                 u_int blk_size,
101                                 resourceHandle parent,
102                                 vector<resourceHandle> *newResources) ;
103
104 typedef enum batchMode { batchStart, batchEnd };
105
106 typedef void (*resourceBatchModeCallback)(perfStreamHandle, batchMode mode); 
107
108 typedef void (*histFoldCallback)(perfStreamHandle, timeStamp width, phaseType);
109
110 typedef enum appState { appRunning, appPaused, appExited };
111
112 typedef void (*appStateChangeCallback)(perfStreamHandle, appState state);
113
114 typedef void (*newPhaseCallback)(perfStreamHandle handle, 
115                                  const char *name, 
116                                  phaseHandle phase,
117                                  timeStamp begin, 
118                                  timeStamp end, 
119                                  float bucketwidth,
120                                  bool with_new_pc,
121                                  bool with_visis); 
122
123 /*
124  * Handler that gets called when there is a response to a 
125  * getPredictedDataCost call 
126  *   
127  *   m_handle - the metricHandle assoc. with the request
128  *   rl_handle - the resourceListHandle assoc. with the request 
129  *   cost     - the cost of enabling the metric/focus pair
130  *   clientId - the identifier passed by the calling thread
131  */
132 typedef void (*predDataCostCallbackFunc)(u_int clientId,
133                                          float cost);
134
135 /*
136  * Handler that gets called when there is a response to an enableData request 
137  *   
138  * response -   vector of responses to enable request one element for each   
139  *              element in the vector passed by client to enableData request
140  * request_id - identifier that client thread associated with this call
141  *              (passed to DM on enableDataRequest)
142  */
143 typedef void (*enableDataCallbackFunc)(vector<metricInstInfo> *response,
144                                        u_int request_id);
145
146 struct controlCallback {
147     metricInfoCallback          mFunc;
148     resourceInfoCallback        rFunc;
149     resourceBatchModeCallback   bFunc;
150     histFoldCallback            fFunc;
151     appStateChangeCallback      sFunc;
152     newPhaseCallback            pFunc;
153     predDataCostCallbackFunc    cFunc;
154     enableDataCallbackFunc      eFunc;
155     memoryInfoCallback          xFunc;
156 };
157
158 typedef struct controlCallback controlCallback;
159
160 $remote dataManager {
161     $base 2500;
162     $version 54;
163
164     //
165     // Start a paradyn daemon
166     //
167     bool addDaemon (const char *machine,
168                     const char *login,
169                     const char *name);
170
171     // 
172     // Define a daemon in the daemon dictionary
173     //     command = command line to exec
174     //     dir = directory to use as working directory
175     //     login = user name to execute as
176     //     name = name of dictionary entry, for matching
177     //     flavor = programming environment (metPVM, metCM5, metUNIX)
178     //     machine = machine to run this daemon on
179     //
180     //     Note - arguments that are not used should be passed in
181     //            as null, anything else will be assumed to be a
182     //            valid string.
183      bool defineDaemon (const char *command,
184                         const char *dir,
185                         const char *login,
186                         const char *name,
187                         const char *machine,
188                         const char *remote_shell,
189                         const char *flavor);
190
191     //
192     // Define a program to run. 
193     //     machine = name of machine to run on
194     //     login = user to run as
195     //     name = name of daemon to run with, matches dictionary entry
196     //     dir = working directory to use
197     //
198     //     Note - arguments that are not used should be passed in
199     //            as null, anything else will be assumed to be a
200     //            valid string.
201     bool addExecutable(const char *machine, 
202                        const char *login, 
203                        const char *name, 
204                        const char *dir,
205                        const vector<string> *argv);
206
207     // Attach is the other way to start a process...newly implemented with v1.2
208     bool attach(const char *machine,
209                 const char *user,
210                 const char *cmd,
211                 const char *pidStr,
212                 const char *daemonName,
213                 int afterAttach // 1 --> pause, 2 --> run, 0 --> leave as is
214                 );
215                 
216     //
217     // Find out if an application has been defined yet.
218     //
219     bool applicationDefined();
220
221     //
222     // Start an application running (This starts the actual execution).
223     // 
224     bool startApplication();
225
226     //
227     //   Stop all processes associted with the application.
228     //
229     // Pause an application (I am not sure about this but I think we want it).
230     //      - Does this force buffered data to be delivered?
231     //  - Does a paused application respond to enable/disable commands?
232     //
233     bool pauseApplication();
234
235     void createCallGraph();
236
237     //
238     // Pause a process in an application 
239     //      - Does this force buffered data to be delivered?
240     //  - Does a paused application respond to enable/disable commands?
241     //
242     bool pauseProcess(int pid);
243
244     //
245     // Continue a paused application.
246     //
247     bool continueApplication();
248
249     //
250     // Continue a paused process in an application.
251     //
252     bool continueProcess(int pid);
253
254     //
255     // Disconnect the tool from the process.
256     //    pause - leave the process in a stopped state.
257     //
258     bool detachApplication(bool pause);
259
260     // 
261     // write all global data to files created in the dirname directory
262     // 
263     $async void saveAllData (const char *dirname, SaveRequestType optionFlag);
264
265     // 
266     // write all resource information to a file created in dirname
267     //
268     $async void saveAllResources (const char *dirname);
269
270     // 
271     // Create a performanceStream.  This a flow of performance information
272     //   to a destination. 
273     //
274     // dataType         - Sample or Trace
275     // dataCallback     - Function to call when new data arrives
276     // controlCallback  - Function to call when new structure info arrives
277     //
278     perfStreamHandle createPerformanceStream(dataType, 
279                                              dataCallback, 
280                                              controlCallback);
281
282     // 
283     // Destroy a performance Stream.  
284     // 
285     // perfStreamHandle   - a handle returned by createPerformanceStream
286     //
287     int  destroyPerformanceStream(perfStreamHandle);
288
289     //
290     // Routines to control data collection on a performance Stream.
291     //
292
293     //
294     // Request to enable a set of metric/focus pairs  
295     // ps_handle - the perfStreamHandle of the calling thread 
296     // pt_handle - the perfTraceStreamHandle of the calling thread 
297     // request   - vector of metic/focus pairs to enable
298     // request_Id - identifier passed by calling thread  
299     // type - which phase type to enable data for
300     // phaseId - the identifier of the phase for which data is requested
301     // persistent_data - if set data is not distroyed on last disable 
302     // persistent_collection - if set data collection isn't stoped on disable 
303     // phase_persistent_data - like persistent_data, but only valid for curr
304     //                         phase
305     //
306     $async void enableDataRequest(perfStreamHandle ps_handle,
307                                   perfStreamHandle pt_handle,
308                                   vector<metric_focus_pair> *request,
309                                   u_int request_Id,
310                                   phaseType type,
311                                   u_int phaseId,
312                                   u_int persistent_data,
313                                   u_int persistent_collection,
314                                   u_int phase_persistent_data);
315    // getMemoryBounds: get the bounds of shared-memory for
316     // tempest
317     $async void getMemoryBounds(perfStreamHandle ps_handle,
318                                 vector<metric_focus_pair> *request) ;
319
320     //
321     // same as enableDataRequest, but with diff type request
322     //
323     $async void enableDataRequest2(perfStreamHandle ps_handle,
324                                    vector<metricRLType> *request,
325                                    u_int request_Id,
326                                    phaseType type,
327                                    u_int phaseId,
328                                    u_int persistent_data,
329                                    u_int persistent_collection,
330                                    u_int phase_persistent_data);
331
332
333     //
334     // stop collecting data for the named metricInstance.
335     // perfStreamHandle - a handle returned by createPerformanceStream
336     // metricInstance   - a metricInstance returned by enableDataCollection.
337     // phaseType - specifies either global or current phase data
338     //
339     // If you are going to add something to a list using pt_handle on enable
340     // it would probably be a good idea to remove it useing pt_handle on
341     // disable rather than ps_handle...otherwise all those asserts you added
342     // to check the size of the list are bound to fail when the ps_handle
343     // and pt_handle are not the same.
344     $async void disableDataCollection(perfStreamHandle ps_handle, 
345                                       perfStreamHandle pt_handle,
346                                       metricInstanceHandle,
347                                       phaseType);
348
349     //
350     // stop collecting data for the named metricInstance and clear the
351     // persistent data flag(s) before disabling
352     // ps_handle - a handle returned by createPerformanceStream
353     // mi_handle - a metricInstance returned by enableDataCollection.
354     // p_type - specifies either global or current phase data
355     // clear_persistent_data - if true, clear persistent_data flag
356     // clear_phase_persistent_data - if true, clear phase_persistent_data flag
357     //
358     $async void disableDataAndClearPersistentData(perfStreamHandle ps_handle,
359                                          perfStreamHandle pt_handle,
360                                          metricInstanceHandle mi_handle,
361                                          phaseType p_type,
362                                          bool clear_persistent_data,
363                                          bool clear_phase_persistent_data);
364     //
365     // This routine returns a list of foci which are the result of combining
366     // each child of resource rh with the remaining resources that make up rlh
367     // if the resource rh is a component of the focus rlh, otherwise returns 0
368     //
369     vector<rlNameId> *magnify(resourceHandle rh, 
370                               resourceListHandle rlh,
371                               magnifyType m);
372
373     //
374     // if resource rh is a decendent of a component of the focus, return a new
375     // focus consisting of rh replaced with it's corresponding entry in rlh,
376     // otherwise return the focus rlh
377     //
378     resourceListHandle *constrain(resourceHandle rh, resourceListHandle rlh);
379
380     //
381     // like constrain, except it returns 0 on failure
382     //
383     resourceListHandle *morespecific(resourceHandle rh, resourceListHandle rlh);
384
385     //
386     // returns true if seppressSearch is true for this focus
387     //
388     bool isSuppressed(resourceListHandle rlh);
389
390     //
391     // returns the name for the focus associated with this MI
392     // returns 0 on error
393     //
394     const char *getFocusNameFromMI(metricInstanceHandle mi);
395
396     //
397     // returns the name for the focus associated with this resourceHandle
398     //
399     const char *getFocusName(const vector<resourceHandle>*);
400
401     //
402     // returns the name for the focus associated with this resourceListHandle
403     // returns 0 on error
404     //
405     const char *getFocusNameFromHandle(resourceListHandle rlh);
406
407     //
408     // change the persistent_collection flag value for the assoc. MI
409     //
410     $async void setPersistentCollection(metricInstanceHandle);
411     $async void clearPersistentCollection(metricInstanceHandle);
412
413     //
414     // change the persistent_data flag value for the assoc. MI
415     //
416     $async void setPersistentData(metricInstanceHandle);
417
418     // 
419     // this clears both persistent_data and phase_persistent_data flags of MI
420     // 
421     $async void clearPersistentData(metricInstanceHandle);
422
423     //
424     // Return the expected cost of collecting performance data for a single
425     //    metric at a given focus.  The value returned is the fraction of
426     //    perturbation expected (i.e. 0.10 == 10% slow down expected).
427     //    perfStreamHandle and u_int are idetifiers for the request
428     //
429     $async void getPredictedDataCost(perfStreamHandle,
430                                      metricHandle,
431                                      resourceListHandle,
432                                      u_int);
433
434     // 
435     // Histogram/timebase information
436     //
437     timeStamp getCurrentBucketWidth();
438
439     // 
440     // Histogram/timebase information
441     //
442     timeStamp getGlobalBucketWidth();
443
444     //
445     // phase info
446     //
447     u_int getCurrentPhaseId();
448     timeStamp getCurrentStartTime();
449
450     int getMaxBins();
451
452     //
453     // Resource utility functions.
454     //
455
456     //
457     // returns handle for root resource, returns NULL on error
458     //
459     resourceHandle *getRootResource();
460
461     //
462     // returns handles of root resources, returns NULL on error
463     //
464     vector<resourceHandle> *getRootResources();
465
466     //
467     // create a new resource and return it's handle
468     //
469     resourceHandle newResource(resourceHandle parent, 
470                                const char *name, 
471                                u_int type);
472
473     //
474     // converts from a vector of resourceHandles to a resourceListHandle
475     // 
476     resourceListHandle getResourceList(const vector<resourceHandle>*);
477
478     //
479     // converts from a resourceListHandle to a vector of resourceHandles
480     // client is responsible for deleting vector<resourceHandle>*
481     // 
482     vector<resourceHandle> *getResourceHandles(resourceListHandle);
483
484     //
485     // converts from a resource name to a resourceHandle 
486     // the resource name must be the full name ie. "/Code/blah.c/foo"
487     // returns NULL if conversion fails 
488     //
489     resourceHandle *findResource(const char *name);
490
491     //
492     // returns name of resource (this is not a unique representation of 
493     // the name instead it is the unique name trunctated)
494     // so for "/Code/blah.c/foo" this routine will return "foo"
495     //
496     const char *getResourceLabelName(resourceHandle);
497
498
499     //
500     // returns full name of a resource  ie. "/Code/blah.c/foo" 
501     //
502     const char *getResourceName(resourceHandle);
503
504     //
505     // converts from a focus name to a resourceListHandle 
506     // returns NULL if convertion fails 
507     //
508     resourceListHandle *findResourceList(const char *name);
509
510     //
511     // don't search the SHG for this node.
512     //
513     void setResourceSearchSuppress(resourceHandle res_handle, bool newValue);
514
515     //
516     // don't search the SHG for children of this node.
517     //
518     void setResourceSearchChildrenSuppress(resourceHandle res_handle, 
519                                            bool newValue);
520
521     //
522     // consider this resource a black box (applies to modules/procedures now).
523     //
524     void setResourceInstSuppress(resourceHandle res_handle, bool newValue);
525
526     // 
527     // returns a vector of metric names 
528     // client is responsible for deleting these
529     //
530     vector<string> *getAvailableMetrics(bool all);
531
532     //
533     // returns a vector of metric name and id pairs
534     // client is responsible for deleting these
535     //
536     vector<met_name_id> *getAvailableMetInfo(bool all);
537
538     //
539     // looks for a specifc metric instance
540     // returns NULL if search is unsuccessful
541     // 
542     metricHandle *findMetric(const char *name);
543
544     //
545     // Metric utility functions.
546     //
547     const char *getMetricName(metricHandle);
548
549     //
550     // get the supporting info about a metric.
551     //
552     T_dyninstRPC::metricInfo *getMetricInfo(metricHandle);
553
554     // TODO: these shouldn't be necessary
555     // Get metric out of a metric instance.
556     //
557     metricHandle *getMetric(metricInstanceHandle);
558     const char *getMetricNameFromMI(metricInstanceHandle);
559
560     //
561     // Get the value of a metric.
562     //
563     sampleValue getMetricValue(metricInstanceHandle);
564
565     //
566     // fill the passed array of buckets with the histogram sample from the
567     //   passed metricInstance.  
568     //          mi              metric instance to use
569     //          buckets         array of buckets to fill
570     //          numberOfBuckets max number of buckets to fill
571     //          first           first bin to fill (i.e. what bin goes into
572     //                          buckets[0]
573     //          phase           specifies either curr. or global phase data
574     //
575     int getSampleValues(metricInstanceHandle mi, 
576                         sampleValue *buckets,
577                         int numberOfBuckets,
578                         int first,
579                         phaseType phase);
580
581     //
582     // fill the passed array of buckets with the archived histogram values
583     // of the passed metricInstance
584     //      mi        which metric instance
585     //      phase_id  which phase
586     //
587     int getArchiveValues(metricInstanceHandle mi, 
588                         sampleValue *buckets,
589                         int numberOfBuckets,
590                         int first,
591                         phaseHandle phase_id);
592
593     //
594     // Get the total value of a metric. 
595     //  (ie. do not divide by time enabled)
596     //
597     sampleValue getTotValue(metricInstanceHandle);
598
599
600     //
601     //  start_Time: would allow a phase to be specified for some time
602     //              in the future, this would be useful for using phase
603     //              information from a config. file
604     //              a default value of -1.0 would be equivalent to now
605     //  name: would be an optional user defined identifier for the phase
606     //        each phase would still have a system defined unique id
607     //  with_new_pc: flag that indicates if new instance of PC should be
608     //               started with this phase (DM just takes value of flag
609     //               and passes it back on newPhaseCallbacks)
610     //  with_visis:  flag that indicates if new instance of curr. phase
611     //               visis should be started with the new phase (this 
612     //               option is not currently supported....the DM would
613     //               have to keep curr. phase MI's enabled for the new
614     //               phase by setting collection flags for the MI's
615     //               and calling a VM routine to start new versions of
616     //               all curr. phase visis with a pre-defined list of
617     //               MI's for each one)
618     //
619     $async void StartPhase(timeStamp start_Time, const char *name,
620                            bool with_new_pc, bool with_visis);
621
622
623     //
624     // returns a list of all currently defined phases in the system
625     // the caller is responsible for freeing the space associated with
626     // the list
627     //
628     vector<T_visi::phase_info> *getAllPhaseInfo();
629
630
631     //
632     // Debugger style calls.
633     //
634
635     void printResources();
636     void printStatus();
637     void coreProcess(int pid);
638
639     //
640     // probably temporary call, show defined daemons
641     //
642     void printDaemons();
643
644     //
645     // daemonStartInfo: provides information about the command line to start a 
646     // daemon manually (needed if a rshd is not available on a remote machine)
647     //
648     void displayDaemonStartInfo();
649     void printDaemonStartInfo(const char *filename);
650
651     //
652     // display information about Paradyn
653     //
654     void displayParadynGeneralInfo();
655     void displayParadynLicenseInfo();
656     void displayParadynReleaseInfo();
657     void displayParadynVersionInfo();
658
659     //
660     // return a list of daemon names
661     //
662     vector<string> *getAvailableDaemons();
663
664     //
665     // upcalls for indications of events.
666     //
667     $upcall $async void newMetricDefined(metricInfoCallback, 
668                                          perfStreamHandle, 
669                                          const char *name,
670                                          int style,
671                                          int aggregate,
672                                          const char *units,
673                                          metricHandle handle,
674                                          dm_MetUnitsType units_type);
675
676     $upcall $async void newMemoryDefined(memoryInfoCallback,
677                                            perfStreamHandle,
678                                            const char *vname,
679                                            int va,
680                                            u_int mem_size,
681                                            u_int blk_size,
682                                            resourceHandle p_handle,
683                                            vector<resourceHandle> *handles) ;
684
685     $upcall $async void newResourceDefined(resourceInfoCallback,
686                                            perfStreamHandle, 
687                                            resourceHandle parent,
688                                            resourceHandle newResource, 
689                                            const char *name,
690                                            const char *abstr);
691
692     $upcall $async void changeResourceBatchMode(resourceBatchModeCallback,
693                                                 perfStreamHandle, 
694                                                 batchMode mode);
695
696     // $upcall $async void newPerfData(sampleDataCallbackFunc, 
697     $upcall $async void newPerfData(sampleDataCallbackFunc sampleFunc, 
698                                     vector<dataValueType> *data,
699                                     u_int num_data_values);
700
701     // trace data streams
702     $upcall $async void newTracePerfData(traceDataCallbackFunc traceFunc,
703                                     vector<traceDataValueType> *traceData,
704                                     u_int num_traceData_values);
705
706     $upcall $async void predictedDataCost(predDataCostCallbackFunc func,
707                                      metricHandle m_handle,
708                                      resourceListHandle rl_handle, 
709                                      float cost,
710                                      u_int clientId);
711     
712     //
713     // response to enableDataRequest call
714     // func - callback function registered by client thread on createPerfStream
715     // response - vector of enable reponses to enable
716     // request_id - identifier passed by client to enableDataRequest
717     //
718     $upcall $async void enableDataCallback(enableDataCallbackFunc func,
719                                            vector<metricInstInfo> *response,
720                                            u_int request_id);
721
722
723     $upcall $async void histFold(histFoldCallback, 
724                                  perfStreamHandle, 
725                                  timeStamp width,
726                                  phaseType);
727
728     $upcall $async void changeState(appStateChangeCallback, 
729                                     perfStreamHandle, 
730                                     appState);
731
732     //
733     // Info. about a new phase that was created
734     //
735     $upcall $async void newPhaseInfo(newPhaseCallback, 
736                                      perfStreamHandle,
737                                      const char *,       // name
738                                      phaseHandle,       // unique id 
739                                      timeStamp,         // start time 
740                                      timeStamp,         // end time 
741                                      float,            // bucketwidth
742                                      bool,              // with_new_pc
743                                      bool);             // with_visis
744
745     $signore
746     static int sock_port;
747     static PDSOCKET sock_desc;
748     static bool DM_sequential_init(const char*);
749     static int DM_post_thread_create_init(thread_t);
750     static dataManager *dm;  // need this so can call setTid which is
751                              // not a static function, otherwise could
752                              // just define all DM functions as static
753     $signore
754 };
755
756 #endif