src/include/gnunet_statistics_service.h

   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 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
  16 /**
  17  * @author Christian Grothoff
  18  *
  19  * @file
  20  * API to create, modify and access statistics.
  21  *
  22  * @defgroup statistics  Statistics service
  23  * Track statistics or provide access to statistics.
  24  *
  25  * Create, modify and access statistics about the operation of GNUnet.
  26  *
  27  * All statistical values must be of type `unsigned long long`.
  28  *
  29  * @see [Documentation](https://gnunet.org/gnunet-statistics-subsystem)
  30  *
  31  * @{
  32  */
  33
  34 #ifndef GNUNET_STATISTICS_SERVICE_H
  35 #define GNUNET_STATISTICS_SERVICE_H
  36
  37 #ifdef __cplusplus
  38 extern "C"
  39 {
  40 #if 0                           /* keep Emacsens' auto-indent happy */
  41 }
  42 #endif
  43 #endif
  44
  45 #include "gnunet_util_lib.h"
  46
  47 /**
  48  * Version of the statistics API.
  49  */
  50 #define GNUNET_STATISTICS_VERSION 0x00000000
  51
  52 /**
  53  * Opaque handle for the statistics service.
  54  */
  55 struct GNUNET_STATISTICS_Handle;
  56
  57 /**
  58  * Callback function to process statistic values.
  59  *
  60  * @param cls closure
  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
  66  */
  67 typedef int
  68 (*GNUNET_STATISTICS_Iterator) (void *cls,
  69                                const char *subsystem,
  70                                const char *name,
  71                                uint64_t value,
  72                                int is_persistent);
  73
  74
  75 /**
  76  * Get handle for the statistics service.
  77  *
  78  * @param subsystem name of subsystem using the service
  79  * @param cfg services configuration in use
  80  * @return handle to use
  81  */
  82 struct GNUNET_STATISTICS_Handle *
  83 GNUNET_STATISTICS_create (const char *subsystem,
  84                           const struct GNUNET_CONFIGURATION_Handle *cfg);
  85
  86
  87 /**
  88  * Destroy a handle (free all state associated with it).
  89  *
  90  * @param h statistics handle to destroy
  91  * @param sync_first set to #GNUNET_YES if pending SET requests should
  92  *        be completed
  93  */
  94 void
  95 GNUNET_STATISTICS_destroy (struct GNUNET_STATISTICS_Handle *h,
  96                            int sync_first);
  97
  98
  99 /**
 100  * Watch statistics from the peer (be notified whenever they change).
 101  *
 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
 108  */
 109 int
 110 GNUNET_STATISTICS_watch (struct GNUNET_STATISTICS_Handle *handle,
 111                          const char *subsystem,
 112                          const char *name,
 113                          GNUNET_STATISTICS_Iterator proc,
 114                          void *proc_cls);
 115
 116
 117 /**
 118  * Stop watching statistics from the peer.
 119  *
 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)
 126  */
 127 int
 128 GNUNET_STATISTICS_watch_cancel (struct GNUNET_STATISTICS_Handle *handle,
 129                                 const char *subsystem,
 130                                 const char *name,
 131                                 GNUNET_STATISTICS_Iterator proc,
 132                                 void *proc_cls);
 133
 134
 135 /**
 136  * Continuation called by #GNUNET_STATISTICS_get() functions.
 137  *
 138  * @param cls closure
 139  * @param success #GNUNET_OK if statistics were
 140  *        successfully obtained, #GNUNET_SYSERR if not.
 141  */
 142 typedef void
 143 (*GNUNET_STATISTICS_Callback) (void *cls,
 144                                int success);
 145
 146
 147 /**
 148  * Handle that can be used to cancel a statistics 'get' operation.
 149  */
 150 struct GNUNET_STATISTICS_GetHandle;
 151
 152
 153 /**
 154  * Get statistic from the peer.
 155  *
 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
 164  */
 165 struct GNUNET_STATISTICS_GetHandle *
 166 GNUNET_STATISTICS_get (struct GNUNET_STATISTICS_Handle *handle,
 167                        const char *subsystem,
 168                        const char *name,
 169                        GNUNET_STATISTICS_Callback cont,
 170                        GNUNET_STATISTICS_Iterator proc,
 171                        void *cls);
 172
 173
 174 /**
 175  * Cancel a #GNUNET_STATISTICS_get request.  Must be called before the 'cont'
 176  * function is called.
 177  *
 178  * @param gh handle of the request to cancel
 179  */
 180 void
 181 GNUNET_STATISTICS_get_cancel (struct GNUNET_STATISTICS_GetHandle *gh);
 182
 183
 184 /**
 185  * Set statistic value for the peer.  Will always use our
 186  * subsystem (the argument used when @a handle was created).
 187  *
 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?
 192  */
 193 void
 194 GNUNET_STATISTICS_set (struct GNUNET_STATISTICS_Handle *handle,
 195                        const char *name,
 196                        uint64_t value,
 197                        int make_persistent);
 198
 199
 200 /**
 201  * Set statistic value for the peer.  Will always use our
 202  * subsystem (the argument used when @a handle was created).
 203  *
 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?
 208  */
 209 void
 210 GNUNET_STATISTICS_update (struct GNUNET_STATISTICS_Handle *handle,
 211                           const char *name,
 212                           int64_t delta,
 213                           int make_persistent);
 214
 215
 216
 217 #if 0                           /* keep Emacsens' auto-indent happy */
 218 {
 219 #endif
 220 #ifdef __cplusplus
 221 }
 222 #endif
 223
 224 /** @} */ /* end of group statistics */
 225
 226 #endif