2 This file is part of GNUnet
3 (C) 2009-2013 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 3, 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
27 * @defgroup statistics track statistics or provide access to statistics
31 #ifndef GNUNET_STATISTICS_SERVICE_H
32 #define GNUNET_STATISTICS_SERVICE_H
37 #if 0 /* keep Emacsens' auto-indent happy */
42 #include "gnunet_common.h"
43 #include "gnunet_configuration_lib.h"
44 #include "gnunet_scheduler_lib.h"
47 * Version of the statistics API.
49 #define GNUNET_STATISTICS_VERSION 0x00000000
52 * Opaque handle for the statistics service.
54 struct GNUNET_STATISTICS_Handle;
57 * Callback function to process statistic values.
60 * @param subsystem name of subsystem that created the statistic
61 * @param name the name of the datum
62 * @param value the current value
63 * @param is_persistent #GNUNET_YES if the value is persistent, #GNUNET_NO if not
64 * @return #GNUNET_OK to continue, #GNUNET_SYSERR to abort iteration
66 typedef int (*GNUNET_STATISTICS_Iterator) (void *cls, const char *subsystem,
67 const char *name, uint64_t value,
71 * Get handle for the statistics service.
73 * @param subsystem name of subsystem using the service
74 * @param cfg services configuration in use
75 * @return handle to use
77 struct GNUNET_STATISTICS_Handle *
78 GNUNET_STATISTICS_create (const char *subsystem,
79 const struct GNUNET_CONFIGURATION_Handle *cfg);
83 * Destroy a handle (free all state associated with
86 * @param h statistics handle to destroy
87 * @param sync_first set to #GNUNET_YES if pending SET requests should
91 GNUNET_STATISTICS_destroy (struct GNUNET_STATISTICS_Handle *h, int sync_first);
95 * Watch statistics from the peer (be notified whenever they change).
97 * @param handle identification of the statistics service
98 * @param subsystem limit to the specified subsystem, never NULL
99 * @param name name of the statistic value, never NULL
100 * @param proc function to call on each value
101 * @param proc_cls closure for @a proc
102 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
105 GNUNET_STATISTICS_watch (struct GNUNET_STATISTICS_Handle *handle,
106 const char *subsystem, const char *name,
107 GNUNET_STATISTICS_Iterator proc, void *proc_cls);
111 * Stop watching statistics from the peer.
113 * @param handle identification of the statistics service
114 * @param subsystem limit to the specified subsystem, never NULL
115 * @param name name of the statistic value, never NULL
116 * @param proc function to call on each value
117 * @param proc_cls closure for @a proc
118 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error (no such watch)
121 GNUNET_STATISTICS_watch_cancel (struct GNUNET_STATISTICS_Handle *handle,
122 const char *subsystem, const char *name,
123 GNUNET_STATISTICS_Iterator proc, void *proc_cls);
127 * Continuation called by #GNUNET_STATISTICS_get functions.
130 * @param success #GNUNET_OK if statistics were
131 * successfully obtained, #GNUNET_SYSERR if not.
133 typedef void (*GNUNET_STATISTICS_Callback) (void *cls, int success);
137 * Handle that can be used to cancel a statistics 'get' operation.
139 struct GNUNET_STATISTICS_GetHandle;
143 * Get statistic from the peer.
145 * @param handle identification of the statistics service
146 * @param subsystem limit to the specified subsystem, NULL for all subsystems
147 * @param name name of the statistic value, NULL for all values
148 * @param timeout after how long should we give up (and call
149 * notify with buf NULL and size 0)?
150 * @param cont continuation to call when done (can be NULL)
151 * This callback CANNOT destroy the statistics handle in the same call.
152 * @param proc function to call on each value
153 * @param cls closure for @a proc and @a cont
154 * @return NULL on error
156 struct GNUNET_STATISTICS_GetHandle *
157 GNUNET_STATISTICS_get (struct GNUNET_STATISTICS_Handle *handle,
158 const char *subsystem, const char *name,
159 struct GNUNET_TIME_Relative timeout,
160 GNUNET_STATISTICS_Callback cont,
161 GNUNET_STATISTICS_Iterator proc, void *cls);
165 * Cancel a #GNUNET_STATISTICS_get request. Must be called before the 'cont'
166 * function is called.
168 * @param gh handle of the request to cancel
171 GNUNET_STATISTICS_get_cancel (struct GNUNET_STATISTICS_GetHandle *gh);
175 * Set statistic value for the peer. Will always use our
176 * subsystem (the argument used when @a handle was created).
178 * @param handle identification of the statistics service
179 * @param name name of the statistic value
180 * @param value new value to set
181 * @param make_persistent should the value be kept across restarts?
184 GNUNET_STATISTICS_set (struct GNUNET_STATISTICS_Handle *handle,
185 const char *name, uint64_t value, int make_persistent);
189 * Set statistic value for the peer. Will always use our
190 * subsystem (the argument used when @a handle was created).
192 * @param handle identification of the statistics service
193 * @param name name of the statistic value
194 * @param delta change in value (added to existing value)
195 * @param make_persistent should the value be kept across restarts?
198 GNUNET_STATISTICS_update (struct GNUNET_STATISTICS_Handle *handle,
199 const char *name, int64_t delta, int make_persistent);
203 #if 0 /* keep Emacsens' auto-indent happy */
210 /** @} */ /* end of group statistics */