2 This file is part of GNUnet
3 Copyright (C) 2009-2013 GNUnet e.V.
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., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
22 * @author Christian Grothoff
25 * API to create, modify and access statistics.
27 * @defgroup statistics Statistics service
28 * Track statistics or provide access to statistics.
30 * Create, modify and access statistics about the operation of GNUnet.
32 * All statistical values must be of type `unsigned long long`.
34 * @see [Documentation](https://gnunet.org/gnunet-statistics-subsystem)
39 #ifndef GNUNET_STATISTICS_SERVICE_H
40 #define GNUNET_STATISTICS_SERVICE_H
45 #if 0 /* keep Emacsens' auto-indent happy */
50 #include "gnunet_util_lib.h"
53 * Version of the statistics API.
55 #define GNUNET_STATISTICS_VERSION 0x00000000
58 * Opaque handle for the statistics service.
60 struct GNUNET_STATISTICS_Handle;
63 * Callback function to process statistic values.
66 * @param subsystem name of subsystem that created the statistic
67 * @param name the name of the datum
68 * @param value the current value
69 * @param is_persistent #GNUNET_YES if the value is persistent, #GNUNET_NO if not
70 * @return #GNUNET_OK to continue, #GNUNET_SYSERR to abort iteration
73 (*GNUNET_STATISTICS_Iterator) (void *cls,
74 const char *subsystem,
81 * Get handle for the statistics service.
83 * @param subsystem name of subsystem using the service
84 * @param cfg services configuration in use
85 * @return handle to use
87 struct GNUNET_STATISTICS_Handle *
88 GNUNET_STATISTICS_create (const char *subsystem,
89 const struct GNUNET_CONFIGURATION_Handle *cfg);
93 * Destroy a handle (free all state associated with it).
95 * @param h statistics handle to destroy
96 * @param sync_first set to #GNUNET_YES if pending SET requests should
100 GNUNET_STATISTICS_destroy (struct GNUNET_STATISTICS_Handle *h,
105 * Watch statistics from the peer (be notified whenever they change).
107 * @param handle identification of the statistics service
108 * @param subsystem limit to the specified subsystem, never NULL
109 * @param name name of the statistic value, never NULL
110 * @param proc function to call on each value
111 * @param proc_cls closure for @a proc
112 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
115 GNUNET_STATISTICS_watch (struct GNUNET_STATISTICS_Handle *handle,
116 const char *subsystem,
118 GNUNET_STATISTICS_Iterator proc,
123 * Stop watching statistics from the peer.
125 * @param handle identification of the statistics service
126 * @param subsystem limit to the specified subsystem, never NULL
127 * @param name name of the statistic value, never NULL
128 * @param proc function to call on each value
129 * @param proc_cls closure for @a proc
130 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error (no such watch)
133 GNUNET_STATISTICS_watch_cancel (struct GNUNET_STATISTICS_Handle *handle,
134 const char *subsystem,
136 GNUNET_STATISTICS_Iterator proc,
141 * Continuation called by #GNUNET_STATISTICS_get functions.
144 * @param success #GNUNET_OK if statistics were
145 * successfully obtained, #GNUNET_SYSERR if not.
147 typedef void (*GNUNET_STATISTICS_Callback) (void *cls,
152 * Handle that can be used to cancel a statistics 'get' operation.
154 struct GNUNET_STATISTICS_GetHandle;
158 * Get statistic from the peer.
160 * @param handle identification of the statistics service
161 * @param subsystem limit to the specified subsystem, NULL for all subsystems
162 * @param name name of the statistic value, NULL for all values
163 * @param timeout after how long should we give up (and call
164 * notify with buf NULL and size 0)?
165 * @param cont continuation to call when done (can be NULL)
166 * This callback CANNOT destroy the statistics handle in the same call.
167 * @param proc function to call on each value
168 * @param cls closure for @a proc and @a cont
169 * @return NULL on error
171 struct GNUNET_STATISTICS_GetHandle *
172 GNUNET_STATISTICS_get (struct GNUNET_STATISTICS_Handle *handle,
173 const char *subsystem,
175 struct GNUNET_TIME_Relative timeout,
176 GNUNET_STATISTICS_Callback cont,
177 GNUNET_STATISTICS_Iterator proc, void *cls);
181 * Cancel a #GNUNET_STATISTICS_get request. Must be called before the 'cont'
182 * function is called.
184 * @param gh handle of the request to cancel
187 GNUNET_STATISTICS_get_cancel (struct GNUNET_STATISTICS_GetHandle *gh);
191 * Set statistic value for the peer. Will always use our
192 * subsystem (the argument used when @a handle was created).
194 * @param handle identification of the statistics service
195 * @param name name of the statistic value
196 * @param value new value to set
197 * @param make_persistent should the value be kept across restarts?
200 GNUNET_STATISTICS_set (struct GNUNET_STATISTICS_Handle *handle,
203 int make_persistent);
207 * Set statistic value for the peer. Will always use our
208 * subsystem (the argument used when @a handle was created).
210 * @param handle identification of the statistics service
211 * @param name name of the statistic value
212 * @param delta change in value (added to existing value)
213 * @param make_persistent should the value be kept across restarts?
216 GNUNET_STATISTICS_update (struct GNUNET_STATISTICS_Handle *handle,
219 int make_persistent);
223 #if 0 /* keep Emacsens' auto-indent happy */
230 /** @} */ /* end of group statistics */