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