prcountr.h

Netscape NSPR库源码

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* 
 * 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 Netscape are 
 * Copyright (C) 1998-2000 Netscape Communications Corporation.  All
 * Rights Reserved.
 * 
 * Contributor(s):
 * 
 * Alternatively, the contents of this file may be used under the
 * terms of the GNU General Public License Version 2 or later (the
 * "GPL"), in which case the provisions of the GPL are applicable 
 * instead of those above.  If you wish to allow use of your 
 * version of this file only under the terms of the GPL and not to
 * allow others to use your version of this file under the MPL,
 * indicate your decision by deleting the provisions above and
 * replace them with the notice and other provisions required by
 * the GPL.  If you do not delete the provisions above, a recipient
 * may use your version of this file under either the MPL or the
 * GPL.
 */

#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


#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)

/* -----------------------------------------------------------------------
** 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.
** 
*/
#define PR_INIT_COUNTER_HANDLE(handle,value)\
    (handle) = (PRCounterHandle)(value)

/* -----------------------------------------------------------------------
** 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:
** 
*/
#define PR_CREATE_COUNTER(handle,qName,rName,description)\
   (handle) = PR_CreateCounter((qName),(rName),(description))

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:
** 
*/
#define PR_DESTROY_COUNTER(handle) PR_DestroyCounter((handle))

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:
** 
*/
#define PR_GET_COUNTER_HANDLE_FROM_NAME(handle,qName,rName)\
    (handle) = PR_GetCounterHandleFromName((qName),(rName))

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:
** 
*/
#define PR_GET_COUNTER_NAME_FROM_HANDLE(handle,qName,rName,description)\
    PR_GetCounterNameFromHandle((handle),(qName),(rName),(description))

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