XFontStruct --> Tk_Font
[dyninst.git] / paradyn / src / TCthread / tunableConst.h
1 /*
2  * Copyright (c) 1996 Barton P. Miller
3  * 
4  * We provide the Paradyn Parallel Performance Tools (below
5  * described as Paradyn") on an AS IS basis, and do not warrant its
6  * validity or performance.  We reserve the right to update, modify,
7  * or discontinue this software at any time.  We shall have no
8  * obligation to supply such updates or modifications or any other
9  * form of support to you.
10  * 
11  * This license is for research uses.  For such uses, there is no
12  * charge. We define "research use" to mean you may freely use it
13  * inside your organization for whatever purposes you see fit. But you
14  * may not re-distribute Paradyn or parts of Paradyn, in any form
15  * source or binary (including derivatives), electronic or otherwise,
16  * to any other organization or entity without our permission.
17  * 
18  * (for other uses, please contact us at paradyn@cs.wisc.edu)
19  * 
20  * All warranties, including without limitation, any warranty of
21  * merchantability or fitness for a particular purpose, are hereby
22  * excluded.
23  * 
24  * By your use of Paradyn, you understand and agree that we (or any
25  * other person or entity with proprietary rights in Paradyn) are
26  * under no obligation to provide either maintenance services,
27  * update services, notices of latent defects, or correction of
28  * defects for Paradyn.
29  * 
30  * Even if advised of the possibility of such damages, under no
31  * circumstances shall we (or any other person or entity with
32  * proprietary rights in the software licensed hereunder) be liable
33  * to you or any third party for direct, indirect, or consequential
34  * damages of any character regardless of type of action, including,
35  * without limitation, loss of profits, loss of use, loss of good
36  * will, or computer failure or malfunction.  You agree to indemnify
37  * us (and any other person or entity with proprietary rights in the
38  * software licensed hereunder) for any and all liability it may
39  * incur to third parties resulting from your use of Paradyn.
40  */
41
42 /*
43  * tunableConstant - a constant that might be changed during execution.
44  *
45  * $Log: tunableConst.h,v $
46  * Revision 1.6  1996/08/16 21:04:37  tamches
47  * updated copyright for release 1.1
48  *
49  * Revision 1.5  1995/12/20 02:26:42  tamches
50  * general cleanup
51  *
52  * Revision 1.4  1995/11/06 19:25:54  tamches
53  * dictionary_hash --> dictionary_lite
54  *
55  * Revision 1.3  1995/10/12 18:35:26  tamches
56  * Changed a lot of prototypes from "string" to "const string &", which is
57  * better because it doesn't make an unneeded and expensive string copy.
58  *
59  * Revision 1.2  1995/06/24  20:49:48  tamches
60  * Removed setValue() and print() for individual tc's.
61  *
62  * Revision 1.1  1995/02/27  18:50:05  tamches
63  * First version of TCthread; files tunableConst.h and .C have
64  * simply moved from the util lib (and have been changed); file
65  * TCmain.C is completely new.
66  *
67  */
68
69 #ifndef TUNABLE_CONST_H
70 #define TUNABLE_CONST_H
71
72 #include <assert.h>
73 #include <iostream.h>
74 #include <string.h>
75 #include "util/h/String.h"
76 #include "util/h/DictionaryLite.h"
77
78 typedef enum tunableUse { developerConstant, userConstant };
79 typedef enum tunableType { tunableBoolean, tunableFloat };
80
81 typedef bool (*isValidFunc)(float newVal);
82 typedef void (*booleanChangeValCallBackFunc)(bool value);
83 typedef void (*floatChangeValCallBackFunc)(float value);
84
85 /* ****************************************************************
86  * ******************** tunableConstantBase ***********************
87  * ****************************************************************
88  * 
89  * Every tunable constant stored in the central registry is derived from
90  * this base class, which provides name, description, type (bool/float),
91  * and use (user/developer) fields.
92  *
93  * Outside code should probably never need to know about this class.
94  *
95  * To obtain a read-only copy of a tunable constant, see routines like:
96  * 
97  *   tunableBooleanConstant myConst = tunableConstantRegistry::findBoolTunableConstant(string);
98  *   tunableFloatConstant myConst = tunableConstantRegistry::findFloatTunableConstant(string);
99  *
100  * To make changes take effect in the central registry, try:
101  * 
102  *   tunableConstantRegistry::setBoolTunableConstant(const string &, bool newValue);
103  *   tunableConstantRegistry::setFloatTunableConstant(const string &, float newValue);
104  *
105  * Note the purposeful returning of **copies**.  There are no pointers held across
106  * threads.  This should lead to a pretty clean design.
107  *
108  * ****************************************************************
109 */
110
111 class tunableConstantBase {
112  protected:
113    string name;
114    string desc;
115    string tag;
116    tunableType typeName;
117    tunableUse use;
118
119    tunableConstantBase() { } // needed for Pair class
120
121    tunableConstantBase(const string &iname, const string &idesc,
122                        const tunableType theType,
123                        const tunableUse  theUse);
124
125  public:
126
127    tunableConstantBase(const tunableConstantBase &src) :
128       name(src.name), desc(src.desc), tag(src.tag),
129       typeName(src.typeName), use(src.use) {
130    }
131
132    virtual ~tunableConstantBase();
133
134    bool operator==(const tunableConstantBase &other) const {
135       return (this->name == other.name);
136    }
137
138    const string &getDesc() const { return desc; }
139    const string &getName() const { return name; }
140    const string &getTag() const { return tag; }
141    tunableUse  getUse()  const { return use; }
142    tunableType getType() const { return typeName; }
143 };
144
145 /* ****************************************************************
146  * ******************** tunableBooleanConstant ********************
147  * ****************************************************************
148  * 
149  * Outside code should not declare variables of this class, except
150  * as the return value of tunableConstantRegistry::findBoolTunableConstant()
151  * That's why the meaty constructor was made private.
152  *
153  * ****************************************************************
154  */
155
156 class tunableBooleanConstant : public tunableConstantBase {
157  friend class tunableConstantRegistry;
158  friend class pair<string, tunableBooleanConstant>;
159
160  private:
161    bool value;
162    booleanChangeValCallBackFunc newValueCallBack;
163
164    tunableBooleanConstant(bool initialValue, 
165                           booleanChangeValCallBackFunc cb,
166                           tunableUse use,
167                           const string &iname,
168                           const string &idesc);
169
170  public:
171    tunableBooleanConstant() : tunableConstantBase() {} // needed by Pair.h ONLY
172    tunableBooleanConstant(unsigned) : tunableConstantBase() {} // needed by Pair.h ONLY
173    tunableBooleanConstant(const tunableBooleanConstant &src) {
174       this->value = src.value;
175       this->newValueCallBack = src.newValueCallBack;
176    }
177
178    bool getValue() const {return value;}
179 };
180
181 /* ****************************************************************
182  * ******************** tunableFloatConstant **********************
183  * ****************************************************************
184  * 
185  * Outside code should not declare variables of this class, except
186  * as the return value of tunableConstantRegistry::findFloatTunableConstant()
187  * That's why the meaty constructor was made private.
188  *
189  * ****************************************************************
190  */
191
192 class tunableFloatConstant : public tunableConstantBase {
193  friend class tunableConstantRegistry;
194  friend class pair<string, tunableFloatConstant>;
195
196  private:
197    float value;
198    float min, max;
199    isValidFunc isValidValue;
200    floatChangeValCallBackFunc newValueCallBack;
201
202    bool simpleRangeCheck(float val); // a default range checker
203
204    tunableFloatConstant(const string &iname,
205                         const string &idesc,
206                         float initialValue, 
207                         float min, float max,
208                         floatChangeValCallBackFunc cb,
209                         tunableUse use);
210    tunableFloatConstant(const string &iname,
211                         const string &idesc,
212                         float initialValue, 
213                         isValidFunc ivf, 
214                         floatChangeValCallBackFunc cb,
215                         tunableUse use);
216
217  public:
218
219    tunableFloatConstant() : tunableConstantBase() {} // needed by Pair.h ONLY
220    tunableFloatConstant(unsigned) : tunableConstantBase() {} // needed by Pair.h ONLY
221    tunableFloatConstant(const tunableFloatConstant &src);
222
223    float getValue() const {return value;}
224
225    float getMin() const {return min;}
226    float getMax() const {return max;}
227 };
228
229 /* *****************************************************************
230  * ******************** tunableConstantRegistry ********************
231  * *****************************************************************
232  *
233  * Contains a lot of static member functions meant for use by outside code.
234  *
235  * Contains two very important local (static) variables: associative arrays
236  * for boolean and float constants.
237  *
238  * *****************************************************************
239 */
240
241 class tunableConstantRegistry {
242  private:
243    typedef dictionary_lite<string, tunableBooleanConstant> tunBoolAssocArrayType;
244    typedef dictionary_lite<string, tunableFloatConstant>   tunFloatAssocArrayType;
245
246    // the central registry is comprised of these two arrays:
247    static tunBoolAssocArrayType  allBoolTunables;
248    static tunFloatAssocArrayType allFloatTunables;
249
250  public:
251    // Methods not specific to bool v. float:
252
253    static bool existsTunableConstant(const string &);
254       // true iff the tunable constant exists, regardless of type.
255
256    static tunableType getTunableConstantType(const string &);
257       // Perhaps a prelude to deciding whether to call "findBoolTunableConstant"
258       // or "findFloatTunableConstant".  Will (eventually be implemented to) raise
259       // an exception if not found.
260
261    static unsigned numTunables();
262
263    static tunableConstantBase getGenericTunableConstantByName(const string &);
264       // will (eventually be implemented to) throw an exception if name is not found.
265
266    // Methods specific to boolean tunable constants:
267    static unsigned numBoolTunables();
268
269    static bool createBoolTunableConstant(const string &iname,
270                                          const string &idesc,
271                                          booleanChangeValCallBackFunc cb,
272                                          tunableUse type,
273                                          const bool initialVal);
274       // returns true iff successfully created in the central repository.
275       // outside code can use class tunableBooleanConstantDeclarator to avoid the
276       // need to bother with this routine and the next one...
277    static bool destroyBoolTunableConstant(const string &);
278       // returns true iff successfully destroyed.
279       // Beware of race conditions...best to only call this routine when
280       // completely shutting down paradyn!
281      
282    static bool existsBoolTunableConstant(const string &);
283
284    static tunableBooleanConstant findBoolTunableConstant(const string &);
285    static vector<tunableBooleanConstant> getAllBoolTunableConstants();
286
287    static void setBoolTunableConstant(const string &, bool newValue);
288       // makes change take effect in the central repository.  Will eventually be implemented
289       // to throw and exception if not found.
290
291    // Methods specific to float tunable constants:
292    static unsigned numFloatTunables();
293
294    static bool createFloatTunableConstant(const string &iname,
295                                           const string &idesc,
296                                           floatChangeValCallBackFunc cb,
297                                           tunableUse type,
298                                           const float initialVal,
299                                           float min, float max);
300       // returns true iff successfully created
301       // outside code can use class tunableFloatConstantDeclarator to avoid the
302       // need to bother with this routine and the next two...
303    static bool createFloatTunableConstant(const string &iname,
304                                           const string &idesc,
305                                           floatChangeValCallBackFunc cb,
306                                           tunableUse use,
307                                           const float initialVal,
308                                           isValidFunc ivf);
309       // returns true iff successfully created
310    static bool destroyFloatTunableConstant(const string &);
311       // returns true iff successfully destroyed.
312       // Beware of race conditions...best to only call this routine when
313       // completely shutting down paradyn!
314      
315    static bool existsFloatTunableConstant(const string &);
316
317    static tunableFloatConstant findFloatTunableConstant(const string &);
318    static vector<tunableFloatConstant> getAllFloatTunableConstants();
319
320    static void setFloatTunableConstant(const string &, float newValue);
321 };
322
323 /* **************************************************************
324  * ************************ Declarators *************************
325  * **************************************************************
326  *
327  * Outside code can (and should) use these classes to declare
328  * tunable constants.  This class automatically makes the appropriate
329  * igen calls to create & destroy a tunable constant in the central
330  * registry.
331  *
332  * **************************************************************
333 */
334
335 class tunableBooleanConstantDeclarator {
336  private:
337    string the_name; // needed in the destructor
338
339  public:
340    tunableBooleanConstantDeclarator(const string &iname,
341                                     const string &idesc,
342                                     bool initialValue, 
343                                     booleanChangeValCallBackFunc cb,
344                                     tunableUse type);
345    ~tunableBooleanConstantDeclarator();
346 };
347
348 class tunableFloatConstantDeclarator {
349  private:
350    string the_name;
351
352  public:
353    tunableFloatConstantDeclarator(const string &iname,
354                                   const string &idesc,
355                                   float initialValue,
356                                   float min, float max,
357                                   floatChangeValCallBackFunc cb,
358                                   tunableUse type);
359    tunableFloatConstantDeclarator(const string &iname,
360                                   const string &idesc,
361                                   float initialValue, 
362                                   isValidFunc ivf,
363                                   floatChangeValCallBackFunc cb,
364                                   tunableUse type);
365    ~tunableFloatConstantDeclarator();
366 };
367
368 #endif