gnunet_statistics_service.h (7084B)
1 /* 2 This file is part of GNUnet 3 Copyright (C) 2009-2013, 2016 GNUnet e.V. 4 5 GNUnet is free software: you can redistribute it and/or modify it 6 under the terms of the GNU Affero 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. 9 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. 14 15 You should have received a copy of the GNU Affero General Public License 16 along with this program. If not, see <http://www.gnu.org/licenses/>. 17 18 SPDX-License-Identifier: AGPL3.0-or-later 19 */ 20 21 /** 22 * @addtogroup Backbone 23 * @{ 24 * 25 * @author Christian Grothoff 26 * 27 * @file 28 * API to create, modify and access statistics. 29 * 30 * @defgroup statistics Statistics service 31 * Track statistics or provide access to statistics. 32 * 33 * Create, modify and access statistics about the operation of GNUnet. 34 * 35 * All statistical values must be of type `unsigned long long`. 36 * 37 * @see [Documentation](https://gnunet.org/gnunet-statistics-subsystem) 38 * 39 * @{ 40 */ 41 42 #ifndef GNUNET_STATISTICS_SERVICE_H 43 #define GNUNET_STATISTICS_SERVICE_H 44 45 #ifdef __cplusplus 46 extern "C" 47 { 48 #if 0 /* keep Emacsens' auto-indent happy */ 49 } 50 #endif 51 #endif 52 53 54 #include "gnunet_util_lib.h" 55 56 /** 57 * Version of the statistics API. 58 */ 59 #define GNUNET_STATISTICS_VERSION 0x00000000 60 61 /** 62 * Opaque handle for the statistics service. 63 */ 64 struct GNUNET_STATISTICS_Handle; 65 66 /** 67 * Callback function to process statistic values. 68 * 69 * @param cls closure 70 * @param subsystem name of subsystem that created the statistic 71 * @param name the name of the datum 72 * @param value the current value 73 * @param is_persistent #GNUNET_YES if the value is persistent, #GNUNET_NO if not 74 * @return #GNUNET_OK to continue, #GNUNET_SYSERR to abort iteration 75 */ 76 typedef int 77 (*GNUNET_STATISTICS_Iterator) (void *cls, 78 const char *subsystem, 79 const char *name, 80 uint64_t value, 81 int is_persistent); 82 83 84 /** 85 * Get handle for the statistics service. 86 * 87 * @param subsystem name of subsystem using the service 88 * @param cfg services configuration in use 89 * @return handle to use 90 */ 91 struct GNUNET_STATISTICS_Handle * 92 GNUNET_STATISTICS_create (const char *subsystem, 93 const struct GNUNET_CONFIGURATION_Handle *cfg); 94 95 96 /** 97 * Destroy a handle (free all state associated with it). 98 * 99 * @param h statistics handle to destroy 100 * @param sync_first set to #GNUNET_YES if pending SET requests should 101 * be completed 102 */ 103 void 104 GNUNET_STATISTICS_destroy (struct GNUNET_STATISTICS_Handle *h, 105 int sync_first); 106 107 108 /** 109 * Watch statistics from the peer (be notified whenever they change). 110 * 111 * @param handle identification of the statistics service 112 * @param subsystem limit to the specified subsystem, never NULL 113 * @param name name of the statistic value, never NULL 114 * @param proc function to call on each value 115 * @param proc_cls closure for @a proc 116 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error 117 */ 118 int 119 GNUNET_STATISTICS_watch (struct GNUNET_STATISTICS_Handle *handle, 120 const char *subsystem, 121 const char *name, 122 GNUNET_STATISTICS_Iterator proc, 123 void *proc_cls); 124 125 126 /** 127 * Stop watching statistics from the peer. 128 * 129 * @param handle identification of the statistics service 130 * @param subsystem limit to the specified subsystem, never NULL 131 * @param name name of the statistic value, never NULL 132 * @param proc function to call on each value 133 * @param proc_cls closure for @a proc 134 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error (no such watch) 135 */ 136 int 137 GNUNET_STATISTICS_watch_cancel (struct GNUNET_STATISTICS_Handle *handle, 138 const char *subsystem, 139 const char *name, 140 GNUNET_STATISTICS_Iterator proc, 141 void *proc_cls); 142 143 144 /** 145 * Continuation called by #GNUNET_STATISTICS_get() functions. 146 * 147 * @param cls closure 148 * @param success #GNUNET_OK if statistics were 149 * successfully obtained, #GNUNET_SYSERR if not. 150 */ 151 typedef void 152 (*GNUNET_STATISTICS_Callback) (void *cls, 153 int success); 154 155 156 /** 157 * Handle that can be used to cancel a statistics 'get' operation. 158 */ 159 struct GNUNET_STATISTICS_GetHandle; 160 161 162 /** 163 * Get statistic from the peer. 164 * 165 * @param handle identification of the statistics service 166 * @param subsystem limit to the specified subsystem, NULL for all subsystems 167 * @param name name of the statistic value, NULL for all values 168 * @param cont continuation to call when done (can be NULL) 169 * This callback CANNOT destroy the statistics handle in the same call. 170 * @param proc function to call on each value 171 * @param cls closure for @a proc and @a cont 172 * @return NULL on error 173 */ 174 struct GNUNET_STATISTICS_GetHandle * 175 GNUNET_STATISTICS_get (struct GNUNET_STATISTICS_Handle *handle, 176 const char *subsystem, 177 const char *name, 178 GNUNET_STATISTICS_Callback cont, 179 GNUNET_STATISTICS_Iterator proc, 180 void *cls); 181 182 183 /** 184 * Cancel a #GNUNET_STATISTICS_get request. Must be called before the 'cont' 185 * function is called. 186 * 187 * @param gh handle of the request to cancel 188 */ 189 void 190 GNUNET_STATISTICS_get_cancel (struct GNUNET_STATISTICS_GetHandle *gh); 191 192 193 /** 194 * Set statistic value for the peer. Will always use our 195 * subsystem (the argument used when @a handle was created). 196 * 197 * @param handle identification of the statistics service 198 * @param name name of the statistic value 199 * @param value new value to set 200 * @param make_persistent should the value be kept across restarts? 201 */ 202 void 203 GNUNET_STATISTICS_set (struct GNUNET_STATISTICS_Handle *handle, 204 const char *name, 205 uint64_t value, 206 int make_persistent); 207 208 209 /** 210 * Set statistic value for the peer. Will always use our 211 * subsystem (the argument used when @a handle was created). 212 * 213 * @param handle identification of the statistics service 214 * @param name name of the statistic value 215 * @param delta change in value (added to existing value) 216 * @param make_persistent should the value be kept across restarts? 217 */ 218 void 219 GNUNET_STATISTICS_update (struct GNUNET_STATISTICS_Handle *handle, 220 const char *name, 221 int64_t delta, 222 int make_persistent); 223 224 225 #if 0 /* keep Emacsens' auto-indent happy */ 226 { 227 #endif 228 #ifdef __cplusplus 229 } 230 #endif 231 232 /** @} */ /* end of group statistics */ 233 234 /** @} */ /* end of group addition */ 235 236 #endif