Back to index

lightning-sunbird  0.9+nobinonly
prcountr.h
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is the Netscape Portable Runtime (NSPR).
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998-2000
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #ifndef prcountr_h___
00039 #define prcountr_h___
00040 
00041 /*----------------------------------------------------------------------------
00042 ** prcountr.h -- NSPR Instrumentation counters
00043 **
00044 ** The NSPR Counter Feature provides a means to "count
00045 ** something." Counters can be dynamically defined, incremented,
00046 ** decremented, set, and deleted under application program
00047 ** control.
00048 **                                                                                                                                 
00049 ** The Counter Feature is intended to be used as instrumentation,                  
00050 ** not as operational data. If you need a counter for operational                  
00051 ** data, use native integral types.                                                
00052 **                                                                                                                                 
00053 ** Counters are 32bit unsigned intergers. On overflow, a counter                   
00054 ** will wrap. No exception is recognized or reported.                              
00055 **                                                                                 
00056 ** A counter can be dynamically created using a two level naming
00057 ** convention. A "handle" is returned when the counter is
00058 ** created. The counter can subsequently be addressed by its
00059 ** handle. An API is provided to get an existing counter's handle
00060 ** given the names with  which it was originally created. 
00061 ** Similarly, a counter's name can be retrieved given its handle.
00062 ** 
00063 ** The counter naming convention is a two-level hierarchy. The
00064 ** QName is the higher level of the hierarchy; RName is the
00065 ** lower level. RNames can be thought of as existing within a
00066 ** QName. The same RName can exist within multiple QNames. QNames
00067 ** are unique. The NSPR Counter is not a near-zero overhead
00068 ** feature. Application designers should be aware of 
00069 ** serialization issues when using the Counter API. Creating a
00070 ** counter locks a large asset, potentially causing a stall. This
00071 ** suggest that applications should create counters at component
00072 ** initialization, for example, and not create and destroy them
00073 ** willy-nilly. ... You have been warned.
00074 ** 
00075 ** Incrementing and Adding to counters uses atomic operations.
00076 ** The performance of these operations will vary from platform
00077 ** to platform. On platforms where atomic operations are not
00078 ** supported the overhead may be substantial.
00079 ** 
00080 ** When traversing the counter database with FindNext functions,
00081 ** the instantaneous values of any given counter is that at the
00082 ** moment of extraction. The state of the entire counter database
00083 ** may not be viewed as atomic.
00084 ** 
00085 ** The counter interface may be disabled (No-Op'd) at compile
00086 ** time. When DEBUG is defined at compile time, the Counter
00087 ** Feature is compiled into NSPR and applications invoking it.
00088 ** When DEBUG is not defined, the counter macros compile to
00089 ** nothing. To force the Counter Feature to be compiled into an
00090 ** optimized build, define FORCE_NSPR_COUNTERS at compile time
00091 ** for both NSPR and the application intending to use it.
00092 ** 
00093 ** Application designers should use the macro form of the Counter
00094 ** Feature methods to minimize performance impact in optimized
00095 ** builds. The macros normally compile to nothing on optimized
00096 ** builds.
00097 ** 
00098 ** Application designers should be aware of the effects of
00099 ** debug and optimized build differences when using result of the
00100 ** Counter Feature macros in expressions.
00101 ** 
00102 ** The Counter Feature is thread-safe and SMP safe.
00103 ** 
00104 ** /lth. 09-Jun-1998.
00105 */
00106 
00107 #include "prtypes.h"
00108 
00109 PR_BEGIN_EXTERN_C
00110 
00111 /*
00112 ** Opaque counter handle type.
00113 ** ... don't even think of looking in here.
00114 **
00115 */
00116 typedef void *  PRCounterHandle;
00117 
00118 #define PRCOUNTER_NAME_MAX 31
00119 #define PRCOUNTER_DESC_MAX 255
00120 
00121 
00122 
00123 /* -----------------------------------------------------------------------
00124 ** FUNCTION: PR_DEFINE_COUNTER() -- Define a PRCounterHandle
00125 ** 
00126 ** DESCRIPTION: PR_DEFINE_COUNTER() is used to define a counter
00127 ** handle.
00128 ** 
00129 */
00130 #define PR_DEFINE_COUNTER(name) PRCounterHandle name
00131 
00132 /* -----------------------------------------------------------------------
00133 ** FUNCTION: PR_INIT_COUNTER_HANDLE() -- Set the value of a PRCounterHandle
00134 ** 
00135 ** DESCRIPTION: 
00136 ** PR_INIT_COUNTER_HANDLE() sets the value of a PRCounterHandle
00137 ** to value.
00138 ** 
00139 */
00140 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
00141 #define PR_INIT_COUNTER_HANDLE(handle,value)\
00142     (handle) = (PRCounterHandle)(value)
00143 #else
00144 #define PR_INIT_COUNTER_HANDLE(handle,value)
00145 #endif
00146 
00147 /* -----------------------------------------------------------------------
00148 ** FUNCTION: PR_CreateCounter() -- Create a counter
00149 ** 
00150 ** DESCRIPTION: PR_CreateCounter() creates a counter object and
00151 ** initializes it to zero.
00152 ** 
00153 ** The macro form takes as its first argument the name of the
00154 ** PRCounterHandle to receive the handle returned from
00155 ** PR_CreateCounter().
00156 ** 
00157 ** INPUTS:
00158 **  qName: The QName for the counter object. The maximum length
00159 ** of qName is defined by PRCOUNTER_NAME_MAX
00160 ** 
00161 **  rName: The RName for the counter object. The maximum length
00162 ** of qName is defined by PRCOUNTER_NAME_MAX
00163 ** 
00164 **  descrioption: The description of the counter object. The
00165 ** maximum length of description is defined by
00166 ** PRCOUNTER_DESC_MAX.
00167 ** 
00168 ** OUTPUTS:
00169 ** 
00170 ** RETURNS:
00171 **  PRCounterHandle.
00172 ** 
00173 ** RESTRICTIONS:
00174 ** 
00175 */
00176 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
00177 #define PR_CREATE_COUNTER(handle,qName,rName,description)\
00178    (handle) = PR_CreateCounter((qName),(rName),(description))
00179 #else
00180 #define PR_CREATE_COUNTER(handle,qName,rName,description)
00181 #endif
00182 
00183 NSPR_API(PRCounterHandle) 
00184        PR_CreateCounter( 
00185               const char *qName, 
00186        const char *rName, 
00187         const char *description 
00188 );
00189 
00190 /* -----------------------------------------------------------------------
00191 ** FUNCTION: PR_DestroyCounter() -- Destroy a counter object.
00192 ** 
00193 ** DESCRIPTION: PR_DestroyCounter() removes a counter and
00194 ** unregisters its handle from the counter database.
00195 ** 
00196 ** INPUTS:
00197 **  handle: the PRCounterHandle of the counter to be destroyed.
00198 ** 
00199 ** OUTPUTS: 
00200 **  The counter is destroyed.
00201 ** 
00202 ** RETURNS: void
00203 ** 
00204 ** RESTRICTIONS:
00205 ** 
00206 */
00207 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
00208 #define PR_DESTROY_COUNTER(handle) PR_DestroyCounter((handle))
00209 #else
00210 #define PR_DESTROY_COUNTER(handle)
00211 #endif
00212 
00213 NSPR_API(void) 
00214        PR_DestroyCounter( 
00215               PRCounterHandle handle 
00216 );
00217 
00218 
00219 /* -----------------------------------------------------------------------
00220 ** FUNCTION: PR_GetCounterHandleFromName() -- Retreive a
00221 ** counter's handle give its name.
00222 ** 
00223 ** DESCRIPTION: PR_GetCounterHandleFromName() retreives a
00224 ** counter's handle from the counter database, given the name
00225 ** the counter was originally created with.
00226 ** 
00227 ** INPUTS:
00228 **  qName: Counter's original QName.
00229 **  rName: Counter's original RName.
00230 ** 
00231 ** OUTPUTS:
00232 ** 
00233 ** RETURNS: 
00234 **  PRCounterHandle or PRCounterError.
00235 ** 
00236 ** RESTRICTIONS:
00237 ** 
00238 */
00239 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
00240 #define PR_GET_COUNTER_HANDLE_FROM_NAME(handle,qName,rName)\
00241     (handle) = PR_GetCounterHandleFromName((qName),(rName))
00242 #else
00243 #define PR_GET_COUNTER_HANDLE_FROM_NAME(handle,qName,rName)
00244 #endif
00245 
00246 NSPR_API(PRCounterHandle) 
00247        PR_GetCounterHandleFromName( 
00248        const char *qName, 
00249        const char *rName 
00250 );
00251 
00252 /* -----------------------------------------------------------------------
00253 ** FUNCTION: PR_GetCounterNameFromHandle() -- Retreive a
00254 ** counter's name, given its handle.
00255 ** 
00256 ** DESCRIPTION: PR_GetCounterNameFromHandle() retreives a
00257 ** counter's name given its handle.
00258 ** 
00259 ** INPUTS:
00260 **  qName: Where to store a pointer to qName.
00261 **  rName: Where to store a pointer to rName.
00262 **  description: Where to store a pointer to description.
00263 ** 
00264 ** OUTPUTS: Pointers to the Counter Feature's copies of the names
00265 ** used when the counters were created.
00266 ** 
00267 ** RETURNS: void
00268 ** 
00269 ** RESTRICTIONS:
00270 ** 
00271 */
00272 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
00273 #define PR_GET_COUNTER_NAME_FROM_HANDLE(handle,qName,rName,description)\
00274     PR_GetCounterNameFromHandle((handle),(qName),(rName),(description))
00275 #else
00276 #define PR_GET_COUNTER_NAME_FROM_HANDLE(handle,qName,rName,description )
00277 #endif
00278 
00279 NSPR_API(void) 
00280        PR_GetCounterNameFromHandle( 
00281        PRCounterHandle handle,  
00282            const char **qName, 
00283            const char **rName, 
00284               const char **description 
00285 );
00286 
00287 
00288 /* -----------------------------------------------------------------------
00289 ** FUNCTION: PR_IncrementCounter() -- Add one to the referenced
00290 ** counter.
00291 ** 
00292 ** DESCRIPTION: Add one to the referenced counter.
00293 ** 
00294 ** INPUTS:
00295 **  handle: The PRCounterHandle of the counter to be incremented
00296 ** 
00297 ** OUTPUTS: The counter is incrementd.
00298 ** 
00299 ** RETURNS: void
00300 ** 
00301 ** RESTRICTIONS:
00302 ** 
00303 */
00304 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
00305 #define PR_INCREMENT_COUNTER(handle) PR_IncrementCounter(handle)
00306 #else
00307 #define PR_INCREMENT_COUNTER(handle)
00308 #endif
00309 
00310 NSPR_API(void) 
00311        PR_IncrementCounter( 
00312               PRCounterHandle handle
00313 );
00314 
00315 
00316 /* -----------------------------------------------------------------------
00317 ** FUNCTION: PR_DecrementCounter() -- Subtract one from the
00318 ** referenced counter
00319 ** 
00320 ** DESCRIPTION: Subtract one from the referenced counter.
00321 ** 
00322 ** INPUTS: 
00323 **  handle: The PRCounterHandle of the coutner to be
00324 ** decremented.
00325 ** 
00326 ** OUTPUTS: the counter is decremented.
00327 ** 
00328 ** RETURNS: void
00329 ** 
00330 ** RESTRICTIONS:
00331 ** 
00332 */
00333 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
00334 #define PR_DECREMENT_COUNTER(handle) PR_DecrementCounter(handle)
00335 #else
00336 #define PR_DECREMENT_COUNTER(handle)
00337 #endif
00338 
00339 NSPR_API(void) 
00340        PR_DecrementCounter( 
00341               PRCounterHandle handle
00342 );
00343 
00344 /* -----------------------------------------------------------------------
00345 ** FUNCTION: PR_AddToCounter() -- Add a value to a counter.
00346 ** 
00347 ** DESCRIPTION: Add value to the counter referenced by handle.
00348 ** 
00349 ** INPUTS:
00350 **  handle: the PRCounterHandle of the counter to be added to.
00351 ** 
00352 **  value: the value to be added to the counter.
00353 ** 
00354 ** OUTPUTS: new value for counter.
00355 ** 
00356 ** RETURNS: void
00357 ** 
00358 ** RESTRICTIONS:
00359 ** 
00360 */
00361 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
00362 #define PR_ADD_TO_COUNTER(handle,value)\
00363     PR_AddToCounter((handle),(value))
00364 #else
00365 #define PR_ADD_TO_COUNTER(handle,value)
00366 #endif
00367 
00368 NSPR_API(void) 
00369        PR_AddToCounter( 
00370        PRCounterHandle handle, 
00371            PRUint32 value 
00372 );
00373 
00374 
00375 /* -----------------------------------------------------------------------
00376 ** FUNCTION: PR_SubtractFromCounter() -- A value is subtracted
00377 ** from a counter.
00378 ** 
00379 ** DESCRIPTION:
00380 ** Subtract a value from a counter.
00381 ** 
00382 ** INPUTS:
00383 **  handle: the PRCounterHandle of the counter to be subtracted
00384 ** from.
00385 ** 
00386 **  value: the value to be subtracted from the counter.
00387 ** 
00388 ** OUTPUTS: new value for counter
00389 ** 
00390 ** RETURNS: void
00391 ** 
00392 ** RESTRICTIONS:
00393 ** 
00394 */
00395 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
00396 #define PR_SUBTRACT_FROM_COUNTER(handle,value)\
00397     PR_SubtractFromCounter((handle),(value))
00398 #else
00399 #define PR_SUBTRACT_FROM_COUNTER(handle,value)
00400 #endif
00401 
00402 NSPR_API(void) 
00403        PR_SubtractFromCounter( 
00404        PRCounterHandle handle, 
00405            PRUint32 value 
00406 );
00407 
00408 
00409 /* -----------------------------------------------------------------------
00410 ** FUNCTION: PR_GetCounter() -- Retreive the value of a counter
00411 ** 
00412 ** DESCRIPTION:
00413 ** Retreive the value of a counter.
00414 ** 
00415 ** INPUTS:
00416 **  handle: the PR_CounterHandle of the counter to be retreived
00417 ** 
00418 ** OUTPUTS:
00419 ** 
00420 ** RETURNS: The value of the referenced counter
00421 ** 
00422 ** RESTRICTIONS:
00423 ** 
00424 */
00425 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
00426 #define PR_GET_COUNTER(counter,handle)\
00427     (counter) = PR_GetCounter((handle))
00428 #else
00429 #define PR_GET_COUNTER(counter,handle) 0
00430 #endif
00431 
00432 NSPR_API(PRUint32) 
00433        PR_GetCounter( 
00434               PRCounterHandle handle 
00435 );
00436 
00437 /* -----------------------------------------------------------------------
00438 ** FUNCTION: PR_SetCounter() -- Replace the content of counter
00439 ** with value.
00440 ** 
00441 ** DESCRIPTION: The contents of the referenced counter are
00442 ** replaced by value.
00443 ** 
00444 ** INPUTS:
00445 **  handle: the PRCounterHandle of the counter whose contents
00446 ** are to be replaced.
00447 ** 
00448 **  value: the new value of the counter.
00449 ** 
00450 ** OUTPUTS:
00451 ** 
00452 ** RETURNS: void
00453 ** 
00454 ** RESTRICTIONS:
00455 ** 
00456 */
00457 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
00458 #define PR_SET_COUNTER(handle,value) PR_SetCounter((handle),(value))
00459 #else
00460 #define PR_SET_COUNTER(handle,value)
00461 #endif
00462 
00463 NSPR_API(void) 
00464        PR_SetCounter( 
00465               PRCounterHandle handle, 
00466               PRUint32 value 
00467 );
00468 
00469 
00470 /* -----------------------------------------------------------------------
00471 ** FUNCTION: PR_FindNextCounterQname() -- Retreive the next QName counter
00472 ** handle iterator
00473 ** 
00474 ** DESCRIPTION:
00475 ** PR_FindNextCounterQname() retreives the first or next Qname
00476 ** the counter data base, depending on the value of handle. When
00477 ** handle is NULL, the function attempts to retreive the first
00478 ** QName handle in the database. When handle is a handle previosly
00479 ** retreived QName handle, then the function attempts to retreive
00480 ** the next QName handle.
00481 ** 
00482 ** INPUTS: 
00483 **  handle: PRCounterHandle or NULL.
00484 ** 
00485 ** OUTPUTS: returned
00486 ** 
00487 ** RETURNS: PRCounterHandle or NULL when no more QName counter
00488 ** handles are present.
00489 ** 
00490 ** RESTRICTIONS:
00491 **  A concurrent PR_CreateCounter() or PR_DestroyCounter() may
00492 ** cause unpredictable results.
00493 ** 
00494 ** A PRCounterHandle returned from this function may only be used
00495 ** in another PR_FindNextCounterQname() function call; other
00496 ** operations may cause unpredictable results.
00497 ** 
00498 */
00499 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
00500 #define PR_FIND_NEXT_COUNTER_QNAME(next,handle)\
00501     (next) = PR_FindNextCounterQname((handle))
00502 #else
00503 #define PR_FIND_NEXT_COUNTER_QNAME(next,handle) NULL
00504 #endif
00505 
00506 NSPR_API(PRCounterHandle) 
00507        PR_FindNextCounterQname( 
00508         PRCounterHandle handle
00509 );
00510 
00511 /* -----------------------------------------------------------------------
00512 ** FUNCTION: PR_FindNextCounterRname() -- Retreive the next RName counter
00513 ** handle iterator
00514 ** 
00515 ** DESCRIPTION:
00516 ** PR_FindNextCounterRname() retreives the first or next RNname
00517 ** handle from the counter data base, depending on the
00518 ** value of handle. When handle is NULL, the function attempts to
00519 ** retreive the first RName handle in the database. When handle is
00520 ** a handle previosly retreived RName handle, then the function
00521 ** attempts to retreive the next RName handle.
00522 ** 
00523 ** INPUTS:
00524 **  handle: PRCounterHandle or NULL.
00525 **  qhandle: PRCounterHandle of a previously aquired via
00526 ** PR_FIND_NEXT_QNAME_HANDLE()
00527 ** 
00528 ** OUTPUTS: returned
00529 ** 
00530 ** RETURNS: PRCounterHandle or NULL when no more RName counter
00531 ** handles are present.
00532 ** 
00533 ** RESTRICTIONS:
00534 **  A concurrent PR_CreateCounter() or PR_DestroyCounter() may
00535 ** cause unpredictable results.
00536 ** 
00537 ** A PRCounterHandle returned from this function may only be used
00538 ** in another PR_FindNextCounterRname() function call; other
00539 ** operations may cause unpredictable results.
00540 ** 
00541 */
00542 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
00543 #define PR_FIND_NEXT_COUNTER_RNAME(next,rhandle,qhandle)\
00544     (next) = PR_FindNextCounterRname((rhandle),(qhandle))
00545 #else
00546 #define PR_FIND_NEXT_COUNTER_RNAME(next,rhandle,qhandle)
00547 #endif
00548 
00549 NSPR_API(PRCounterHandle) 
00550        PR_FindNextCounterRname( 
00551         PRCounterHandle rhandle,
00552         PRCounterHandle qhandle
00553 );
00554 
00555 PR_END_EXTERN_C
00556 
00557 #endif /* prcountr_h___ */