NSPR Reference: Chapter 27 Instrumentation Counters
Description: The Sun-Netscape Alliance, a strategic alliance formed by America Online and Sun Microsystems, Inc., is delivering iPlanet e-commerce software and enterprise solutions that enable companies to compete successfully in the Net Economy
Keywords: electronic commerce, ecommerce, ebusiness, e-business, e-commerce, enterprise software, net economy, Netscape, Sun Microsystems, Sun-Netscape Alliance, iPlanet, internet software

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