2 This file is part of GNUnet
3 Copyright (C) 2009-2013, 2016 GNUnet e.V.
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your 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 Affero General Public License for more details.
17 * @author Christian Grothoff
20 * API to create, modify and access statistics.
22 * @defgroup statistics Statistics service
23 * Track statistics or provide access to statistics.
25 * Create, modify and access statistics about the operation of GNUnet.
27 * All statistical values must be of type `unsigned long long`.
29 * @see [Documentation](https://gnunet.org/gnunet-statistics-subsystem)
34 #ifndef GNUNET_STATISTICS_SERVICE_H
35 #define GNUNET_STATISTICS_SERVICE_H
40 #if 0 /* keep Emacsens' auto-indent happy */
45 #include "gnunet_util_lib.h"
48 * Version of the statistics API.
50 #define GNUNET_STATISTICS_VERSION 0x00000000
53 * Opaque handle for the statistics service.
55 struct GNUNET_STATISTICS_Handle;
58 * Callback function to process statistic values.
61 * @param subsystem name of subsystem that created the statistic
62 * @param name the name of the datum
63 * @param value the current value
64 * @param is_persistent #GNUNET_YES if the value is persistent, #GNUNET_NO if not
65 * @return #GNUNET_OK to continue, #GNUNET_SYSERR to abort iteration
68 (*GNUNET_STATISTICS_Iterator) (void *cls,
69 const char *subsystem,
76 * Get handle for the statistics service.
78 * @param subsystem name of subsystem using the service
79 * @param cfg services configuration in use
80 * @return handle to use
82 struct GNUNET_STATISTICS_Handle *
83 GNUNET_STATISTICS_create (const char *subsystem,
84 const struct GNUNET_CONFIGURATION_Handle *cfg);
88 * Destroy a handle (free all state associated with it).
90 * @param h statistics handle to destroy
91 * @param sync_first set to #GNUNET_YES if pending SET requests should
95 GNUNET_STATISTICS_destroy (struct GNUNET_STATISTICS_Handle *h,
100 * Watch statistics from the peer (be notified whenever they change).
102 * @param handle identification of the statistics service
103 * @param subsystem limit to the specified subsystem, never NULL
104 * @param name name of the statistic value, never NULL
105 * @param proc function to call on each value
106 * @param proc_cls closure for @a proc
107 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
110 GNUNET_STATISTICS_watch (struct GNUNET_STATISTICS_Handle *handle,
111 const char *subsystem,
113 GNUNET_STATISTICS_Iterator proc,
118 * Stop watching statistics from the peer.
120 * @param handle identification of the statistics service
121 * @param subsystem limit to the specified subsystem, never NULL
122 * @param name name of the statistic value, never NULL
123 * @param proc function to call on each value
124 * @param proc_cls closure for @a proc
125 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error (no such watch)
128 GNUNET_STATISTICS_watch_cancel (struct GNUNET_STATISTICS_Handle *handle,
129 const char *subsystem,
131 GNUNET_STATISTICS_Iterator proc,
136 * Continuation called by #GNUNET_STATISTICS_get() functions.
139 * @param success #GNUNET_OK if statistics were
140 * successfully obtained, #GNUNET_SYSERR if not.
143 (*GNUNET_STATISTICS_Callback) (void *cls,
148 * Handle that can be used to cancel a statistics 'get' operation.
150 struct GNUNET_STATISTICS_GetHandle;
154 * Get statistic from the peer.
156 * @param handle identification of the statistics service
157 * @param subsystem limit to the specified subsystem, NULL for all subsystems
158 * @param name name of the statistic value, NULL for all values
159 * @param cont continuation to call when done (can be NULL)
160 * This callback CANNOT destroy the statistics handle in the same call.
161 * @param proc function to call on each value
162 * @param cls closure for @a proc and @a cont
163 * @return NULL on error
165 struct GNUNET_STATISTICS_GetHandle *
166 GNUNET_STATISTICS_get (struct GNUNET_STATISTICS_Handle *handle,
167 const char *subsystem,
169 GNUNET_STATISTICS_Callback cont,
170 GNUNET_STATISTICS_Iterator proc,
175 * Cancel a #GNUNET_STATISTICS_get request. Must be called before the 'cont'
176 * function is called.
178 * @param gh handle of the request to cancel
181 GNUNET_STATISTICS_get_cancel (struct GNUNET_STATISTICS_GetHandle *gh);
185 * Set statistic value for the peer. Will always use our
186 * subsystem (the argument used when @a handle was created).
188 * @param handle identification of the statistics service
189 * @param name name of the statistic value
190 * @param value new value to set
191 * @param make_persistent should the value be kept across restarts?
194 GNUNET_STATISTICS_set (struct GNUNET_STATISTICS_Handle *handle,
197 int make_persistent);
201 * Set statistic value for the peer. Will always use our
202 * subsystem (the argument used when @a handle was created).
204 * @param handle identification of the statistics service
205 * @param name name of the statistic value
206 * @param delta change in value (added to existing value)
207 * @param make_persistent should the value be kept across restarts?
210 GNUNET_STATISTICS_update (struct GNUNET_STATISTICS_Handle *handle,
213 int make_persistent);
217 #if 0 /* keep Emacsens' auto-indent happy */
224 /** @} */ /* end of group statistics */