prcountr.h
上传用户:goldcmy89
上传日期:2017-12-03
资源大小:2246k
文件大小:16k
- /* -*- 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___ */