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