nsprpub/pr/include/prcountr.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is the Netscape Portable Runtime (NSPR).
  16  *
  17  * The Initial Developer of the Original Code is
  18  * Netscape Communications Corporation.
  19  * Portions created by the Initial Developer are Copyright (C) 1998-2000
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *
  24  * Alternatively, the contents of this file may be used under the terms of
  25  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27  * in which case the provisions of the GPL or the LGPL are applicable instead
  28  * of those above. If you wish to allow use of your version of this file only
  29  * under the terms of either the GPL or the LGPL, and not to allow others to
  30  * use your version of this file under the terms of the MPL, indicate your
  31  * decision by deleting the provisions above and replace them with the notice
  32  * and other provisions required by the GPL or the LGPL. If you do not delete
  33  * the provisions above, a recipient may use your version of this file under
  34  * the terms of any one of the MPL, the GPL or the LGPL.
  35  *
  36  * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef prcountr_h___
  39 #define prcountr_h___
  40
  41 /*----------------------------------------------------------------------------
  42 ** prcountr.h -- NSPR Instrumentation counters
  43 **
  44 ** The NSPR Counter Feature provides a means to "count
  45 ** something." Counters can be dynamically defined, incremented,
  46 ** decremented, set, and deleted under application program
  47 ** control.
  48 **
  49 ** The Counter Feature is intended to be used as instrumentation,
  50 ** not as operational data. If you need a counter for operational
  51 ** data, use native integral types.
  52 **
  53 ** Counters are 32bit unsigned intergers. On overflow, a counter
  54 ** will wrap. No exception is recognized or reported.
  55 **
  56 ** A counter can be dynamically created using a two level naming
  57 ** convention. A "handle" is returned when the counter is
  58 ** created. The counter can subsequently be addressed by its
  59 ** handle. An API is provided to get an existing counter's handle
  60 ** given the names with  which it was originally created.
  61 ** Similarly, a counter's name can be retrieved given its handle.
  62 **
  63 ** The counter naming convention is a two-level hierarchy. The
  64 ** QName is the higher level of the hierarchy; RName is the
  65 ** lower level. RNames can be thought of as existing within a
  66 ** QName. The same RName can exist within multiple QNames. QNames
  67 ** are unique. The NSPR Counter is not a near-zero overhead
  68 ** feature. Application designers should be aware of
  69 ** serialization issues when using the Counter API. Creating a
  70 ** counter locks a large asset, potentially causing a stall. This
  71 ** suggest that applications should create counters at component
  72 ** initialization, for example, and not create and destroy them
  73 ** willy-nilly. ... You have been warned.
  74 **
  75 ** Incrementing and Adding to counters uses atomic operations.
  76 ** The performance of these operations will vary from platform
  77 ** to platform. On platforms where atomic operations are not
  78 ** supported the overhead may be substantial.
  79 **
  80 ** When traversing the counter database with FindNext functions,
  81 ** the instantaneous values of any given counter is that at the
  82 ** moment of extraction. The state of the entire counter database
  83 ** may not be viewed as atomic.
  84 **
  85 ** The counter interface may be disabled (No-Op'd) at compile
  86 ** time. When DEBUG is defined at compile time, the Counter
  87 ** Feature is compiled into NSPR and applications invoking it.
  88 ** When DEBUG is not defined, the counter macros compile to
  89 ** nothing. To force the Counter Feature to be compiled into an
  90 ** optimized build, define FORCE_NSPR_COUNTERS at compile time
  91 ** for both NSPR and the application intending to use it.
  92 **
  93 ** Application designers should use the macro form of the Counter
  94 ** Feature methods to minimize performance impact in optimized
  95 ** builds. The macros normally compile to nothing on optimized
  96 ** builds.
  97 **
  98 ** Application designers should be aware of the effects of
  99 ** debug and optimized build differences when using result of the
 100 ** Counter Feature macros in expressions.
 101 **
 102 ** The Counter Feature is thread-safe and SMP safe.
 103 **
 104 ** /lth. 09-Jun-1998.
 105 */
 106
 107 #include "prtypes.h"
 108
 109 PR_BEGIN_EXTERN_C
 110
 111 /*
 112 ** Opaque counter handle type.
 113 ** ... don't even think of looking in here.
 114 **
 115 */
 116 typedef void *  PRCounterHandle;
 117
 118 #define PRCOUNTER_NAME_MAX 31
 119 #define PRCOUNTER_DESC_MAX 255
 120
 121
 122
 123 /* -----------------------------------------------------------------------
 124 ** FUNCTION: PR_DEFINE_COUNTER() -- Define a PRCounterHandle
 125 **
 126 ** DESCRIPTION: PR_DEFINE_COUNTER() is used to define a counter
 127 ** handle.
 128 **
 129 */
 130 #define PR_DEFINE_COUNTER(name) PRCounterHandle name
 131
 132 /* -----------------------------------------------------------------------
 133 ** FUNCTION: PR_INIT_COUNTER_HANDLE() -- Set the value of a PRCounterHandle
 134 **
 135 ** DESCRIPTION:
 136 ** PR_INIT_COUNTER_HANDLE() sets the value of a PRCounterHandle
 137 ** to value.
 138 **
 139 */
 140 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
 141 #define PR_INIT_COUNTER_HANDLE(handle,value)\
 142     (handle) = (PRCounterHandle)(value)
 143 #else
 144 #define PR_INIT_COUNTER_HANDLE(handle,value)
 145 #endif
 146
 147 /* -----------------------------------------------------------------------
 148 ** FUNCTION: PR_CreateCounter() -- Create a counter
 149 **
 150 ** DESCRIPTION: PR_CreateCounter() creates a counter object and
 151 ** initializes it to zero.
 152 **
 153 ** The macro form takes as its first argument the name of the
 154 ** PRCounterHandle to receive the handle returned from
 155 ** PR_CreateCounter().
 156 **
 157 ** INPUTS:
 158 **  qName: The QName for the counter object. The maximum length
 159 ** of qName is defined by PRCOUNTER_NAME_MAX
 160 **
 161 **  rName: The RName for the counter object. The maximum length
 162 ** of qName is defined by PRCOUNTER_NAME_MAX
 163 **
 164 **  descrioption: The description of the counter object. The
 165 ** maximum length of description is defined by
 166 ** PRCOUNTER_DESC_MAX.
 167 **
 168 ** OUTPUTS:
 169 **
 170 ** RETURNS:
 171 **  PRCounterHandle.
 172 **
 173 ** RESTRICTIONS:
 174 **
 175 */
 176 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
 177 #define PR_CREATE_COUNTER(handle,qName,rName,description)\
 178    (handle) = PR_CreateCounter((qName),(rName),(description))
 179 #else
 180 #define PR_CREATE_COUNTER(handle,qName,rName,description)
 181 #endif
 182
 183 NSPR_API(PRCounterHandle)
 184         PR_CreateCounter(
 185                 const char *qName,
 186         const char *rName,
 187         const char *description
 188 );
 189
 190 /* -----------------------------------------------------------------------
 191 ** FUNCTION: PR_DestroyCounter() -- Destroy a counter object.
 192 **
 193 ** DESCRIPTION: PR_DestroyCounter() removes a counter and
 194 ** unregisters its handle from the counter database.
 195 **
 196 ** INPUTS:
 197 **  handle: the PRCounterHandle of the counter to be destroyed.
 198 **
 199 ** OUTPUTS:
 200 **  The counter is destroyed.
 201 **
 202 ** RETURNS: void
 203 **
 204 ** RESTRICTIONS:
 205 **
 206 */
 207 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
 208 #define PR_DESTROY_COUNTER(handle) PR_DestroyCounter((handle))
 209 #else
 210 #define PR_DESTROY_COUNTER(handle)
 211 #endif
 212
 213 NSPR_API(void)
 214         PR_DestroyCounter(
 215                 PRCounterHandle handle
 216 );
 217
 218
 219 /* -----------------------------------------------------------------------
 220 ** FUNCTION: PR_GetCounterHandleFromName() -- Retreive a
 221 ** counter's handle give its name.
 222 **
 223 ** DESCRIPTION: PR_GetCounterHandleFromName() retreives a
 224 ** counter's handle from the counter database, given the name
 225 ** the counter was originally created with.
 226 **
 227 ** INPUTS:
 228 **  qName: Counter's original QName.
 229 **  rName: Counter's original RName.
 230 **
 231 ** OUTPUTS:
 232 **
 233 ** RETURNS:
 234 **  PRCounterHandle or PRCounterError.
 235 **
 236 ** RESTRICTIONS:
 237 **
 238 */
 239 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
 240 #define PR_GET_COUNTER_HANDLE_FROM_NAME(handle,qName,rName)\
 241     (handle) = PR_GetCounterHandleFromName((qName),(rName))
 242 #else
 243 #define PR_GET_COUNTER_HANDLE_FROM_NAME(handle,qName,rName)
 244 #endif
 245
 246 NSPR_API(PRCounterHandle)
 247         PR_GetCounterHandleFromName(
 248         const char *qName,
 249         const char *rName
 250 );
 251
 252 /* -----------------------------------------------------------------------
 253 ** FUNCTION: PR_GetCounterNameFromHandle() -- Retreive a
 254 ** counter's name, given its handle.
 255 **
 256 ** DESCRIPTION: PR_GetCounterNameFromHandle() retreives a
 257 ** counter's name given its handle.
 258 **
 259 ** INPUTS:
 260 **  qName: Where to store a pointer to qName.
 261 **  rName: Where to store a pointer to rName.
 262 **  description: Where to store a pointer to description.
 263 **
 264 ** OUTPUTS: Pointers to the Counter Feature's copies of the names
 265 ** used when the counters were created.
 266 **
 267 ** RETURNS: void
 268 **
 269 ** RESTRICTIONS:
 270 **
 271 */
 272 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
 273 #define PR_GET_COUNTER_NAME_FROM_HANDLE(handle,qName,rName,description)\
 274     PR_GetCounterNameFromHandle((handle),(qName),(rName),(description))
 275 #else
 276 #define PR_GET_COUNTER_NAME_FROM_HANDLE(handle,qName,rName,description )
 277 #endif
 278
 279 NSPR_API(void)
 280         PR_GetCounterNameFromHandle(
 281         PRCounterHandle handle,
 282             const char **qName,
 283             const char **rName,
 284                 const char **description
 285 );
 286
 287
 288 /* -----------------------------------------------------------------------
 289 ** FUNCTION: PR_IncrementCounter() -- Add one to the referenced
 290 ** counter.
 291 **
 292 ** DESCRIPTION: Add one to the referenced counter.
 293 **
 294 ** INPUTS:
 295 **  handle: The PRCounterHandle of the counter to be incremented
 296 **
 297 ** OUTPUTS: The counter is incrementd.
 298 **
 299 ** RETURNS: void
 300 **
 301 ** RESTRICTIONS:
 302 **
 303 */
 304 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
 305 #define PR_INCREMENT_COUNTER(handle) PR_IncrementCounter(handle)
 306 #else
 307 #define PR_INCREMENT_COUNTER(handle)
 308 #endif
 309
 310 NSPR_API(void)
 311         PR_IncrementCounter(
 312                 PRCounterHandle handle
 313 );
 314
 315
 316 /* -----------------------------------------------------------------------
 317 ** FUNCTION: PR_DecrementCounter() -- Subtract one from the
 318 ** referenced counter
 319 **
 320 ** DESCRIPTION: Subtract one from the referenced counter.
 321 **
 322 ** INPUTS:
 323 **  handle: The PRCounterHandle of the coutner to be
 324 ** decremented.
 325 **
 326 ** OUTPUTS: the counter is decremented.
 327 **
 328 ** RETURNS: void
 329 **
 330 ** RESTRICTIONS:
 331 **
 332 */
 333 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
 334 #define PR_DECREMENT_COUNTER(handle) PR_DecrementCounter(handle)
 335 #else
 336 #define PR_DECREMENT_COUNTER(handle)
 337 #endif
 338
 339 NSPR_API(void)
 340         PR_DecrementCounter(
 341                 PRCounterHandle handle
 342 );
 343
 344 /* -----------------------------------------------------------------------
 345 ** FUNCTION: PR_AddToCounter() -- Add a value to a counter.
 346 **
 347 ** DESCRIPTION: Add value to the counter referenced by handle.
 348 **
 349 ** INPUTS:
 350 **  handle: the PRCounterHandle of the counter to be added to.
 351 **
 352 **  value: the value to be added to the counter.
 353 **
 354 ** OUTPUTS: new value for counter.
 355 **
 356 ** RETURNS: void
 357 **
 358 ** RESTRICTIONS:
 359 **
 360 */
 361 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
 362 #define PR_ADD_TO_COUNTER(handle,value)\
 363     PR_AddToCounter((handle),(value))
 364 #else
 365 #define PR_ADD_TO_COUNTER(handle,value)
 366 #endif
 367
 368 NSPR_API(void)
 369         PR_AddToCounter(
 370         PRCounterHandle handle,
 371             PRUint32 value
 372 );
 373
 374
 375 /* -----------------------------------------------------------------------
 376 ** FUNCTION: PR_SubtractFromCounter() -- A value is subtracted
 377 ** from a counter.
 378 **
 379 ** DESCRIPTION:
 380 ** Subtract a value from a counter.
 381 **
 382 ** INPUTS:
 383 **  handle: the PRCounterHandle of the counter to be subtracted
 384 ** from.
 385 **
 386 **  value: the value to be subtracted from the counter.
 387 **
 388 ** OUTPUTS: new value for counter
 389 **
 390 ** RETURNS: void
 391 **
 392 ** RESTRICTIONS:
 393 **
 394 */
 395 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
 396 #define PR_SUBTRACT_FROM_COUNTER(handle,value)\
 397     PR_SubtractFromCounter((handle),(value))
 398 #else
 399 #define PR_SUBTRACT_FROM_COUNTER(handle,value)
 400 #endif
 401
 402 NSPR_API(void)
 403         PR_SubtractFromCounter(
 404         PRCounterHandle handle,
 405             PRUint32 value
 406 );
 407
 408
 409 /* -----------------------------------------------------------------------
 410 ** FUNCTION: PR_GetCounter() -- Retreive the value of a counter
 411 **
 412 ** DESCRIPTION:
 413 ** Retreive the value of a counter.
 414 **
 415 ** INPUTS:
 416 **  handle: the PR_CounterHandle of the counter to be retreived
 417 **
 418 ** OUTPUTS:
 419 **
 420 ** RETURNS: The value of the referenced counter
 421 **
 422 ** RESTRICTIONS:
 423 **
 424 */
 425 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
 426 #define PR_GET_COUNTER(counter,handle)\
 427     (counter) = PR_GetCounter((handle))
 428 #else
 429 #define PR_GET_COUNTER(counter,handle) 0
 430 #endif
 431
 432 NSPR_API(PRUint32)
 433         PR_GetCounter(
 434                 PRCounterHandle handle
 435 );
 436
 437 /* -----------------------------------------------------------------------
 438 ** FUNCTION: PR_SetCounter() -- Replace the content of counter
 439 ** with value.
 440 **
 441 ** DESCRIPTION: The contents of the referenced counter are
 442 ** replaced by value.
 443 **
 444 ** INPUTS:
 445 **  handle: the PRCounterHandle of the counter whose contents
 446 ** are to be replaced.
 447 **
 448 **  value: the new value of the counter.
 449 **
 450 ** OUTPUTS:
 451 **
 452 ** RETURNS: void
 453 **
 454 ** RESTRICTIONS:
 455 **
 456 */
 457 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
 458 #define PR_SET_COUNTER(handle,value) PR_SetCounter((handle),(value))
 459 #else
 460 #define PR_SET_COUNTER(handle,value)
 461 #endif
 462
 463 NSPR_API(void)
 464         PR_SetCounter(
 465                 PRCounterHandle handle,
 466                 PRUint32 value
 467 );
 468
 469
 470 /* -----------------------------------------------------------------------
 471 ** FUNCTION: PR_FindNextCounterQname() -- Retreive the next QName counter
 472 ** handle iterator
 473 **
 474 ** DESCRIPTION:
 475 ** PR_FindNextCounterQname() retreives the first or next Qname
 476 ** the counter data base, depending on the value of handle. When
 477 ** handle is NULL, the function attempts to retreive the first
 478 ** QName handle in the database. When handle is a handle previosly
 479 ** retreived QName handle, then the function attempts to retreive
 480 ** the next QName handle.
 481 **
 482 ** INPUTS:
 483 **  handle: PRCounterHandle or NULL.
 484 **
 485 ** OUTPUTS: returned
 486 **
 487 ** RETURNS: PRCounterHandle or NULL when no more QName counter
 488 ** handles are present.
 489 **
 490 ** RESTRICTIONS:
 491 **  A concurrent PR_CreateCounter() or PR_DestroyCounter() may
 492 ** cause unpredictable results.
 493 **
 494 ** A PRCounterHandle returned from this function may only be used
 495 ** in another PR_FindNextCounterQname() function call; other
 496 ** operations may cause unpredictable results.
 497 **
 498 */
 499 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
 500 #define PR_FIND_NEXT_COUNTER_QNAME(next,handle)\
 501     (next) = PR_FindNextCounterQname((handle))
 502 #else
 503 #define PR_FIND_NEXT_COUNTER_QNAME(next,handle) NULL
 504 #endif
 505
 506 NSPR_API(PRCounterHandle)
 507         PR_FindNextCounterQname(
 508         PRCounterHandle handle
 509 );
 510
 511 /* -----------------------------------------------------------------------
 512 ** FUNCTION: PR_FindNextCounterRname() -- Retreive the next RName counter
 513 ** handle iterator
 514 **
 515 ** DESCRIPTION:
 516 ** PR_FindNextCounterRname() retreives the first or next RNname
 517 ** handle from the counter data base, depending on the
 518 ** value of handle. When handle is NULL, the function attempts to
 519 ** retreive the first RName handle in the database. When handle is
 520 ** a handle previosly retreived RName handle, then the function
 521 ** attempts to retreive the next RName handle.
 522 **
 523 ** INPUTS:
 524 **  handle: PRCounterHandle or NULL.
 525 **  qhandle: PRCounterHandle of a previously aquired via
 526 ** PR_FIND_NEXT_QNAME_HANDLE()
 527 **
 528 ** OUTPUTS: returned
 529 **
 530 ** RETURNS: PRCounterHandle or NULL when no more RName counter
 531 ** handles are present.
 532 **
 533 ** RESTRICTIONS:
 534 **  A concurrent PR_CreateCounter() or PR_DestroyCounter() may
 535 ** cause unpredictable results.
 536 **
 537 ** A PRCounterHandle returned from this function may only be used
 538 ** in another PR_FindNextCounterRname() function call; other
 539 ** operations may cause unpredictable results.
 540 **
 541 */
 542 #if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
 543 #define PR_FIND_NEXT_COUNTER_RNAME(next,rhandle,qhandle)\
 544     (next) = PR_FindNextCounterRname((rhandle),(qhandle))
 545 #else
 546 #define PR_FIND_NEXT_COUNTER_RNAME(next,rhandle,qhandle)
 547 #endif
 548
 549 NSPR_API(PRCounterHandle)
 550         PR_FindNextCounterRname(
 551         PRCounterHandle rhandle,
 552         PRCounterHandle qhandle
 553 );
 554
 555 PR_END_EXTERN_C
 556
 557 #endif /* prcountr_h___ */