558 lines
16 KiB
C
558 lines
16 KiB
C
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
|
|
/* ***** BEGIN LICENSE BLOCK *****
|
|
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
|
|
*
|
|
* The contents of this file are subject to the Mozilla Public License Version
|
|
* 1.1 (the "License"); you may not use this file except in compliance with
|
|
* the License. You may obtain a copy of the License at
|
|
* http://www.mozilla.org/MPL/
|
|
*
|
|
* Software distributed under the License is distributed on an "AS IS" basis,
|
|
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
|
|
* for the specific language governing rights and limitations under the
|
|
* License.
|
|
*
|
|
* The Original Code is the Netscape Portable Runtime (NSPR).
|
|
*
|
|
* The Initial Developer of the Original Code is
|
|
* Netscape Communications Corporation.
|
|
* Portions created by the Initial Developer are Copyright (C) 1998-2000
|
|
* the Initial Developer. All Rights Reserved.
|
|
*
|
|
* Contributor(s):
|
|
*
|
|
* Alternatively, the contents of this file may be used under the terms of
|
|
* either the GNU General Public License Version 2 or later (the "GPL"), or
|
|
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
|
|
* in which case the provisions of the GPL or the LGPL are applicable instead
|
|
* of those above. If you wish to allow use of your version of this file only
|
|
* under the terms of either the GPL or the LGPL, and not to allow others to
|
|
* use your version of this file under the terms of the MPL, indicate your
|
|
* decision by deleting the provisions above and replace them with the notice
|
|
* and other provisions required by the GPL or the LGPL. If you do not delete
|
|
* the provisions above, a recipient may use your version of this file under
|
|
* the terms of any one of the MPL, the GPL or the LGPL.
|
|
*
|
|
* ***** END LICENSE BLOCK ***** */
|
|
|
|
#ifndef prcountr_h___
|
|
#define prcountr_h___
|
|
|
|
/*----------------------------------------------------------------------------
|
|
** prcountr.h -- NSPR Instrumentation counters
|
|
**
|
|
** The NSPR Counter Feature provides a means to "count
|
|
** something." Counters can be dynamically defined, incremented,
|
|
** decremented, set, and deleted under application program
|
|
** control.
|
|
**
|
|
** The Counter Feature is intended to be used as instrumentation,
|
|
** not as operational data. If you need a counter for operational
|
|
** data, use native integral types.
|
|
**
|
|
** Counters are 32bit unsigned intergers. 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. ... You have been warned.
|
|
**
|
|
** 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 traversing the counter database with 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
|
|
** Feature 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 result of the
|
|
** Counter Feature macros in expressions.
|
|
**
|
|
** The Counter Feature is thread-safe and SMP safe.
|
|
**
|
|
** /lth. 09-Jun-1998.
|
|
*/
|
|
|
|
#include "prtypes.h"
|
|
|
|
PR_BEGIN_EXTERN_C
|
|
|
|
/*
|
|
** Opaque counter handle type.
|
|
** ... don't even think of looking in here.
|
|
**
|
|
*/
|
|
typedef void * PRCounterHandle;
|
|
|
|
#define PRCOUNTER_NAME_MAX 31
|
|
#define PRCOUNTER_DESC_MAX 255
|
|
|
|
|
|
|
|
/* -----------------------------------------------------------------------
|
|
** FUNCTION: PR_DEFINE_COUNTER() -- Define a PRCounterHandle
|
|
**
|
|
** DESCRIPTION: PR_DEFINE_COUNTER() is used to define a counter
|
|
** handle.
|
|
**
|
|
*/
|
|
#define PR_DEFINE_COUNTER(name) PRCounterHandle name
|
|
|
|
/* -----------------------------------------------------------------------
|
|
** FUNCTION: PR_INIT_COUNTER_HANDLE() -- Set the value of a PRCounterHandle
|
|
**
|
|
** DESCRIPTION:
|
|
** PR_INIT_COUNTER_HANDLE() sets the value of a PRCounterHandle
|
|
** to value.
|
|
**
|
|
*/
|
|
#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
|
|
#define PR_INIT_COUNTER_HANDLE(handle,value)\
|
|
(handle) = (PRCounterHandle)(value)
|
|
#else
|
|
#define PR_INIT_COUNTER_HANDLE(handle,value)
|
|
#endif
|
|
|
|
/* -----------------------------------------------------------------------
|
|
** FUNCTION: PR_CreateCounter() -- Create a counter
|
|
**
|
|
** DESCRIPTION: PR_CreateCounter() creates a counter object and
|
|
** initializes it to zero.
|
|
**
|
|
** The macro form takes as its first argument the name of the
|
|
** PRCounterHandle to receive the handle returned from
|
|
** PR_CreateCounter().
|
|
**
|
|
** INPUTS:
|
|
** qName: The QName for the counter object. The maximum length
|
|
** of qName is defined by PRCOUNTER_NAME_MAX
|
|
**
|
|
** rName: The RName for the counter object. The maximum length
|
|
** of qName is defined by PRCOUNTER_NAME_MAX
|
|
**
|
|
** descrioption: The description of the counter object. The
|
|
** maximum length of description is defined by
|
|
** PRCOUNTER_DESC_MAX.
|
|
**
|
|
** OUTPUTS:
|
|
**
|
|
** RETURNS:
|
|
** PRCounterHandle.
|
|
**
|
|
** RESTRICTIONS:
|
|
**
|
|
*/
|
|
#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
|
|
#define PR_CREATE_COUNTER(handle,qName,rName,description)\
|
|
(handle) = PR_CreateCounter((qName),(rName),(description))
|
|
#else
|
|
#define PR_CREATE_COUNTER(handle,qName,rName,description)
|
|
#endif
|
|
|
|
NSPR_API(PRCounterHandle)
|
|
PR_CreateCounter(
|
|
const char *qName,
|
|
const char *rName,
|
|
const char *description
|
|
);
|
|
|
|
/* -----------------------------------------------------------------------
|
|
** FUNCTION: PR_DestroyCounter() -- Destroy a counter object.
|
|
**
|
|
** DESCRIPTION: PR_DestroyCounter() removes a counter and
|
|
** unregisters its handle from the counter database.
|
|
**
|
|
** INPUTS:
|
|
** handle: the PRCounterHandle of the counter to be destroyed.
|
|
**
|
|
** OUTPUTS:
|
|
** The counter is destroyed.
|
|
**
|
|
** RETURNS: void
|
|
**
|
|
** RESTRICTIONS:
|
|
**
|
|
*/
|
|
#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
|
|
#define PR_DESTROY_COUNTER(handle) PR_DestroyCounter((handle))
|
|
#else
|
|
#define PR_DESTROY_COUNTER(handle)
|
|
#endif
|
|
|
|
NSPR_API(void)
|
|
PR_DestroyCounter(
|
|
PRCounterHandle handle
|
|
);
|
|
|
|
|
|
/* -----------------------------------------------------------------------
|
|
** FUNCTION: PR_GetCounterHandleFromName() -- Retreive a
|
|
** counter's handle give its name.
|
|
**
|
|
** DESCRIPTION: PR_GetCounterHandleFromName() retreives a
|
|
** counter's handle from the counter database, given the name
|
|
** the counter was originally created with.
|
|
**
|
|
** INPUTS:
|
|
** qName: Counter's original QName.
|
|
** rName: Counter's original RName.
|
|
**
|
|
** OUTPUTS:
|
|
**
|
|
** RETURNS:
|
|
** PRCounterHandle or PRCounterError.
|
|
**
|
|
** RESTRICTIONS:
|
|
**
|
|
*/
|
|
#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
|
|
#define PR_GET_COUNTER_HANDLE_FROM_NAME(handle,qName,rName)\
|
|
(handle) = PR_GetCounterHandleFromName((qName),(rName))
|
|
#else
|
|
#define PR_GET_COUNTER_HANDLE_FROM_NAME(handle,qName,rName)
|
|
#endif
|
|
|
|
NSPR_API(PRCounterHandle)
|
|
PR_GetCounterHandleFromName(
|
|
const char *qName,
|
|
const char *rName
|
|
);
|
|
|
|
/* -----------------------------------------------------------------------
|
|
** FUNCTION: PR_GetCounterNameFromHandle() -- Retreive a
|
|
** counter's name, given its handle.
|
|
**
|
|
** DESCRIPTION: PR_GetCounterNameFromHandle() retreives a
|
|
** counter's name given its handle.
|
|
**
|
|
** INPUTS:
|
|
** qName: Where to store a pointer to qName.
|
|
** rName: Where to store a pointer to rName.
|
|
** description: Where to store a pointer to description.
|
|
**
|
|
** OUTPUTS: Pointers to the Counter Feature's copies of the names
|
|
** used when the counters were created.
|
|
**
|
|
** RETURNS: void
|
|
**
|
|
** RESTRICTIONS:
|
|
**
|
|
*/
|
|
#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
|
|
#define PR_GET_COUNTER_NAME_FROM_HANDLE(handle,qName,rName,description)\
|
|
PR_GetCounterNameFromHandle((handle),(qName),(rName),(description))
|
|
#else
|
|
#define PR_GET_COUNTER_NAME_FROM_HANDLE(handle,qName,rName,description )
|
|
#endif
|
|
|
|
NSPR_API(void)
|
|
PR_GetCounterNameFromHandle(
|
|
PRCounterHandle handle,
|
|
const char **qName,
|
|
const char **rName,
|
|
const char **description
|
|
);
|
|
|
|
|
|
/* -----------------------------------------------------------------------
|
|
** FUNCTION: PR_IncrementCounter() -- Add one to the referenced
|
|
** counter.
|
|
**
|
|
** DESCRIPTION: Add one to the referenced counter.
|
|
**
|
|
** INPUTS:
|
|
** handle: The PRCounterHandle of the counter to be incremented
|
|
**
|
|
** OUTPUTS: The counter is incrementd.
|
|
**
|
|
** RETURNS: void
|
|
**
|
|
** RESTRICTIONS:
|
|
**
|
|
*/
|
|
#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
|
|
#define PR_INCREMENT_COUNTER(handle) PR_IncrementCounter(handle)
|
|
#else
|
|
#define PR_INCREMENT_COUNTER(handle)
|
|
#endif
|
|
|
|
NSPR_API(void)
|
|
PR_IncrementCounter(
|
|
PRCounterHandle handle
|
|
);
|
|
|
|
|
|
/* -----------------------------------------------------------------------
|
|
** FUNCTION: PR_DecrementCounter() -- Subtract one from the
|
|
** referenced counter
|
|
**
|
|
** DESCRIPTION: Subtract one from the referenced counter.
|
|
**
|
|
** INPUTS:
|
|
** handle: The PRCounterHandle of the coutner to be
|
|
** decremented.
|
|
**
|
|
** OUTPUTS: the counter is decremented.
|
|
**
|
|
** RETURNS: void
|
|
**
|
|
** RESTRICTIONS:
|
|
**
|
|
*/
|
|
#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
|
|
#define PR_DECREMENT_COUNTER(handle) PR_DecrementCounter(handle)
|
|
#else
|
|
#define PR_DECREMENT_COUNTER(handle)
|
|
#endif
|
|
|
|
NSPR_API(void)
|
|
PR_DecrementCounter(
|
|
PRCounterHandle handle
|
|
);
|
|
|
|
/* -----------------------------------------------------------------------
|
|
** FUNCTION: PR_AddToCounter() -- Add a value to a counter.
|
|
**
|
|
** DESCRIPTION: Add value to the counter referenced by handle.
|
|
**
|
|
** INPUTS:
|
|
** handle: the PRCounterHandle of the counter to be added to.
|
|
**
|
|
** value: the value to be added to the counter.
|
|
**
|
|
** OUTPUTS: new value for counter.
|
|
**
|
|
** RETURNS: void
|
|
**
|
|
** RESTRICTIONS:
|
|
**
|
|
*/
|
|
#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
|
|
#define PR_ADD_TO_COUNTER(handle,value)\
|
|
PR_AddToCounter((handle),(value))
|
|
#else
|
|
#define PR_ADD_TO_COUNTER(handle,value)
|
|
#endif
|
|
|
|
NSPR_API(void)
|
|
PR_AddToCounter(
|
|
PRCounterHandle handle,
|
|
PRUint32 value
|
|
);
|
|
|
|
|
|
/* -----------------------------------------------------------------------
|
|
** FUNCTION: PR_SubtractFromCounter() -- A value is subtracted
|
|
** from a counter.
|
|
**
|
|
** DESCRIPTION:
|
|
** Subtract a value from a counter.
|
|
**
|
|
** INPUTS:
|
|
** handle: the PRCounterHandle of the counter to be subtracted
|
|
** from.
|
|
**
|
|
** value: the value to be subtracted from the counter.
|
|
**
|
|
** OUTPUTS: new value for counter
|
|
**
|
|
** RETURNS: void
|
|
**
|
|
** RESTRICTIONS:
|
|
**
|
|
*/
|
|
#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
|
|
#define PR_SUBTRACT_FROM_COUNTER(handle,value)\
|
|
PR_SubtractFromCounter((handle),(value))
|
|
#else
|
|
#define PR_SUBTRACT_FROM_COUNTER(handle,value)
|
|
#endif
|
|
|
|
NSPR_API(void)
|
|
PR_SubtractFromCounter(
|
|
PRCounterHandle handle,
|
|
PRUint32 value
|
|
);
|
|
|
|
|
|
/* -----------------------------------------------------------------------
|
|
** FUNCTION: PR_GetCounter() -- Retreive the value of a counter
|
|
**
|
|
** DESCRIPTION:
|
|
** Retreive the value of a counter.
|
|
**
|
|
** INPUTS:
|
|
** handle: the PR_CounterHandle of the counter to be retreived
|
|
**
|
|
** OUTPUTS:
|
|
**
|
|
** RETURNS: The value of the referenced counter
|
|
**
|
|
** RESTRICTIONS:
|
|
**
|
|
*/
|
|
#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
|
|
#define PR_GET_COUNTER(counter,handle)\
|
|
(counter) = PR_GetCounter((handle))
|
|
#else
|
|
#define PR_GET_COUNTER(counter,handle) 0
|
|
#endif
|
|
|
|
NSPR_API(PRUint32)
|
|
PR_GetCounter(
|
|
PRCounterHandle handle
|
|
);
|
|
|
|
/* -----------------------------------------------------------------------
|
|
** FUNCTION: PR_SetCounter() -- Replace the content of counter
|
|
** with value.
|
|
**
|
|
** DESCRIPTION: The contents of the referenced counter are
|
|
** replaced by value.
|
|
**
|
|
** INPUTS:
|
|
** handle: the PRCounterHandle of the counter whose contents
|
|
** are to be replaced.
|
|
**
|
|
** value: the new value of the counter.
|
|
**
|
|
** OUTPUTS:
|
|
**
|
|
** RETURNS: void
|
|
**
|
|
** RESTRICTIONS:
|
|
**
|
|
*/
|
|
#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
|
|
#define PR_SET_COUNTER(handle,value) PR_SetCounter((handle),(value))
|
|
#else
|
|
#define PR_SET_COUNTER(handle,value)
|
|
#endif
|
|
|
|
NSPR_API(void)
|
|
PR_SetCounter(
|
|
PRCounterHandle handle,
|
|
PRUint32 value
|
|
);
|
|
|
|
|
|
/* -----------------------------------------------------------------------
|
|
** FUNCTION: PR_FindNextCounterQname() -- Retreive the next QName counter
|
|
** handle iterator
|
|
**
|
|
** DESCRIPTION:
|
|
** PR_FindNextCounterQname() retreives the first or next Qname
|
|
** the counter data base, depending on the value of handle. When
|
|
** handle is NULL, the function attempts to retreive the first
|
|
** QName handle in the database. When handle is a handle previosly
|
|
** retreived QName handle, then the function attempts to retreive
|
|
** the next QName handle.
|
|
**
|
|
** INPUTS:
|
|
** handle: PRCounterHandle or NULL.
|
|
**
|
|
** OUTPUTS: returned
|
|
**
|
|
** RETURNS: PRCounterHandle or NULL when no more QName counter
|
|
** handles are present.
|
|
**
|
|
** RESTRICTIONS:
|
|
** A concurrent PR_CreateCounter() or PR_DestroyCounter() may
|
|
** cause unpredictable results.
|
|
**
|
|
** A PRCounterHandle returned from this function may only be used
|
|
** in another PR_FindNextCounterQname() function call; other
|
|
** operations may cause unpredictable results.
|
|
**
|
|
*/
|
|
#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
|
|
#define PR_FIND_NEXT_COUNTER_QNAME(next,handle)\
|
|
(next) = PR_FindNextCounterQname((handle))
|
|
#else
|
|
#define PR_FIND_NEXT_COUNTER_QNAME(next,handle) NULL
|
|
#endif
|
|
|
|
NSPR_API(PRCounterHandle)
|
|
PR_FindNextCounterQname(
|
|
PRCounterHandle handle
|
|
);
|
|
|
|
/* -----------------------------------------------------------------------
|
|
** FUNCTION: PR_FindNextCounterRname() -- Retreive the next RName counter
|
|
** handle iterator
|
|
**
|
|
** DESCRIPTION:
|
|
** PR_FindNextCounterRname() retreives the first or next RNname
|
|
** handle from the counter data base, depending on the
|
|
** value of handle. When handle is NULL, the function attempts to
|
|
** retreive the first RName handle in the database. When handle is
|
|
** a handle previosly retreived RName handle, then the function
|
|
** attempts to retreive the next RName handle.
|
|
**
|
|
** INPUTS:
|
|
** handle: PRCounterHandle or NULL.
|
|
** qhandle: PRCounterHandle of a previously aquired via
|
|
** PR_FIND_NEXT_QNAME_HANDLE()
|
|
**
|
|
** OUTPUTS: returned
|
|
**
|
|
** RETURNS: PRCounterHandle or NULL when no more RName counter
|
|
** handles are present.
|
|
**
|
|
** RESTRICTIONS:
|
|
** A concurrent PR_CreateCounter() or PR_DestroyCounter() may
|
|
** cause unpredictable results.
|
|
**
|
|
** A PRCounterHandle returned from this function may only be used
|
|
** in another PR_FindNextCounterRname() function call; other
|
|
** operations may cause unpredictable results.
|
|
**
|
|
*/
|
|
#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
|
|
#define PR_FIND_NEXT_COUNTER_RNAME(next,rhandle,qhandle)\
|
|
(next) = PR_FindNextCounterRname((rhandle),(qhandle))
|
|
#else
|
|
#define PR_FIND_NEXT_COUNTER_RNAME(next,rhandle,qhandle)
|
|
#endif
|
|
|
|
NSPR_API(PRCounterHandle)
|
|
PR_FindNextCounterRname(
|
|
PRCounterHandle rhandle,
|
|
PRCounterHandle qhandle
|
|
);
|
|
|
|
PR_END_EXTERN_C
|
|
|
|
#endif /* prcountr_h___ */
|