← Back to branch summary

~ubuntu-branches/ubuntu/precise/kompozer/precise

« back to all changes in this revision

Viewing changes to mozilla/nsprpub/pr/include/prcountr.h

  • Committer: Bazaar Package Importer
  • Author(s): Anthony Yarusso
  • Date: 2007-08-27 01:11:03 UTC
  • Revision ID: james.westby@ubuntu.com-20070827011103-2jgf4s6532gqu2ka
Tags: upstream-0.7.10
Import upstream version 0.7.10

Show diffs side-by-side

added added

removed removed

Lines of Context:
mozilla/nsprpub/pr/include/prcountr.h
 
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___ */