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