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 106PR_BEGIN_EXTERN_C 107 108/* 109** Opaque counter handle type. 110** ... don't even think of looking in here. 111** 112*/ 113typedef 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 180NSPR_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 210NSPR_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 243NSPR_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 276NSPR_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 307NSPR_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 336NSPR_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 365NSPR_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 399NSPR_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 429NSPR_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 460NSPR_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 503NSPR_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 546NSPR_API(PRCounterHandle) 547 PR_FindNextCounterRname( 548 PRCounterHandle rhandle, 549 PRCounterHandle qhandle 550); 551 552PR_END_EXTERN_C 553 554#endif /* prcountr_h___ */ 555