stats.h revision 290001 
1/*
2 * Copyright (C) 2009, 2012  Internet Systems Consortium, Inc. ("ISC")
3 *
4 * Permission to use, copy, modify, and/or distribute this software for any
5 * purpose with or without fee is hereby granted, provided that the above
6 * copyright notice and this permission notice appear in all copies.
7 *
8 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
9 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
10 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
11 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
12 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
13 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
14 * PERFORMANCE OF THIS SOFTWARE.
15 */
16
17/* $Id$ */
18
19#ifndef ISC_STATS_H
20#define ISC_STATS_H 1
21
22/*! \file isc/stats.h */
23
24#include <isc/types.h>
25
26ISC_LANG_BEGINDECLS
27
28/*%<
29 * Flag(s) for isc_stats_dump().
30 */
31#define ISC_STATSDUMP_VERBOSE	0x00000001 /*%< dump 0-value counters */
32
33/*%<
34 * Dump callback type.
35 */
36typedef void (*isc_stats_dumper_t)(isc_statscounter_t, isc_uint64_t, void *);
37
38isc_result_t
39isc_stats_create(isc_mem_t *mctx, isc_stats_t **statsp, int ncounters);
40/*%<
41 * Create a statistics counter structure of general type.  It counts a general
42 * set of counters indexed by an ID between 0 and ncounters -1.
43 *
44 * Requires:
45 *\li	'mctx' must be a valid memory context.
46 *
47 *\li	'statsp' != NULL && '*statsp' == NULL.
48 *
49 * Returns:
50 *\li	ISC_R_SUCCESS	-- all ok
51 *
52 *\li	anything else	-- failure
53 */
54
55void
56isc_stats_attach(isc_stats_t *stats, isc_stats_t **statsp);
57/*%<
58 * Attach to a statistics set.
59 *
60 * Requires:
61 *\li	'stats' is a valid isc_stats_t.
62 *
63 *\li	'statsp' != NULL && '*statsp' == NULL
64 */
65
66void
67isc_stats_detach(isc_stats_t **statsp);
68/*%<
69 * Detaches from the statistics set.
70 *
71 * Requires:
72 *\li	'statsp' != NULL and '*statsp' is a valid isc_stats_t.
73 */
74
75int
76isc_stats_ncounters(isc_stats_t *stats);
77/*%<
78 * Returns the number of counters contained in stats.
79 *
80 * Requires:
81 *\li	'stats' is a valid isc_stats_t.
82 *
83 */
84
85void
86isc_stats_increment(isc_stats_t *stats, isc_statscounter_t counter);
87/*%<
88 * Increment the counter-th counter of stats.
89 *
90 * Requires:
91 *\li	'stats' is a valid isc_stats_t.
92 *
93 *\li	counter is less than the maximum available ID for the stats specified
94 *	on creation.
95 */
96
97void
98isc_stats_decrement(isc_stats_t *stats, isc_statscounter_t counter);
99/*%<
100 * Decrement the counter-th counter of stats.
101 *
102 * Requires:
103 *\li	'stats' is a valid isc_stats_t.
104 */
105
106void
107isc_stats_dump(isc_stats_t *stats, isc_stats_dumper_t dump_fn, void *arg,
108	       unsigned int options);
109/*%<
110 * Dump the current statistics counters in a specified way.  For each counter
111 * in stats, dump_fn is called with its current value and the given argument
112 * arg.  By default counters that have a value of 0 is skipped; if options has
113 * the ISC_STATSDUMP_VERBOSE flag, even such counters are dumped.
114 *
115 * Requires:
116 *\li	'stats' is a valid isc_stats_t.
117 */
118
119ISC_LANG_ENDDECLS
120
121#endif /* ISC_STATS_H */
122