updating the feature formerly known as SAVE.
[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.88 1999/05/19 21:15:37 karavan 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 52;
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 *flavor);
189
190     //
191     // Define a program to run. 
192     //     machine = name of machine to run on
193     //     login = user to run as
194     //     name = name of daemon to run with, matches dictionary entry
195     //     dir = working directory to use
196     //
197     //     Note - arguments that are not used should be passed in
198     //            as null, anything else will be assumed to be a
199     //            valid string.
200     bool addExecutable(const char *machine, 
201                        const char *login, 
202                        const char *name, 
203                        const char *dir,
204                        const vector<string> *argv);
205
206     // Attach is the other way to start a process...newly implemented with v1.2
207     bool attach(const char *machine,
208                 const char *user,
209                 const char *cmd,
210                 const char *pidStr,
211                 const char *daemonName,
212                 int afterAttach // 1 --> pause, 2 --> run, 0 --> leave as is
213                 );
214                 
215     //
216     // Find out if an application has been defined yet.
217     //
218     bool applicationDefined();
219
220     //
221     // Start an application running (This starts the actual execution).
222     // 
223     bool startApplication();
224
225     //
226     //   Stop all processes associted with the application.
227     //
228     // Pause an application (I am not sure about this but I think we want it).
229     //      - Does this force buffered data to be delivered?
230     //  - Does a paused application respond to enable/disable commands?
231     //
232     bool pauseApplication();
233
234     //
235     // Pause a process in an application 
236     //      - Does this force buffered data to be delivered?
237     //  - Does a paused application respond to enable/disable commands?
238     //
239     bool pauseProcess(int pid);
240
241     //
242     // Continue a paused application.
243     //
244     bool continueApplication();
245
246     //
247     // Continue a paused process in an application.
248     //
249     bool continueProcess(int pid);
250
251     //
252     // Disconnect the tool from the process.
253     //    pause - leave the process in a stopped state.
254     //
255     bool detachApplication(bool pause);
256
257     // 
258     // write all global data to files created in the dirname directory
259     // 
260     $async void saveAllData (const char *dirname, SaveRequestType optionFlag);
261
262     // 
263     // write all resource information to a file created in dirname
264     //
265     $async void saveAllResources (char *dirname);
266
267     // 
268     // Create a performanceStream.  This a flow of performance information
269     //   to a destination. 
270     //
271     // dataType         - Sample or Trace
272     // dataCallback     - Function to call when new data arrives
273     // controlCallback  - Function to call when new structure info arrives
274     //
275     perfStreamHandle createPerformanceStream(dataType, 
276                                              dataCallback, 
277                                              controlCallback);
278
279     // 
280     // Destroy a performance Stream.  
281     // 
282     // perfStreamHandle   - a handle returned by createPerformanceStream
283     //
284     int  destroyPerformanceStream(perfStreamHandle);
285
286     //
287     // Routines to control data collection on a performance Stream.
288     //
289
290     //
291     // Request to enable a set of metric/focus pairs  
292     // ps_handle - the perfStreamHandle of the calling thread 
293     // pt_handle - the perfTraceStreamHandle of the calling thread 
294     // request   - vector of metic/focus pairs to enable
295     // request_Id - identifier passed by calling thread  
296     // type - which phase type to enable data for
297     // phaseId - the identifier of the phase for which data is requested
298     // persistent_data - if set data is not distroyed on last disable 
299     // persistent_collection - if set data collection isn't stoped on disable 
300     // phase_persistent_data - like persistent_data, but only valid for curr
301     //                         phase
302     //
303     $async void enableDataRequest(perfStreamHandle ps_handle,
304                                   perfStreamHandle pt_handle,
305                                   vector<metric_focus_pair> *request,
306                                   u_int request_Id,
307                                   phaseType type,
308                                   u_int phaseId,
309                                   u_int persistent_data,
310                                   u_int persistent_collection,
311                                   u_int phase_persistent_data);
312    // getMemoryBounds: get the bounds of shared-memory for
313     // tempest
314     $async void getMemoryBounds(perfStreamHandle ps_handle,
315                                 vector<metric_focus_pair> *request) ;
316
317     //
318     // same as enableDataRequest, but with diff type request
319     //
320     $async void enableDataRequest2(perfStreamHandle ps_handle,
321                                    vector<metricRLType> *request,
322                                    u_int request_Id,
323                                    phaseType type,
324                                    u_int phaseId,
325                                    u_int persistent_data,
326                                    u_int persistent_collection,
327                                    u_int phase_persistent_data);
328
329
330     //
331     // stop collecting data for the named metricInstance.
332     // perfStreamHandle - a handle returned by createPerformanceStream
333     // metricInstance   - a metricInstance returned by enableDataCollection.
334     // phaseType - specifies either global or current phase data
335     //
336     // If you are going to add something to a list using pt_handle on enable
337     // it would probably be a good idea to remove it useing pt_handle on
338     // disable rather than ps_handle...otherwise all those asserts you added
339     // to check the size of the list are bound to fail when the ps_handle
340     // and pt_handle are not the same.
341     $async void disableDataCollection(perfStreamHandle ps_handle, 
342                                       perfStreamHandle pt_handle,
343                                       metricInstanceHandle,
344                                       phaseType);
345
346     //
347     // stop collecting data for the named metricInstance and clear the
348     // persistent data flag(s) before disabling
349     // ps_handle - a handle returned by createPerformanceStream
350     // mi_handle - a metricInstance returned by enableDataCollection.
351     // p_type - specifies either global or current phase data
352     // clear_persistent_data - if true, clear persistent_data flag
353     // clear_phase_persistent_data - if true, clear phase_persistent_data flag
354     //
355     $async void disableDataAndClearPersistentData(perfStreamHandle ps_handle,
356                                          perfStreamHandle pt_handle,
357                                          metricInstanceHandle mi_handle,
358                                          phaseType p_type,
359                                          bool clear_persistent_data,
360                                          bool clear_phase_persistent_data);
361     //
362     // This routine returns a list of foci which are the result of combining
363     // each child of resource rh with the remaining resources that make up rlh
364     // if the resource rh is a component of the focus rlh, otherwise returns 0
365     //
366     vector<rlNameId> *magnify(resourceHandle rh, 
367                                         resourceListHandle rlh);
368
369     //
370     // returns a list of foci each of which is the result of combining a child
371     // of one of the resources with the remaining resource components of rlh,
372     // this routine returns 0 if no resource components of rlh have children
373     //
374     vector<rlNameId> *magnify2(resourceListHandle rlh);
375
376     //
377     // if resource rh is a decendent of a component of the focus, return a new
378     // focus consisting of rh replaced with it's corresponding entry in rlh,
379     // otherwise return the focus rlh
380     //
381     resourceListHandle *constrain(resourceHandle rh, resourceListHandle rlh);
382
383     //
384     // like constrain, except it returns 0 on failure
385     //
386     resourceListHandle *morespecific(resourceHandle rh, resourceListHandle rlh);
387
388     //
389     // returns true if seppressSearch is true for this focus
390     //
391     bool isSuppressed(resourceListHandle rlh);
392
393     //
394     // returns the name for the focus associated with this MI
395     // returns 0 on error
396     //
397     const char *getFocusNameFromMI(metricInstanceHandle mi);
398
399     //
400     // returns the name for the focus associated with this resourceHandle
401     //
402     const char *getFocusName(const vector<resourceHandle>*);
403
404     //
405     // returns the name for the focus associated with this resourceListHandle
406     // returns 0 on error
407     //
408     const char *getFocusNameFromHandle(resourceListHandle rlh);
409
410     //
411     // change the persistent_collection flag value for the assoc. MI
412     //
413     $async void setPersistentCollection(metricInstanceHandle);
414     $async void clearPersistentCollection(metricInstanceHandle);
415
416     //
417     // change the persistent_data flag value for the assoc. MI
418     //
419     $async void setPersistentData(metricInstanceHandle);
420
421     // 
422     // this clears both persistent_data and phase_persistent_data flags of MI
423     // 
424     $async void clearPersistentData(metricInstanceHandle);
425
426     //
427     // Return the expected cost of collecting performance data for a single
428     //    metric at a given focus.  The value returned is the fraction of
429     //    perturbation expected (i.e. 0.10 == 10% slow down expected).
430     //    perfStreamHandle and u_int are idetifiers for the request
431     //
432     $async void getPredictedDataCost(perfStreamHandle,
433                                      metricHandle,
434                                      resourceListHandle,
435                                      u_int);
436
437     // 
438     // Histogram/timebase information
439     //
440     timeStamp getCurrentBucketWidth();
441
442     // 
443     // Histogram/timebase information
444     //
445     timeStamp getGlobalBucketWidth();
446
447     //
448     // phase info
449     //
450     u_int getCurrentPhaseId();
451     timeStamp getCurrentStartTime();
452
453     int getMaxBins();
454
455     //
456     // Resource utility functions.
457     //
458
459     //
460     // returns handle for root resource, returns NULL on error
461     //
462     resourceHandle *getRootResource();
463
464     //
465     // returns handles of root resources, returns NULL on error
466     //
467     vector<resourceHandle> *getRootResources();
468
469     //
470     // create a new resource and return it's handle
471     //
472     resourceHandle newResource(resourceHandle parent, 
473                                const char *name, 
474                                u_int type);
475
476     //
477     // converts from a vector of resourceHandles to a resourceListHandle
478     // 
479     resourceListHandle getResourceList(const vector<resourceHandle>*);
480
481     //
482     // converts from a resourceListHandle to a vector of resourceHandles
483     // client is responsible for deleting vector<resourceHandle>*
484     // 
485     vector<resourceHandle> *getResourceHandles(resourceListHandle);
486
487     //
488     // converts from a resource name to a resourceHandle 
489     // the resource name must be the full name ie. "/Code/blah.c/foo"
490     // returns NULL if conversion fails 
491     //
492     resourceHandle *findResource(const char *name);
493
494     //
495     // returns name of resource (this is not a unique representation of 
496     // the name instead it is the unique name trunctated)
497     // so for "/Code/blah.c/foo" this routine will return "foo"
498     //
499     const char *getResourceLabelName(resourceHandle);
500
501
502     //
503     // returns full name of a resource  ie. "/Code/blah.c/foo" 
504     //
505     const char *getResourceName(resourceHandle);
506
507     //
508     // converts from a focus name to a resourceListHandle 
509     // returns NULL if convertion fails 
510     //
511     resourceListHandle *findResourceList(const char *name);
512
513     //
514     // don't search the SHG for this node.
515     //
516     void setResourceSearchSuppress(resourceHandle res_handle, bool newValue);
517
518     //
519     // don't search the SHG for children of this node.
520     //
521     void setResourceSearchChildrenSuppress(resourceHandle res_handle, 
522                                            bool newValue);
523
524     //
525     // consider this resource a black box (applies to modules/procedures now).
526     //
527     void setResourceInstSuppress(resourceHandle res_handle, bool newValue);
528
529     // 
530     // returns a vector of metric names 
531     // client is responsible for deleting these
532     //
533     vector<string> *getAvailableMetrics(bool all);
534
535     //
536     // returns a vector of metric name and id pairs
537     // client is responsible for deleting these
538     //
539     vector<met_name_id> *getAvailableMetInfo(bool all);
540
541     //
542     // looks for a specifc metric instance
543     // returns NULL if search is unsuccessful
544     // 
545     metricHandle *findMetric(const char *name);
546
547     //
548     // Metric utility functions.
549     //
550     const char *getMetricName(metricHandle);
551
552     //
553     // get the supporting info about a metric.
554     //
555     T_dyninstRPC::metricInfo *getMetricInfo(metricHandle);
556
557     // TODO: these shouldn't be necessary
558     // Get metric out of a metric instance.
559     //
560     metricHandle *getMetric(metricInstanceHandle);
561     const char *getMetricNameFromMI(metricInstanceHandle);
562
563     //
564     // Get the value of a metric.
565     //
566     sampleValue getMetricValue(metricInstanceHandle);
567
568     //
569     // fill the passed array of buckets with the histogram sample from the
570     //   passed metricInstance.  
571     //          mi              metric instance to use
572     //          buckets         array of buckets to fill
573     //          numberOfBuckets max number of buckets to fill
574     //          first           first bin to fill (i.e. what bin goes into
575     //                          buckets[0]
576     //          phase           specifies either curr. or global phase data
577     //
578     int getSampleValues(metricInstanceHandle mi, 
579                         sampleValue *buckets,
580                         int numberOfBuckets,
581                         int first,
582                         phaseType phase);
583
584     //
585     // fill the passed array of buckets with the archived histogram values
586     // of the passed metricInstance
587     //      mi        which metric instance
588     //      phase_id  which phase
589     //
590     int getArchiveValues(metricInstanceHandle mi, 
591                         sampleValue *buckets,
592                         int numberOfBuckets,
593                         int first,
594                         phaseHandle phase_id);
595
596     //
597     // Get the total value of a metric. 
598     //  (ie. do not divide by time enabled)
599     //
600     sampleValue getTotValue(metricInstanceHandle);
601
602
603     //
604     //  start_Time: would allow a phase to be specified for some time
605     //              in the future, this would be useful for using phase
606     //              information from a config. file
607     //              a default value of -1.0 would be equivalent to now
608     //  name: would be an optional user defined identifier for the phase
609     //        each phase would still have a system defined unique id
610     //  with_new_pc: flag that indicates if new instance of PC should be
611     //               started with this phase (DM just takes value of flag
612     //               and passes it back on newPhaseCallbacks)
613     //  with_visis:  flag that indicates if new instance of curr. phase
614     //               visis should be started with the new phase (this 
615     //               option is not currently supported....the DM would
616     //               have to keep curr. phase MI's enabled for the new
617     //               phase by setting collection flags for the MI's
618     //               and calling a VM routine to start new versions of
619     //               all curr. phase visis with a pre-defined list of
620     //               MI's for each one)
621     //
622     $async void StartPhase(timeStamp start_Time, const char *name,
623                            bool with_new_pc, bool with_visis);
624
625
626     //
627     // returns a list of all currently defined phases in the system
628     // the caller is responsible for freeing the space associated with
629     // the list
630     //
631     vector<T_visi::phase_info> *getAllPhaseInfo();
632
633
634     //
635     // Debugger style calls.
636     //
637
638     void printResources();
639     void printStatus();
640     void coreProcess(int pid);
641
642     //
643     // probably temporary call, show defined daemons
644     //
645     void printDaemons();
646
647     //
648     // daemonStartInfo: provides information about the command line to start a 
649     // daemon manually (needed if a rshd is not available on a remote machine)
650     //
651     void displayDaemonStartInfo();
652     void printDaemonStartInfo(const char *filename);
653
654     //
655     // display information about Paradyn
656     //
657     void displayParadynGeneralInfo();
658     void displayParadynLicenseInfo();
659     void displayParadynReleaseInfo();
660     void displayParadynVersionInfo();
661
662     //
663     // return a list of daemon names
664     //
665     vector<string> *getAvailableDaemons();
666
667     //
668     // upcalls for indications of events.
669     //
670     $upcall $async void newMetricDefined(metricInfoCallback, 
671                                          perfStreamHandle, 
672                                          const char *name,
673                                          int style,
674                                          int aggregate,
675                                          const char *units,
676                                          metricHandle handle,
677                                          dm_MetUnitsType units_type);
678
679     $upcall $async void newMemoryDefined(memoryInfoCallback,
680                                            perfStreamHandle,
681                                            const char *vname,
682                                            int va,
683                                            u_int mem_size,
684                                            u_int blk_size,
685                                            resourceHandle p_handle,
686                                            vector<resourceHandle> *handles) ;
687
688     $upcall $async void newResourceDefined(resourceInfoCallback,
689                                            perfStreamHandle, 
690                                            resourceHandle parent,
691                                            resourceHandle newResource, 
692                                            const char *name,
693                                            const char *abstr);
694
695     $upcall $async void changeResourceBatchMode(resourceBatchModeCallback,
696                                                 perfStreamHandle, 
697                                                 batchMode mode);
698
699     // $upcall $async void newPerfData(sampleDataCallbackFunc, 
700     $upcall $async void newPerfData(sampleDataCallbackFunc sampleFunc, 
701                                     vector<dataValueType> *data,
702                                     u_int num_data_values);
703
704     // trace data streams
705     $upcall $async void newTracePerfData(traceDataCallbackFunc traceFunc,
706                                     vector<traceDataValueType> *traceData,
707                                     u_int num_traceData_values);
708
709     $upcall $async void predictedDataCost(predDataCostCallbackFunc func,
710                                      metricHandle m_handle,
711                                      resourceListHandle rl_handle, 
712                                      float cost,
713                                      u_int clientId);
714     
715     //
716     // response to enableDataRequest call
717     // func - callback function registered by client thread on createPerfStream
718     // response - vector of enable reponses to enable
719     // request_id - identifier passed by client to enableDataRequest
720     //
721     $upcall $async void enableDataCallback(enableDataCallbackFunc func,
722                                            vector<metricInstInfo> *response,
723                                            u_int request_id);
724
725
726     $upcall $async void histFold(histFoldCallback, 
727                                  perfStreamHandle, 
728                                  timeStamp width,
729                                  phaseType);
730
731     $upcall $async void changeState(appStateChangeCallback, 
732                                     perfStreamHandle, 
733                                     appState);
734
735     //
736     // Info. about a new phase that was created
737     //
738     $upcall $async void newPhaseInfo(newPhaseCallback, 
739                                      perfStreamHandle,
740                                      const char *,       // name
741                                      phaseHandle,       // unique id 
742                                      timeStamp,         // start time 
743                                      timeStamp,         // end time 
744                                      float,            // bucketwidth
745                                      bool,              // with_new_pc
746                                      bool);             // with_visis
747
748     $signore
749     static int sock_port;
750     static PDSOCKET sock_desc;
751     static bool DM_sequential_init(const char*);
752     static int DM_post_thread_create_init(thread_t);
753     static dataManager *dm;  // need this so can call setTid which is
754                              // not a static function, otherwise could
755                              // just define all DM functions as static
756     $signore
757 };
758
759 #endif