![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to prcountr.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Synchronet] / sbbs / include / mozilla / nspr|
Return to prcountr.h CVS log | Up to [Synchronet] / sbbs / include / mozilla / nspr |
1.1 root 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___ */
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.