contrib/bind-9.5.2/lib/isc/include/isc/stats.h

   1 /*
   2  * Copyright (C) 2009  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: stats.h,v 1.4.4.2 2009/01/29 23:47:14 tbox Exp $ */
  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
  26 ISC_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  */
  36 typedef void (*isc_stats_dumper_t)(isc_statscounter_t, isc_uint64_t, void *);
  37
  38 isc_result_t
  39 isc_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
  55 void
  56 isc_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
  66 void
  67 isc_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
  75 int
  76 isc_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
  85 void
  86 isc_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
  97 void
  98 isc_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
 106 void
 107 isc_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
 119 ISC_LANG_ENDDECLS
 120
 121 #endif /* ISC_STATS_H */