2 This file is part of GNUnet
3 (C) 2009, 2010 Christian Grothoff (and other contributing authors)
5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 2, or (at your
8 option) any later version.
10 GNUnet is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
22 * @file include/gnunet_statistics_service.h
23 * @brief API to create, modify and access statistics about
24 * the operation of GNUnet; all statistical values
25 * must be of type "unsigned long long".
26 * @author Christian Grothoff
29 #ifndef GNUNET_STATISTICS_SERVICE_H
30 #define GNUNET_STATISTICS_SERVICE_H
35 #if 0 /* keep Emacsens' auto-indent happy */
40 #include "gnunet_common.h"
41 #include "gnunet_configuration_lib.h"
42 #include "gnunet_scheduler_lib.h"
45 * Version of the statistics API.
47 #define GNUNET_STATISTICS_VERSION 0x00000000
50 * Opaque handle for the statistics service.
52 struct GNUNET_STATISTICS_Handle;
55 * Callback function to process statistic values.
58 * @param subsystem name of subsystem that created the statistic
59 * @param name the name of the datum
60 * @param value the current value
61 * @param is_persistent GNUNET_YES if the value is persistent, GNUNET_NO if not
62 * @return GNUNET_OK to continue, GNUNET_SYSERR to abort iteration
64 typedef int (*GNUNET_STATISTICS_Iterator) (void *cls,
65 const char *subsystem,
71 * Get handle for the statistics service.
73 * @param sched scheduler to use
74 * @param subsystem name of subsystem using the service
75 * @param cfg services configuration in use
76 * @return handle to use
78 struct GNUNET_STATISTICS_Handle
79 *GNUNET_STATISTICS_create (struct GNUNET_SCHEDULER_Handle *sched,
80 const char *subsystem,
81 const struct GNUNET_CONFIGURATION_Handle *cfg);
85 * Destroy a handle (free all state associated with
88 * @param h statistics handle to destroy
89 * @param sync_first set to GNUNET_YES if pending SET requests should
92 void GNUNET_STATISTICS_destroy (struct GNUNET_STATISTICS_Handle *h,
97 * Watch statistics from the peer (be notified whenever they change).
98 * Note that the only way to cancel a "watch" request is to destroy
99 * the statistics handle given as the first argument to this call.
101 * @param handle identification of the statistics service
102 * @param subsystem limit to the specified subsystem, never NULL
103 * @param name name of the statistic value, never NULL
104 * @param proc function to call on each value
105 * @param proc_cls closure for proc
106 * @return GNUNET_OK on success, GNUNET_SYSERR on error
109 GNUNET_STATISTICS_watch (struct GNUNET_STATISTICS_Handle *handle,
110 const char *subsystem,
112 GNUNET_STATISTICS_Iterator proc,
117 * Continuation called by the "get_all" and "get" functions.
120 * @param success GNUNET_OK if statistics were
121 * successfully obtained, GNUNET_SYSERR if not.
123 typedef void (*GNUNET_STATISTICS_Callback) (void *cls, int success);
126 * Handle that can be used to cancel a statistics 'get' operation.
128 struct GNUNET_STATISTICS_GetHandle;
131 * Get statistic from the peer.
133 * @param handle identification of the statistics service
134 * @param subsystem limit to the specified subsystem, NULL for our subsystem
135 * @param name name of the statistic value, NULL for all values
136 * @param timeout after how long should we give up (and call
137 * notify with buf NULL and size 0)?
138 * @param cont continuation to call when done (can be NULL)
139 * @param proc function to call on each value
140 * @param cls closure for proc and cont
141 * @return NULL on error
143 struct GNUNET_STATISTICS_GetHandle *
144 GNUNET_STATISTICS_get (struct GNUNET_STATISTICS_Handle *handle,
145 const char *subsystem,
147 struct GNUNET_TIME_Relative timeout,
148 GNUNET_STATISTICS_Callback cont,
149 GNUNET_STATISTICS_Iterator proc, void *cls);
153 * Cancel a 'get' request. Must be called before the 'cont'
154 * function is called.
156 * @param gh handle of the request to cancel
159 GNUNET_STATISTICS_get_cancel (struct GNUNET_STATISTICS_GetHandle *gh);
163 * Set statistic value for the peer. Will always use our
164 * subsystem (the argument used when "handle" was created).
166 * @param handle identification of the statistics service
167 * @param name name of the statistic value
168 * @param value new value to set
169 * @param make_persistent should the value be kept across restarts?
172 GNUNET_STATISTICS_set (struct GNUNET_STATISTICS_Handle *handle,
174 uint64_t value, int make_persistent);
177 * Set statistic value for the peer. Will always use our
178 * subsystem (the argument used when "handle" was created).
180 * @param handle identification of the statistics service
181 * @param name name of the statistic value
182 * @param delta change in value (added to existing value)
183 * @param make_persistent should the value be kept across restarts?
186 GNUNET_STATISTICS_update (struct GNUNET_STATISTICS_Handle *handle,
188 int64_t delta, int make_persistent);
192 #if 0 /* keep Emacsens' auto-indent happy */