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