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
106PR_BEGIN_EXTERN_C
107
108/*
109** Opaque counter handle type.
110** ... don't even think of looking in here.
111**
112*/
113typedef 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
180NSPR_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
210NSPR_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
243NSPR_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
276NSPR_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
307NSPR_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
336NSPR_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
365NSPR_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
399NSPR_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
429NSPR_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
460NSPR_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
503NSPR_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
546NSPR_API(PRCounterHandle)
547	PR_FindNextCounterRname(
548        PRCounterHandle rhandle,
549        PRCounterHandle qhandle
550);
551
552PR_END_EXTERN_C
553
554#endif /* prcountr_h___ */
555