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___ */ 555