third_party/npapi/npspy/extern/nspr/prcountr.h

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