second part of sampling rate change
[dyninst.git] / paradyn / src / DMthread / README
1 section (I) DM objects
2 section (II) persistence flags
3 section (III) phase interface
4 section (IV) rules for changing the sampling rate
5
6 (I) DM objects
7 --------------
8 These objects, once created, are never destroyed:
9         resourceList
10         resource
11         metric
12         phaseInfo
13
14 These objects, once created, can be destroyed:
15         metricInstance
16         performanceStream
17
18 All DM objects should be referred to by their handles outside of the DM thread.
19 The only operations that clients should perform with DM handles are 
20 == and !=  (these operators will always be supported by DM handle types, so 
21 clients can compare handle values directly), any other information that a 
22 client needs about a DM object can be obtained by passing the appropriate
23 handle to a dataManager interface routine.
24
25 Within the DM thread, care should be taken when using pointers to objects that
26 are not persistent (metricInstance and performanceStream)
27
28
29 (II) Persistence Flags
30 ----------------------
31 persistence flags are associated with metricInstances  (a metric/focus pair)
32 they can be set on enable requests and set/cleared by invoking DM methods
33
34 persistent_data: if set, histogram data is not deleted on the last disable
35                  for the associated metricInstance
36                  if clear, the last disable destroys the histogram data
37
38 persistent_collection: if set, data collection is not disabled when the last
39                        client disables collection for this MI
40                        if clear, the last disable for an MI disables data 
41                        collection from the daemons.
42
43 new phase:  if persistent_data flag is set, then the current histogram is
44             archived (these data values can be accessed by clients by 
45             specifying the phaseHandle associated with the old histogram)
46
47             if persistent_collection flag is set, then a histogram is created
48             for the new phase and performance data is collected for it.  
49
50             Currently, persistent collection does not imply persistent data
51             (old histogram values are not archived if the persistent_data 
52             flag is clear and the persistent_collection flag is set).  It is
53             not clear that this is the correct interpretation, and we may
54             want to change the implementation so that persistent collection
55             does imply persistent data.
56
57
58 (III) Phase Interface 
59 ---------------------
60 phases are non-overlapping contiguous sequential time spans within an
61 applications execution.
62
63 data collection
64 ---------------
65 * Data collection can be enabled for a metric/focus pair for either the
66   global phase or for the currently active phase.
67
68 * global data is kept for any MI with active users
69
70 * persistent_collection and persistent_data flags can be set/cleared
71   on a MI granularity
72
73 * an enable request for an MI takes persistent flag arguments, the
74   resulting flags for the MI are the OR of the current value and
75   the value of the arguments (to clear a previously set flag requires
76   invoking a DM method function to do so rather than via an enable request) 
77
78 * archived data for old phases can be obtained by a client
79
80 on enable
81 ---------
82 if enable for global phase: just collect global histogram data
83 if enable for currphase: collect data for both global and current histograms
84
85 on new phase start:
86 -------------------
87 * old phase ends
88     - disable collection for all subscribers to the current phase
89
90 * if persistent_data flag is set for a metricInstance
91     - archive the histogram data for the current phase 
92
93 * if persistent_collection flag is clear for a metricInstance and there
94   are no global subscribers for the MI
95     - disable data collection for the MI from the daemons
96
97 * if persistent_collection flag is set
98     - create a new data Histogram for the new phase and continue to 
99       collect data for this MI
100     - the list of subscribers for the new phase data is empty until
101       a subscriber enables data collection for this MI for the new phase
102
103 * if persistent_collection flag is clear and there exists global phase
104   subscribers for an MI
105     - don't create a new data Histogram for the new phase, but continue
106       to collect global data for this MI
107
108 * if persistent_collection and persistent_data are both clear and there
109   are not global subscribers
110     - data collection for the MI is disabled from the daemons
111     - collection for all subscribers to curr. phase is disabled
112     - the MI object is deleted
113
114 * stop the search for a PC for the current phase 
115
116 * visualizations are defined for either the global phase or for the
117   current phase.  current phase stop receiving data when a new phase
118   is defined
119
120 on folds:
121 ---------
122 a fold callback will specify a phaseType (currPhase or globalPhase)
123
124 the client is responsible for doing the appropriate thing with the
125 fold callback;  ignore it if it is not for the phase that it is 
126 receiving data for or not if it is.
127
128 this will allow a perf. stream to receive more than one type
129 of phase data (both currPhase and globalPhase) as well as avoid
130 making multiple phase calls to the same perf. stream which would
131 result if folds were called on a per/MI basis
132
133
134 on set/clear persistence flags: 
135 -------------------------------
136 these routines have no enable/disable side effects, but when a fold, enable,
137 disable, or new phase event occurs then the appropriate action will take place.
138
139
140 on disable MI
141 -------------
142 if persistent_collection flag is set:  just remove client form user list
143                                        don't disable data collection for MI
144                                        or delete histograms
145 if persistent_data flag is set: don't delete MI...leave all histograms intact
146
147 if this is the last currPhase disable: then remove user from currlist and
148                                        delete curr histogram if persistent_data
149                                        flag is clear and delete MI and disable
150                                        data collection from daemons if there
151                                        are no global clients and persistent_
152                                        collection flag is clear 
153 if this is the last globalPhase disable: remove user from global list. If
154                                          there are no currlist subscribers, then
155                                          disable data collection if persistent_
156                                          collection is clear, and delete MI
157                                          if persistent_data is clear
158
159 (IV) Sampling rate changes
160
161 The sampling rate is related to the histogram bucket size.  Changes in the
162 sampling rate depend on the set of active histograms.
163
164 On Folds
165 --------
166 The sampling rate decreases to match the new bucketwidth.  If this is a fold
167 for a current phase histogram, then the new sampling rate = new bucketsize.
168 If this is a global phase fold, and there are no active current phase
169 histograms, then sampling rate = new global bucketsize.  Otherwise the 
170 sampling rate is not changed.
171
172 On Phase Start
173 --------------
174 If the persistent collection flag is set for any MI, then the sampling rate
175 is set to the bucket size of corresponding to the new current phase histograms.
176 Otherwise, the sampling rate is set to the bucketsize of the global phase
177 histogram bucketWidth.  If there are no currently active MI's then nothing 
178 happens to the sampling rate.
179
180
181 On Enabling Data Collection
182 ---------------------------
183 If this is the first current phase data enable, set  the sampling rate to the
184 current phase histogram bucket size.  If this is the first global phase data
185 enable, and there are no curr. phase enables, then set the sampling rate to
186 the global histogram bucket size.  Otherwise, don't change sampling rate.
187
188 On Disable Data Collection
189 --------------------------
190 If this is the last curr. phase data disable, then set the sampling rate
191 to the global histogram bucket size. Otherwise, do nothing.