nsprpub/pr/include/prcountr.h@44a2da4a2ab2
nsprpub/pr/include/prcountr.h
Fri, 16 Jan 2015 04:50:19 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Fri, 16 Jan 2015 04:50:19 +0100
- branch
- TOR_BUG_9701
- changeset 13
- 44a2da4a2ab2
- permissions
- -rw-r--r--
Replace accessor implementation with direct member state manipulation, by
request https://trac.torproject.org/projects/tor/ticket/9701#comment:32
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/. */
6 #ifndef prcountr_h___
7 #define prcountr_h___
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 */
75 #include "prtypes.h"
77 PR_BEGIN_EXTERN_C
79 /*
80 ** Opaque counter handle type.
81 ** ... don't even think of looking in here.
82 **
83 */
84 typedef void * PRCounterHandle;
86 #define PRCOUNTER_NAME_MAX 31
87 #define PRCOUNTER_DESC_MAX 255
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
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
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
151 NSPR_API(PRCounterHandle)
152 PR_CreateCounter(
153 const char *qName,
154 const char *rName,
155 const char *description
156 );
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
181 NSPR_API(void)
182 PR_DestroyCounter(
183 PRCounterHandle handle
184 );
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
214 NSPR_API(PRCounterHandle)
215 PR_GetCounterHandleFromName(
216 const char *qName,
217 const char *rName
218 );
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
247 NSPR_API(void)
248 PR_GetCounterNameFromHandle(
249 PRCounterHandle handle,
250 const char **qName,
251 const char **rName,
252 const char **description
253 );
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
278 NSPR_API(void)
279 PR_IncrementCounter(
280 PRCounterHandle handle
281 );
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
307 NSPR_API(void)
308 PR_DecrementCounter(
309 PRCounterHandle handle
310 );
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
336 NSPR_API(void)
337 PR_AddToCounter(
338 PRCounterHandle handle,
339 PRUint32 value
340 );
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
370 NSPR_API(void)
371 PR_SubtractFromCounter(
372 PRCounterHandle handle,
373 PRUint32 value
374 );
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
400 NSPR_API(PRUint32)
401 PR_GetCounter(
402 PRCounterHandle handle
403 );
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
431 NSPR_API(void)
432 PR_SetCounter(
433 PRCounterHandle handle,
434 PRUint32 value
435 );
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
474 NSPR_API(PRCounterHandle)
475 PR_FindNextCounterQname(
476 PRCounterHandle handle
477 );
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
517 NSPR_API(PRCounterHandle)
518 PR_FindNextCounterRname(
519 PRCounterHandle rhandle,
520 PRCounterHandle qhandle
521 );
523 PR_END_EXTERN_C
525 #endif /* prcountr_h___ */
