/gecko_api/include/prcountr.h

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