You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

NSPR Reference
Previous     Contents     Next     

Chapter 27   Instrumentation Counters

The chapter describes the NSPR instrumentation counter API. NSPR counters can be dynamically defined, incremented, decremented, set, and deleted under application program control. They are intended for instrumentation, not for operational data. If you need a counter for operational data, use native integral types.

Using Instrumentation Counters
Instrumentation Counter Type
Instrumentation Counter Functions and Macros

Using Instrumentation Counters

NSPR instrumentation counters are 32-bit unsigned integers. On overflow, a counter will wrap. No exception is recognized or reported.

A counter can be dynamically created using a two-level naming convention. A handle is returned when the counter is created. The counter can subsequently be addressed by its handle. An API is provided to get an existing counter's handle given the names with which it was originally created. Similarly, a counter's name can be retrieved given its handle.

The counter naming convention is a two-level hierarchy. The QName is the higher level of the hierarchy; RName is the lower level. RNames can be thought of as existing within a QName. The same RName can exist within multiple QNames. QNames are unique. The NSPR counter is not a near-zero overhead feature. Application designers should be aware of serialization issues when using the Counter API. Creating a counter locks a large asset, potentially causing a stall. This suggest that applications should create counters at component initialization, for example, and not create and destroy them willy-nilly.

Incrementing and adding to counters uses atomic operations. The performance of these operations will vary from platform to platform. On platforms where atomic operations are not supported, the overhead may be substantial.

When you traverse the counter database with the FindNext functions, the instantaneous values of any given counter is that at the moment of extraction. The state of the entire counter database may not be viewed as atomic.

