Line data Source code
1 : /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 : /* This Source Code Form is subject to the terms of the Mozilla Public
3 : * License, v. 2.0. If a copy of the MPL was not distributed with this
4 : * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5 :
6 : #ifndef prcountr_h___
7 : #define prcountr_h___
8 :
9 : /*----------------------------------------------------------------------------
10 : ** prcountr.h -- NSPR Instrumentation counters
11 : **
12 : ** The NSPR Counter Feature provides a means to "count
13 : ** something." Counters can be dynamically defined, incremented,
14 : ** decremented, set, and deleted under application program
15 : ** control.
16 : **
17 : ** The Counter Feature is intended to be used as instrumentation,
18 : ** not as operational data. If you need a counter for operational
19 : ** data, use native integral types.
20 : **
21 : ** Counters are 32bit unsigned intergers. On overflow, a counter
22 : ** will wrap. No exception is recognized or reported.
23 : **
24 : ** A counter can be dynamically created using a two level naming
25 : ** convention. A "handle" is returned when the counter is
26 : ** created. The counter can subsequently be addressed by its
27 : ** handle. An API is provided to get an existing counter's handle
28 : ** given the names with which it was originally created.
29 : ** Similarly, a counter's name can be retrieved given its handle.
30 : **
31 : ** The counter naming convention is a two-level hierarchy. The
32 : ** QName is the higher level of the hierarchy; RName is the
33 : ** lower level. RNames can be thought of as existing within a
34 : ** QName. The same RName can exist within multiple QNames. QNames
35 : ** are unique. The NSPR Counter is not a near-zero overhead
36 : ** feature. Application designers should be aware of
37 : ** serialization issues when using the Counter API. Creating a
38 : ** counter locks a large asset, potentially causing a stall. This
39 : ** suggest that applications should create counters at component
40 : ** initialization, for example, and not create and destroy them
41 : ** willy-nilly. ... You have been warned.
42 : **
43 : ** Incrementing and Adding to counters uses atomic operations.
44 : ** The performance of these operations will vary from platform
45 : ** to platform. On platforms where atomic operations are not
46 : ** supported the overhead may be substantial.
47 : **
48 : ** When traversing the counter database with FindNext functions,
49 : ** the instantaneous values of any given counter is that at the
50 : ** moment of extraction. The state of the entire counter database
51 : ** may not be viewed as atomic.
52 : **
53 : ** The counter interface may be disabled (No-Op'd) at compile
54 : ** time. When DEBUG is defined at compile time, the Counter
55 : ** Feature is compiled into NSPR and applications invoking it.
56 : ** When DEBUG is not defined, the counter macros compile to
57 : ** nothing. To force the Counter Feature to be compiled into an
58 : ** optimized build, define FORCE_NSPR_COUNTERS at compile time
59 : ** for both NSPR and the application intending to use it.
60 : **
61 : ** Application designers should use the macro form of the Counter
62 : ** Feature methods to minimize performance impact in optimized
63 : ** builds. The macros normally compile to nothing on optimized
64 : ** builds.
65 : **
66 : ** Application designers should be aware of the effects of
67 : ** debug and optimized build differences when using result of the
68 : ** Counter Feature macros in expressions.
69 : **
70 : ** The Counter Feature is thread-safe and SMP safe.
71 : **
72 : ** /lth. 09-Jun-1998.
73 : */
74 :
75 : #include "prtypes.h"
76 :
77 : PR_BEGIN_EXTERN_C
78 :
79 : /*
80 : ** Opaque counter handle type.
81 : ** ... don't even think of looking in here.
82 : **
83 : */
84 : typedef void * PRCounterHandle;
85 :
86 : #define PRCOUNTER_NAME_MAX 31
87 : #define PRCOUNTER_DESC_MAX 255
88 :
89 :
90 :
91 : /* -----------------------------------------------------------------------
92 : ** FUNCTION: PR_DEFINE_COUNTER() -- Define a PRCounterHandle
93 : **
94 : ** DESCRIPTION: PR_DEFINE_COUNTER() is used to define a counter
95 : ** handle.
96 : **
97 : */
98 : #define PR_DEFINE_COUNTER(name) PRCounterHandle name
99 :
100 : /* -----------------------------------------------------------------------
101 : ** FUNCTION: PR_INIT_COUNTER_HANDLE() -- Set the value of a PRCounterHandle
102 : **
103 : ** DESCRIPTION:
104 : ** PR_INIT_COUNTER_HANDLE() sets the value of a PRCounterHandle
105 : ** to value.
106 : **
107 : */
108 : #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
109 : #define PR_INIT_COUNTER_HANDLE(handle,value)\
110 : (handle) = (PRCounterHandle)(value)
111 : #else
112 : #define PR_INIT_COUNTER_HANDLE(handle,value)
113 : #endif
114 :
115 : /* -----------------------------------------------------------------------
116 : ** FUNCTION: PR_CreateCounter() -- Create a counter
117 : **
118 : ** DESCRIPTION: PR_CreateCounter() creates a counter object and
119 : ** initializes it to zero.
120 : **
121 : ** The macro form takes as its first argument the name of the
122 : ** PRCounterHandle to receive the handle returned from
123 : ** PR_CreateCounter().
124 : **
125 : ** INPUTS:
126 : ** qName: The QName for the counter object. The maximum length
127 : ** of qName is defined by PRCOUNTER_NAME_MAX
128 : **
129 : ** rName: The RName for the counter object. The maximum length
130 : ** of qName is defined by PRCOUNTER_NAME_MAX
131 : **
132 : ** descrioption: The description of the counter object. The
133 : ** maximum length of description is defined by
134 : ** PRCOUNTER_DESC_MAX.
135 : **
136 : ** OUTPUTS:
137 : **
138 : ** RETURNS:
139 : ** PRCounterHandle.
140 : **
141 : ** RESTRICTIONS:
142 : **
143 : */
144 : #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
145 : #define PR_CREATE_COUNTER(handle,qName,rName,description)\
146 : (handle) = PR_CreateCounter((qName),(rName),(description))
147 : #else
148 : #define PR_CREATE_COUNTER(handle,qName,rName,description)
149 : #endif
150 :
151 : NSPR_API(PRCounterHandle)
152 0 : PR_CreateCounter(
153 : const char *qName,
154 : const char *rName,
155 : const char *description
156 : );
157 :
158 : /* -----------------------------------------------------------------------
159 : ** FUNCTION: PR_DestroyCounter() -- Destroy a counter object.
160 : **
161 : ** DESCRIPTION: PR_DestroyCounter() removes a counter and
162 : ** unregisters its handle from the counter database.
163 : **
164 : ** INPUTS:
165 : ** handle: the PRCounterHandle of the counter to be destroyed.
166 : **
167 : ** OUTPUTS:
168 : ** The counter is destroyed.
169 : **
170 : ** RETURNS: void
171 : **
172 : ** RESTRICTIONS:
173 : **
174 : */
175 : #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
176 : #define PR_DESTROY_COUNTER(handle) PR_DestroyCounter((handle))
177 : #else
178 : #define PR_DESTROY_COUNTER(handle)
179 : #endif
180 :
181 : NSPR_API(void)
182 0 : PR_DestroyCounter(
183 : PRCounterHandle handle
184 : );
185 :
186 :
187 : /* -----------------------------------------------------------------------
188 : ** FUNCTION: PR_GetCounterHandleFromName() -- Retreive a
189 : ** counter's handle give its name.
190 : **
191 : ** DESCRIPTION: PR_GetCounterHandleFromName() retreives a
192 : ** counter's handle from the counter database, given the name
193 : ** the counter was originally created with.
194 : **
195 : ** INPUTS:
196 : ** qName: Counter's original QName.
197 : ** rName: Counter's original RName.
198 : **
199 : ** OUTPUTS:
200 : **
201 : ** RETURNS:
202 : ** PRCounterHandle or PRCounterError.
203 : **
204 : ** RESTRICTIONS:
205 : **
206 : */
207 : #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
208 : #define PR_GET_COUNTER_HANDLE_FROM_NAME(handle,qName,rName)\
209 : (handle) = PR_GetCounterHandleFromName((qName),(rName))
210 : #else
211 : #define PR_GET_COUNTER_HANDLE_FROM_NAME(handle,qName,rName)
212 : #endif
213 :
214 : NSPR_API(PRCounterHandle)
215 0 : PR_GetCounterHandleFromName(
216 : const char *qName,
217 : const char *rName
218 : );
219 :
220 : /* -----------------------------------------------------------------------
221 : ** FUNCTION: PR_GetCounterNameFromHandle() -- Retreive a
222 : ** counter's name, given its handle.
223 : **
224 : ** DESCRIPTION: PR_GetCounterNameFromHandle() retreives a
225 : ** counter's name given its handle.
226 : **
227 : ** INPUTS:
228 : ** qName: Where to store a pointer to qName.
229 : ** rName: Where to store a pointer to rName.
230 : ** description: Where to store a pointer to description.
231 : **
232 : ** OUTPUTS: Pointers to the Counter Feature's copies of the names
233 : ** used when the counters were created.
234 : **
235 : ** RETURNS: void
236 : **
237 : ** RESTRICTIONS:
238 : **
239 : */
240 : #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
241 : #define PR_GET_COUNTER_NAME_FROM_HANDLE(handle,qName,rName,description)\
242 : PR_GetCounterNameFromHandle((handle),(qName),(rName),(description))
243 : #else
244 : #define PR_GET_COUNTER_NAME_FROM_HANDLE(handle,qName,rName,description )
245 : #endif
246 :
247 : NSPR_API(void)
248 0 : PR_GetCounterNameFromHandle(
249 : PRCounterHandle handle,
250 : const char **qName,
251 : const char **rName,
252 : const char **description
253 : );
254 :
255 :
256 : /* -----------------------------------------------------------------------
257 : ** FUNCTION: PR_IncrementCounter() -- Add one to the referenced
258 : ** counter.
259 : **
260 : ** DESCRIPTION: Add one to the referenced counter.
261 : **
262 : ** INPUTS:
263 : ** handle: The PRCounterHandle of the counter to be incremented
264 : **
265 : ** OUTPUTS: The counter is incrementd.
266 : **
267 : ** RETURNS: void
268 : **
269 : ** RESTRICTIONS:
270 : **
271 : */
272 : #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
273 : #define PR_INCREMENT_COUNTER(handle) PR_IncrementCounter(handle)
274 : #else
275 : #define PR_INCREMENT_COUNTER(handle)
276 : #endif
277 :
278 : NSPR_API(void)
279 0 : PR_IncrementCounter(
280 : PRCounterHandle handle
281 : );
282 :
283 :
284 : /* -----------------------------------------------------------------------
285 : ** FUNCTION: PR_DecrementCounter() -- Subtract one from the
286 : ** referenced counter
287 : **
288 : ** DESCRIPTION: Subtract one from the referenced counter.
289 : **
290 : ** INPUTS:
291 : ** handle: The PRCounterHandle of the coutner to be
292 : ** decremented.
293 : **
294 : ** OUTPUTS: the counter is decremented.
295 : **
296 : ** RETURNS: void
297 : **
298 : ** RESTRICTIONS:
299 : **
300 : */
301 : #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
302 : #define PR_DECREMENT_COUNTER(handle) PR_DecrementCounter(handle)
303 : #else
304 : #define PR_DECREMENT_COUNTER(handle)
305 : #endif
306 :
307 : NSPR_API(void)
308 0 : PR_DecrementCounter(
309 : PRCounterHandle handle
310 : );
311 :
312 : /* -----------------------------------------------------------------------
313 : ** FUNCTION: PR_AddToCounter() -- Add a value to a counter.
314 : **
315 : ** DESCRIPTION: Add value to the counter referenced by handle.
316 : **
317 : ** INPUTS:
318 : ** handle: the PRCounterHandle of the counter to be added to.
319 : **
320 : ** value: the value to be added to the counter.
321 : **
322 : ** OUTPUTS: new value for counter.
323 : **
324 : ** RETURNS: void
325 : **
326 : ** RESTRICTIONS:
327 : **
328 : */
329 : #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
330 : #define PR_ADD_TO_COUNTER(handle,value)\
331 : PR_AddToCounter((handle),(value))
332 : #else
333 : #define PR_ADD_TO_COUNTER(handle,value)
334 : #endif
335 :
336 : NSPR_API(void)
337 0 : PR_AddToCounter(
338 : PRCounterHandle handle,
339 : PRUint32 value
340 : );
341 :
342 :
343 : /* -----------------------------------------------------------------------
344 : ** FUNCTION: PR_SubtractFromCounter() -- A value is subtracted
345 : ** from a counter.
346 : **
347 : ** DESCRIPTION:
348 : ** Subtract a value from a counter.
349 : **
350 : ** INPUTS:
351 : ** handle: the PRCounterHandle of the counter to be subtracted
352 : ** from.
353 : **
354 : ** value: the value to be subtracted from the counter.
355 : **
356 : ** OUTPUTS: new value for counter
357 : **
358 : ** RETURNS: void
359 : **
360 : ** RESTRICTIONS:
361 : **
362 : */
363 : #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
364 : #define PR_SUBTRACT_FROM_COUNTER(handle,value)\
365 : PR_SubtractFromCounter((handle),(value))
366 : #else
367 : #define PR_SUBTRACT_FROM_COUNTER(handle,value)
368 : #endif
369 :
370 : NSPR_API(void)
371 0 : PR_SubtractFromCounter(
372 : PRCounterHandle handle,
373 : PRUint32 value
374 : );
375 :
376 :
377 : /* -----------------------------------------------------------------------
378 : ** FUNCTION: PR_GetCounter() -- Retreive the value of a counter
379 : **
380 : ** DESCRIPTION:
381 : ** Retreive the value of a counter.
382 : **
383 : ** INPUTS:
384 : ** handle: the PR_CounterHandle of the counter to be retreived
385 : **
386 : ** OUTPUTS:
387 : **
388 : ** RETURNS: The value of the referenced counter
389 : **
390 : ** RESTRICTIONS:
391 : **
392 : */
393 : #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
394 : #define PR_GET_COUNTER(counter,handle)\
395 : (counter) = PR_GetCounter((handle))
396 : #else
397 : #define PR_GET_COUNTER(counter,handle) 0
398 : #endif
399 :
400 : NSPR_API(PRUint32)
401 0 : PR_GetCounter(
402 : PRCounterHandle handle
403 : );
404 :
405 : /* -----------------------------------------------------------------------
406 : ** FUNCTION: PR_SetCounter() -- Replace the content of counter
407 : ** with value.
408 : **
409 : ** DESCRIPTION: The contents of the referenced counter are
410 : ** replaced by value.
411 : **
412 : ** INPUTS:
413 : ** handle: the PRCounterHandle of the counter whose contents
414 : ** are to be replaced.
415 : **
416 : ** value: the new value of the counter.
417 : **
418 : ** OUTPUTS:
419 : **
420 : ** RETURNS: void
421 : **
422 : ** RESTRICTIONS:
423 : **
424 : */
425 : #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
426 : #define PR_SET_COUNTER(handle,value) PR_SetCounter((handle),(value))
427 : #else
428 : #define PR_SET_COUNTER(handle,value)
429 : #endif
430 :
431 : NSPR_API(void)
432 0 : PR_SetCounter(
433 : PRCounterHandle handle,
434 : PRUint32 value
435 : );
436 :
437 :
438 : /* -----------------------------------------------------------------------
439 : ** FUNCTION: PR_FindNextCounterQname() -- Retreive the next QName counter
440 : ** handle iterator
441 : **
442 : ** DESCRIPTION:
443 : ** PR_FindNextCounterQname() retreives the first or next Qname
444 : ** the counter data base, depending on the value of handle. When
445 : ** handle is NULL, the function attempts to retreive the first
446 : ** QName handle in the database. When handle is a handle previosly
447 : ** retreived QName handle, then the function attempts to retreive
448 : ** the next QName handle.
449 : **
450 : ** INPUTS:
451 : ** handle: PRCounterHandle or NULL.
452 : **
453 : ** OUTPUTS: returned
454 : **
455 : ** RETURNS: PRCounterHandle or NULL when no more QName counter
456 : ** handles are present.
457 : **
458 : ** RESTRICTIONS:
459 : ** A concurrent PR_CreateCounter() or PR_DestroyCounter() may
460 : ** cause unpredictable results.
461 : **
462 : ** A PRCounterHandle returned from this function may only be used
463 : ** in another PR_FindNextCounterQname() function call; other
464 : ** operations may cause unpredictable results.
465 : **
466 : */
467 : #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
468 : #define PR_FIND_NEXT_COUNTER_QNAME(next,handle)\
469 : (next) = PR_FindNextCounterQname((handle))
470 : #else
471 : #define PR_FIND_NEXT_COUNTER_QNAME(next,handle) NULL
472 : #endif
473 :
474 : NSPR_API(PRCounterHandle)
475 0 : PR_FindNextCounterQname(
476 : PRCounterHandle handle
477 : );
478 :
479 : /* -----------------------------------------------------------------------
480 : ** FUNCTION: PR_FindNextCounterRname() -- Retreive the next RName counter
481 : ** handle iterator
482 : **
483 : ** DESCRIPTION:
484 : ** PR_FindNextCounterRname() retreives the first or next RNname
485 : ** handle from the counter data base, depending on the
486 : ** value of handle. When handle is NULL, the function attempts to
487 : ** retreive the first RName handle in the database. When handle is
488 : ** a handle previosly retreived RName handle, then the function
489 : ** attempts to retreive the next RName handle.
490 : **
491 : ** INPUTS:
492 : ** handle: PRCounterHandle or NULL.
493 : ** qhandle: PRCounterHandle of a previously aquired via
494 : ** PR_FIND_NEXT_QNAME_HANDLE()
495 : **
496 : ** OUTPUTS: returned
497 : **
498 : ** RETURNS: PRCounterHandle or NULL when no more RName counter
499 : ** handles are present.
500 : **
501 : ** RESTRICTIONS:
502 : ** A concurrent PR_CreateCounter() or PR_DestroyCounter() may
503 : ** cause unpredictable results.
504 : **
505 : ** A PRCounterHandle returned from this function may only be used
506 : ** in another PR_FindNextCounterRname() function call; other
507 : ** operations may cause unpredictable results.
508 : **
509 : */
510 : #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
511 : #define PR_FIND_NEXT_COUNTER_RNAME(next,rhandle,qhandle)\
512 : (next) = PR_FindNextCounterRname((rhandle),(qhandle))
513 : #else
514 : #define PR_FIND_NEXT_COUNTER_RNAME(next,rhandle,qhandle)
515 : #endif
516 :
517 : NSPR_API(PRCounterHandle)
518 0 : PR_FindNextCounterRname(
519 : PRCounterHandle rhandle,
520 : PRCounterHandle qhandle
521 : );
522 :
523 : PR_END_EXTERN_C
524 :
525 : #endif /* prcountr_h___ */
|
