1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/nsprpub/pr/include/prcountr.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,525 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#ifndef prcountr_h___
1.10 +#define prcountr_h___
1.11 +
1.12 +/*----------------------------------------------------------------------------
1.13 +** prcountr.h -- NSPR Instrumentation counters
1.14 +**
1.15 +** The NSPR Counter Feature provides a means to "count
1.16 +** something." Counters can be dynamically defined, incremented,
1.17 +** decremented, set, and deleted under application program
1.18 +** control.
1.19 +**
1.20 +** The Counter Feature is intended to be used as instrumentation,
1.21 +** not as operational data. If you need a counter for operational
1.22 +** data, use native integral types.
1.23 +**
1.24 +** Counters are 32bit unsigned intergers. On overflow, a counter
1.25 +** will wrap. No exception is recognized or reported.
1.26 +**
1.27 +** A counter can be dynamically created using a two level naming
1.28 +** convention. A "handle" is returned when the counter is
1.29 +** created. The counter can subsequently be addressed by its
1.30 +** handle. An API is provided to get an existing counter's handle
1.31 +** given the names with which it was originally created.
1.32 +** Similarly, a counter's name can be retrieved given its handle.
1.33 +**
1.34 +** The counter naming convention is a two-level hierarchy. The
1.35 +** QName is the higher level of the hierarchy; RName is the
1.36 +** lower level. RNames can be thought of as existing within a
1.37 +** QName. The same RName can exist within multiple QNames. QNames
1.38 +** are unique. The NSPR Counter is not a near-zero overhead
1.39 +** feature. Application designers should be aware of
1.40 +** serialization issues when using the Counter API. Creating a
1.41 +** counter locks a large asset, potentially causing a stall. This
1.42 +** suggest that applications should create counters at component
1.43 +** initialization, for example, and not create and destroy them
1.44 +** willy-nilly. ... You have been warned.
1.45 +**
1.46 +** Incrementing and Adding to counters uses atomic operations.
1.47 +** The performance of these operations will vary from platform
1.48 +** to platform. On platforms where atomic operations are not
1.49 +** supported the overhead may be substantial.
1.50 +**
1.51 +** When traversing the counter database with FindNext functions,
1.52 +** the instantaneous values of any given counter is that at the
1.53 +** moment of extraction. The state of the entire counter database
1.54 +** may not be viewed as atomic.
1.55 +**
1.56 +** The counter interface may be disabled (No-Op'd) at compile
1.57 +** time. When DEBUG is defined at compile time, the Counter
1.58 +** Feature is compiled into NSPR and applications invoking it.
1.59 +** When DEBUG is not defined, the counter macros compile to
1.60 +** nothing. To force the Counter Feature to be compiled into an
1.61 +** optimized build, define FORCE_NSPR_COUNTERS at compile time
1.62 +** for both NSPR and the application intending to use it.
1.63 +**
1.64 +** Application designers should use the macro form of the Counter
1.65 +** Feature methods to minimize performance impact in optimized
1.66 +** builds. The macros normally compile to nothing on optimized
1.67 +** builds.
1.68 +**
1.69 +** Application designers should be aware of the effects of
1.70 +** debug and optimized build differences when using result of the
1.71 +** Counter Feature macros in expressions.
1.72 +**
1.73 +** The Counter Feature is thread-safe and SMP safe.
1.74 +**
1.75 +** /lth. 09-Jun-1998.
1.76 +*/
1.77 +
1.78 +#include "prtypes.h"
1.79 +
1.80 +PR_BEGIN_EXTERN_C
1.81 +
1.82 +/*
1.83 +** Opaque counter handle type.
1.84 +** ... don't even think of looking in here.
1.85 +**
1.86 +*/
1.87 +typedef void * PRCounterHandle;
1.88 +
1.89 +#define PRCOUNTER_NAME_MAX 31
1.90 +#define PRCOUNTER_DESC_MAX 255
1.91 +
1.92 +
1.93 +
1.94 +/* -----------------------------------------------------------------------
1.95 +** FUNCTION: PR_DEFINE_COUNTER() -- Define a PRCounterHandle
1.96 +**
1.97 +** DESCRIPTION: PR_DEFINE_COUNTER() is used to define a counter
1.98 +** handle.
1.99 +**
1.100 +*/
1.101 +#define PR_DEFINE_COUNTER(name) PRCounterHandle name
1.102 +
1.103 +/* -----------------------------------------------------------------------
1.104 +** FUNCTION: PR_INIT_COUNTER_HANDLE() -- Set the value of a PRCounterHandle
1.105 +**
1.106 +** DESCRIPTION:
1.107 +** PR_INIT_COUNTER_HANDLE() sets the value of a PRCounterHandle
1.108 +** to value.
1.109 +**
1.110 +*/
1.111 +#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
1.112 +#define PR_INIT_COUNTER_HANDLE(handle,value)\
1.113 + (handle) = (PRCounterHandle)(value)
1.114 +#else
1.115 +#define PR_INIT_COUNTER_HANDLE(handle,value)
1.116 +#endif
1.117 +
1.118 +/* -----------------------------------------------------------------------
1.119 +** FUNCTION: PR_CreateCounter() -- Create a counter
1.120 +**
1.121 +** DESCRIPTION: PR_CreateCounter() creates a counter object and
1.122 +** initializes it to zero.
1.123 +**
1.124 +** The macro form takes as its first argument the name of the
1.125 +** PRCounterHandle to receive the handle returned from
1.126 +** PR_CreateCounter().
1.127 +**
1.128 +** INPUTS:
1.129 +** qName: The QName for the counter object. The maximum length
1.130 +** of qName is defined by PRCOUNTER_NAME_MAX
1.131 +**
1.132 +** rName: The RName for the counter object. The maximum length
1.133 +** of qName is defined by PRCOUNTER_NAME_MAX
1.134 +**
1.135 +** descrioption: The description of the counter object. The
1.136 +** maximum length of description is defined by
1.137 +** PRCOUNTER_DESC_MAX.
1.138 +**
1.139 +** OUTPUTS:
1.140 +**
1.141 +** RETURNS:
1.142 +** PRCounterHandle.
1.143 +**
1.144 +** RESTRICTIONS:
1.145 +**
1.146 +*/
1.147 +#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
1.148 +#define PR_CREATE_COUNTER(handle,qName,rName,description)\
1.149 + (handle) = PR_CreateCounter((qName),(rName),(description))
1.150 +#else
1.151 +#define PR_CREATE_COUNTER(handle,qName,rName,description)
1.152 +#endif
1.153 +
1.154 +NSPR_API(PRCounterHandle)
1.155 + PR_CreateCounter(
1.156 + const char *qName,
1.157 + const char *rName,
1.158 + const char *description
1.159 +);
1.160 +
1.161 +/* -----------------------------------------------------------------------
1.162 +** FUNCTION: PR_DestroyCounter() -- Destroy a counter object.
1.163 +**
1.164 +** DESCRIPTION: PR_DestroyCounter() removes a counter and
1.165 +** unregisters its handle from the counter database.
1.166 +**
1.167 +** INPUTS:
1.168 +** handle: the PRCounterHandle of the counter to be destroyed.
1.169 +**
1.170 +** OUTPUTS:
1.171 +** The counter is destroyed.
1.172 +**
1.173 +** RETURNS: void
1.174 +**
1.175 +** RESTRICTIONS:
1.176 +**
1.177 +*/
1.178 +#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
1.179 +#define PR_DESTROY_COUNTER(handle) PR_DestroyCounter((handle))
1.180 +#else
1.181 +#define PR_DESTROY_COUNTER(handle)
1.182 +#endif
1.183 +
1.184 +NSPR_API(void)
1.185 + PR_DestroyCounter(
1.186 + PRCounterHandle handle
1.187 +);
1.188 +
1.189 +
1.190 +/* -----------------------------------------------------------------------
1.191 +** FUNCTION: PR_GetCounterHandleFromName() -- Retreive a
1.192 +** counter's handle give its name.
1.193 +**
1.194 +** DESCRIPTION: PR_GetCounterHandleFromName() retreives a
1.195 +** counter's handle from the counter database, given the name
1.196 +** the counter was originally created with.
1.197 +**
1.198 +** INPUTS:
1.199 +** qName: Counter's original QName.
1.200 +** rName: Counter's original RName.
1.201 +**
1.202 +** OUTPUTS:
1.203 +**
1.204 +** RETURNS:
1.205 +** PRCounterHandle or PRCounterError.
1.206 +**
1.207 +** RESTRICTIONS:
1.208 +**
1.209 +*/
1.210 +#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
1.211 +#define PR_GET_COUNTER_HANDLE_FROM_NAME(handle,qName,rName)\
1.212 + (handle) = PR_GetCounterHandleFromName((qName),(rName))
1.213 +#else
1.214 +#define PR_GET_COUNTER_HANDLE_FROM_NAME(handle,qName,rName)
1.215 +#endif
1.216 +
1.217 +NSPR_API(PRCounterHandle)
1.218 + PR_GetCounterHandleFromName(
1.219 + const char *qName,
1.220 + const char *rName
1.221 +);
1.222 +
1.223 +/* -----------------------------------------------------------------------
1.224 +** FUNCTION: PR_GetCounterNameFromHandle() -- Retreive a
1.225 +** counter's name, given its handle.
1.226 +**
1.227 +** DESCRIPTION: PR_GetCounterNameFromHandle() retreives a
1.228 +** counter's name given its handle.
1.229 +**
1.230 +** INPUTS:
1.231 +** qName: Where to store a pointer to qName.
1.232 +** rName: Where to store a pointer to rName.
1.233 +** description: Where to store a pointer to description.
1.234 +**
1.235 +** OUTPUTS: Pointers to the Counter Feature's copies of the names
1.236 +** used when the counters were created.
1.237 +**
1.238 +** RETURNS: void
1.239 +**
1.240 +** RESTRICTIONS:
1.241 +**
1.242 +*/
1.243 +#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
1.244 +#define PR_GET_COUNTER_NAME_FROM_HANDLE(handle,qName,rName,description)\
1.245 + PR_GetCounterNameFromHandle((handle),(qName),(rName),(description))
1.246 +#else
1.247 +#define PR_GET_COUNTER_NAME_FROM_HANDLE(handle,qName,rName,description )
1.248 +#endif
1.249 +
1.250 +NSPR_API(void)
1.251 + PR_GetCounterNameFromHandle(
1.252 + PRCounterHandle handle,
1.253 + const char **qName,
1.254 + const char **rName,
1.255 + const char **description
1.256 +);
1.257 +
1.258 +
1.259 +/* -----------------------------------------------------------------------
1.260 +** FUNCTION: PR_IncrementCounter() -- Add one to the referenced
1.261 +** counter.
1.262 +**
1.263 +** DESCRIPTION: Add one to the referenced counter.
1.264 +**
1.265 +** INPUTS:
1.266 +** handle: The PRCounterHandle of the counter to be incremented
1.267 +**
1.268 +** OUTPUTS: The counter is incrementd.
1.269 +**
1.270 +** RETURNS: void
1.271 +**
1.272 +** RESTRICTIONS:
1.273 +**
1.274 +*/
1.275 +#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
1.276 +#define PR_INCREMENT_COUNTER(handle) PR_IncrementCounter(handle)
1.277 +#else
1.278 +#define PR_INCREMENT_COUNTER(handle)
1.279 +#endif
1.280 +
1.281 +NSPR_API(void)
1.282 + PR_IncrementCounter(
1.283 + PRCounterHandle handle
1.284 +);
1.285 +
1.286 +
1.287 +/* -----------------------------------------------------------------------
1.288 +** FUNCTION: PR_DecrementCounter() -- Subtract one from the
1.289 +** referenced counter
1.290 +**
1.291 +** DESCRIPTION: Subtract one from the referenced counter.
1.292 +**
1.293 +** INPUTS:
1.294 +** handle: The PRCounterHandle of the coutner to be
1.295 +** decremented.
1.296 +**
1.297 +** OUTPUTS: the counter is decremented.
1.298 +**
1.299 +** RETURNS: void
1.300 +**
1.301 +** RESTRICTIONS:
1.302 +**
1.303 +*/
1.304 +#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
1.305 +#define PR_DECREMENT_COUNTER(handle) PR_DecrementCounter(handle)
1.306 +#else
1.307 +#define PR_DECREMENT_COUNTER(handle)
1.308 +#endif
1.309 +
1.310 +NSPR_API(void)
1.311 + PR_DecrementCounter(
1.312 + PRCounterHandle handle
1.313 +);
1.314 +
1.315 +/* -----------------------------------------------------------------------
1.316 +** FUNCTION: PR_AddToCounter() -- Add a value to a counter.
1.317 +**
1.318 +** DESCRIPTION: Add value to the counter referenced by handle.
1.319 +**
1.320 +** INPUTS:
1.321 +** handle: the PRCounterHandle of the counter to be added to.
1.322 +**
1.323 +** value: the value to be added to the counter.
1.324 +**
1.325 +** OUTPUTS: new value for counter.
1.326 +**
1.327 +** RETURNS: void
1.328 +**
1.329 +** RESTRICTIONS:
1.330 +**
1.331 +*/
1.332 +#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
1.333 +#define PR_ADD_TO_COUNTER(handle,value)\
1.334 + PR_AddToCounter((handle),(value))
1.335 +#else
1.336 +#define PR_ADD_TO_COUNTER(handle,value)
1.337 +#endif
1.338 +
1.339 +NSPR_API(void)
1.340 + PR_AddToCounter(
1.341 + PRCounterHandle handle,
1.342 + PRUint32 value
1.343 +);
1.344 +
1.345 +
1.346 +/* -----------------------------------------------------------------------
1.347 +** FUNCTION: PR_SubtractFromCounter() -- A value is subtracted
1.348 +** from a counter.
1.349 +**
1.350 +** DESCRIPTION:
1.351 +** Subtract a value from a counter.
1.352 +**
1.353 +** INPUTS:
1.354 +** handle: the PRCounterHandle of the counter to be subtracted
1.355 +** from.
1.356 +**
1.357 +** value: the value to be subtracted from the counter.
1.358 +**
1.359 +** OUTPUTS: new value for counter
1.360 +**
1.361 +** RETURNS: void
1.362 +**
1.363 +** RESTRICTIONS:
1.364 +**
1.365 +*/
1.366 +#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
1.367 +#define PR_SUBTRACT_FROM_COUNTER(handle,value)\
1.368 + PR_SubtractFromCounter((handle),(value))
1.369 +#else
1.370 +#define PR_SUBTRACT_FROM_COUNTER(handle,value)
1.371 +#endif
1.372 +
1.373 +NSPR_API(void)
1.374 + PR_SubtractFromCounter(
1.375 + PRCounterHandle handle,
1.376 + PRUint32 value
1.377 +);
1.378 +
1.379 +
1.380 +/* -----------------------------------------------------------------------
1.381 +** FUNCTION: PR_GetCounter() -- Retreive the value of a counter
1.382 +**
1.383 +** DESCRIPTION:
1.384 +** Retreive the value of a counter.
1.385 +**
1.386 +** INPUTS:
1.387 +** handle: the PR_CounterHandle of the counter to be retreived
1.388 +**
1.389 +** OUTPUTS:
1.390 +**
1.391 +** RETURNS: The value of the referenced counter
1.392 +**
1.393 +** RESTRICTIONS:
1.394 +**
1.395 +*/
1.396 +#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
1.397 +#define PR_GET_COUNTER(counter,handle)\
1.398 + (counter) = PR_GetCounter((handle))
1.399 +#else
1.400 +#define PR_GET_COUNTER(counter,handle) 0
1.401 +#endif
1.402 +
1.403 +NSPR_API(PRUint32)
1.404 + PR_GetCounter(
1.405 + PRCounterHandle handle
1.406 +);
1.407 +
1.408 +/* -----------------------------------------------------------------------
1.409 +** FUNCTION: PR_SetCounter() -- Replace the content of counter
1.410 +** with value.
1.411 +**
1.412 +** DESCRIPTION: The contents of the referenced counter are
1.413 +** replaced by value.
1.414 +**
1.415 +** INPUTS:
1.416 +** handle: the PRCounterHandle of the counter whose contents
1.417 +** are to be replaced.
1.418 +**
1.419 +** value: the new value of the counter.
1.420 +**
1.421 +** OUTPUTS:
1.422 +**
1.423 +** RETURNS: void
1.424 +**
1.425 +** RESTRICTIONS:
1.426 +**
1.427 +*/
1.428 +#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
1.429 +#define PR_SET_COUNTER(handle,value) PR_SetCounter((handle),(value))
1.430 +#else
1.431 +#define PR_SET_COUNTER(handle,value)
1.432 +#endif
1.433 +
1.434 +NSPR_API(void)
1.435 + PR_SetCounter(
1.436 + PRCounterHandle handle,
1.437 + PRUint32 value
1.438 +);
1.439 +
1.440 +
1.441 +/* -----------------------------------------------------------------------
1.442 +** FUNCTION: PR_FindNextCounterQname() -- Retreive the next QName counter
1.443 +** handle iterator
1.444 +**
1.445 +** DESCRIPTION:
1.446 +** PR_FindNextCounterQname() retreives the first or next Qname
1.447 +** the counter data base, depending on the value of handle. When
1.448 +** handle is NULL, the function attempts to retreive the first
1.449 +** QName handle in the database. When handle is a handle previosly
1.450 +** retreived QName handle, then the function attempts to retreive
1.451 +** the next QName handle.
1.452 +**
1.453 +** INPUTS:
1.454 +** handle: PRCounterHandle or NULL.
1.455 +**
1.456 +** OUTPUTS: returned
1.457 +**
1.458 +** RETURNS: PRCounterHandle or NULL when no more QName counter
1.459 +** handles are present.
1.460 +**
1.461 +** RESTRICTIONS:
1.462 +** A concurrent PR_CreateCounter() or PR_DestroyCounter() may
1.463 +** cause unpredictable results.
1.464 +**
1.465 +** A PRCounterHandle returned from this function may only be used
1.466 +** in another PR_FindNextCounterQname() function call; other
1.467 +** operations may cause unpredictable results.
1.468 +**
1.469 +*/
1.470 +#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
1.471 +#define PR_FIND_NEXT_COUNTER_QNAME(next,handle)\
1.472 + (next) = PR_FindNextCounterQname((handle))
1.473 +#else
1.474 +#define PR_FIND_NEXT_COUNTER_QNAME(next,handle) NULL
1.475 +#endif
1.476 +
1.477 +NSPR_API(PRCounterHandle)
1.478 + PR_FindNextCounterQname(
1.479 + PRCounterHandle handle
1.480 +);
1.481 +
1.482 +/* -----------------------------------------------------------------------
1.483 +** FUNCTION: PR_FindNextCounterRname() -- Retreive the next RName counter
1.484 +** handle iterator
1.485 +**
1.486 +** DESCRIPTION:
1.487 +** PR_FindNextCounterRname() retreives the first or next RNname
1.488 +** handle from the counter data base, depending on the
1.489 +** value of handle. When handle is NULL, the function attempts to
1.490 +** retreive the first RName handle in the database. When handle is
1.491 +** a handle previosly retreived RName handle, then the function
1.492 +** attempts to retreive the next RName handle.
1.493 +**
1.494 +** INPUTS:
1.495 +** handle: PRCounterHandle or NULL.
1.496 +** qhandle: PRCounterHandle of a previously aquired via
1.497 +** PR_FIND_NEXT_QNAME_HANDLE()
1.498 +**
1.499 +** OUTPUTS: returned
1.500 +**
1.501 +** RETURNS: PRCounterHandle or NULL when no more RName counter
1.502 +** handles are present.
1.503 +**
1.504 +** RESTRICTIONS:
1.505 +** A concurrent PR_CreateCounter() or PR_DestroyCounter() may
1.506 +** cause unpredictable results.
1.507 +**
1.508 +** A PRCounterHandle returned from this function may only be used
1.509 +** in another PR_FindNextCounterRname() function call; other
1.510 +** operations may cause unpredictable results.
1.511 +**
1.512 +*/
1.513 +#if defined(DEBUG) || defined(FORCE_NSPR_COUNTERS)
1.514 +#define PR_FIND_NEXT_COUNTER_RNAME(next,rhandle,qhandle)\
1.515 + (next) = PR_FindNextCounterRname((rhandle),(qhandle))
1.516 +#else
1.517 +#define PR_FIND_NEXT_COUNTER_RNAME(next,rhandle,qhandle)
1.518 +#endif
1.519 +
1.520 +NSPR_API(PRCounterHandle)
1.521 + PR_FindNextCounterRname(
1.522 + PRCounterHandle rhandle,
1.523 + PRCounterHandle qhandle
1.524 +);
1.525 +
1.526 +PR_END_EXTERN_C
1.527 +
1.528 +#endif /* prcountr_h___ */