The counter interface may be disabled (No-Op'd) at compile time. When DEBUG is defined at compile time, the counter feature is compiled into NSPR and applications invoking it. When DEBUG is not defined, the counter macros compile to nothing. To force the counter feature to be compiled into an optimized build, define FORCE_NSPR_COUNTERS at compile time for both NSPR and the application intending to use it.

Application designers should use the macro form of the counter methods to minimize performance impact in optimized builds. The macros normally compile to nothing on optimized builds.

Application designers should be aware of the effects of debug and optimized build differences when using results of the counter macros in expressions.

NSPR counters are thread-safe and SMP safe.

Instrumentation Counter Type

PRCounterHandle

A handle to an NSPR counter. 

typedef void *  PRCounterHandle;

This type is an opaque object used to communicate between the application using the counter facility and the counter facility itself. Do not attempt to manipulate a PRCounterHandle object directly.

Instrumentation Counter Functions and Macros

PR_DEFINE_COUNTER
PR_INIT_COUNTER_HANDLE
PR_CreateCounter
PR_DestroyCounter
PR_GetCounterHandleFromName
PR_GetCounterNameFromHandle
PR_IncrementCounter
PR_DecrementCounter
PR_AddToCounter
PR_SubtractFromCounter
PR_GetCounter
PR_SetCounter
PR_FindNextCounterQname
PR_FindNextCounterRname

PR_DEFINE_COUNTER

Defines a PRCounterHandle.


Syntax 
#include <prcountr.h> 


#define PR_DEFINE_COUNTER(name) PRCounterHandle name


Parameters
The function has this parameter: 

name

The name to be assigned to the PRCounterHandle.


Returns
N/A


Description
PR_DEFINE_COUNTER is provided as a macro so that the PRCounterHandle is not created in optimized builds.

PR_INIT_COUNTER_HANDLE

Sets the value of a counter handle.


Syntax 
#include <prcountr.h>


#define PR_INIT_COUNTER_HANDLE(handle,value)\
   (handle) = (PRCounterHandle)(value)


Parameters
The function has these parameters:

handle

The counter handle to be assigned a value.

value

A value to assign to the counter handle. NULL works.


Returns
N/A

PR_CreateCounter

Creates a counter object and returns a handle to that object.


Syntax 
#include <prcountr.h>


#define PR_CREATE_COUNTER(handle,qName,rName,description)\


   (handle) = PR_CreateCounter((qName),(rName),(description))


PR_EXTERN(PRCounterHandle)
   PR_CreateCounter(
      const char *qName,(
      const char *rName,
      const char *description
);


Parameters
The function has these parameters:

qName

The QName to be assigned to the counter.

rName

The RName to be assigned to the counter.

description

Descriptive data about the counter.


Returns
A PRCounterHandle or NULL.

PR_DestroyCounter 

Destroy a counter object.


Syntax 
#include <prcountr.h>


#define PR_DESTROY_COUNTER(handle) PR_DestroyCounter((handle))


PR_EXTERN(void)
   PR_DestroyCounter(
      PRCounterHandle handle
);


Parameters
The function has this parameter:

handle

The PRCounterHandle of the counter to be deleted.


Description
This function removes a counter and unregisters its handle from the counter database.

PR_GetCounterHandleFromName

Retrieves a counter's handle based on a specified QName and RName.


Syntax 
#include <prcountr.h>


#define PR_GET_COUNTER_HANDLE_FROM_NAME(handle,qName,rName)\
   (handle) = PR_GetCounterHandleFromName((qName),(rName))


PR_EXTERN(PRCounterHandle)
   PR_GetCounterHandleFromName( 
   const char *qName, 
   const char *rName 
);


Parameters
The function has these parameters:

qName

The QName of the desired counter.

rName

The RName of the desired counter.


Returns
A PRCounterHandle or NULL


Description
This function retrieves a counter's handle from the counter database, given the name the counter was originally created with.

PR_GetCounterNameFromHandle

Retreives a counter's name, given its handle


Syntax 
#include <prcountr.h>


#define PR_GET_COUNTER_NAME_FROM_HANDLE(handle,qName,rName,description)\
   PR_GetCounterNameFromHandle((handle),(qName),(rName),(description))


PR_EXTERN(void)
   PR_GetCounterNameFromHandle( 
      PRCounterHandle handle, 
      const char **qName,
      const char **rName, 
      const char **description 
);


Parameters
The function has these parameters:

qName

Where to store a pointer to the counter's QName.

rName

Where to store a pointer to the counter's RName.

description

Where to store a pointer to the counter's description.


Returns
Nothing


Description
This function retrieves a counter's QName, RName, and description from the counter database, given the counter's handle.

PR_IncrementCounter

Adds one (1) to the referenced counter.


Syntax 
#include <prcountr.h>


#define PR_INCREMENT_COUNTER(handle) PR_IncrementCounter(handle)


PR_EXTERN(void) 
   PR_IncrementCounter( 
      PRCounterHandle handle
);


Parameters
The function has this parameter:

handle

The PRCounterHandle of the counter to be incremented.


Returns
Nothing.

PR_DecrementCounter

Subtracts one (1) from the referenced counter.


Syntax 
#include <prcountr.h>


#define PR_DECREMENT_COUNTER(handle) PR_DecrementCounter(handle)


PR_EXTERN(void) 
   PR_DecrementCounter(
      PRCounterHandle handle
);


Parameters
The function has this parameter:

handle

The PRCounterHandle of the counter to be decremented.


Returns
Nothing.

PR_AddToCounter

Adds a specified value to the referenced counter.


Syntax 
#include <prcountr.h>


#define PR_ADD_TO_COUNTER(handle,value)\
   PR_AddToCounter((handle),(value))


PR_EXTERN(void)
   PR_AddToCounter(
      PRCounterHandle handle,
      PRUint32 value
);


Parameters
The function has these parameters:

handle

The PRCounterHandle of the counter to which to add the specified value.

value

The quantity to be added to the counter.


Returns
Nothing.

PR_SubtractFromCounter

Subtracts a specified value from the referenced counter.


Syntax 
#include <prcountr.h>  


#define PR_SUBTRACT_FROM_COUNTER(handle,value)\
   PR_SubtractFromCounter((handle),(value))


PR_EXTERN(void) 
   PR_SubtractFromCounter( 
      PRCounterHandle handle,
      PRUint32 value
);


Parameters
The function has these parameters:

handle

The PRCounterHandle of the counter from which to subtract the specified value.

value

The quantity to be subtracted from the counter.


Returns
Nothing.

PR_GetCounter

Retrieves the value of a counter.


Syntax 
#include <prcountr.h>


#define PR_GET_COUNTER(counter,handle)\
   (counter) = PR_GetCounter((handle))


PR_EXTERN(PRUint32)
   PR_GetCounter(
      PRCounterHandle handle
);


Parameters
The function has this parameter:

handle

The PRCounterHandle of the counter to be retrieved.


Returns
The value of the counter referenced by handle.

PR_SetCounter

Sets the value of a counter.


Syntax 
#include <prcountr.h>


#define PR_SET_COUNTER(handle,value) PR_SetCounter((handle),(value))


PR_EXTERN(void) 
   PR_SetCounter(
      PRCounterHandle handle,
      PRUint32 value 
);


Parameters
The function has these parameters:
handle

The PRCounterHandle of the counter whose value is to be set.

value

The value to which to set the counter.


Returns
Nothing.

PR_FindNextCounterQname

Retrieves the next QName counter handle in the counter database.


Syntax 
#include <prcountr.h>


#define PR_FIND_NEXT_COUNTER_QNAME(next,handle)\
   (next) = PR_FindNextCounterQname((handle))


PR_EXTERN(PRCounterHandle) 
   PR_FindNextCounterQname( 
      PRCounterHandle handle
);


Parameters
The function has this parameter:

handle

A PRCounterHandle of the counter before the counter whose QName is to be retrieved, or NULL if you want to get the QName of the first counter.


Returns
A PRCounterHandle or NULL.


Description
This function retrieves the first or next Qname the counter database, depending on the value of handle. When handle is NULL, the function attempts to retrieve the first QName handle in the database. When handle is a previously retrieved QName handle, the function attempts to retrieve the next QName handle.

A PRCounterHandle returned from this function may only be used in another PR_FindNextCounterQname function call; other operations may cause unpredictable results.

PR_FindNextCounterRname

Retrieves the next RName counter handle in the counter database.


Syntax 
#include <prcountr.h>


#define PR_FIND_NEXT_COUNTER_RNAME(next,rhandle,qhandle)\
   (next) = PR_FindNextCounterRname((rhandle),(qhandle))


PR_EXTERN(PRCounterHandle) 
   PR_FindNextCounterRname( 
      PRCounterHandle rhandle,
      PRCounterHandle qhandle
);


Parameters
The function has this parameter:

rhandle

A previously retrieved RName handle..

qhandle

A previously retrieved QName handle, or NULL.


Returns 
A PRCounterHandle or NULL.


Description
This function retrieves the first or next RName handle from the counter database, depending on the value of handle. When handle is NULL, the function attempts to retrieve the first RName handle in the database. When handle is a previously retrieved RName handle, the function attempts to retrieve the next RName handle.

Previous     Contents     Next     

Last Updated May 18, 2001