X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_statistics_service.h;h=94fa49358a44cc62ae6cd2ce95c691d2a0a07e01;hb=0d4f151374efb1972361c40b6624bf4fd0e3fcaa;hp=71c834f2afc7c52420b93a78292c627c6754bdd1;hpb=ac2de52a5de68f6f4f13b7aa01a481869fffc6aa;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_statistics_service.h b/src/include/gnunet_statistics_service.h index 71c834f2a..94fa49358 100644 --- a/src/include/gnunet_statistics_service.h +++ b/src/include/gnunet_statistics_service.h @@ -1,29 +1,39 @@ /* This file is part of GNUnet - (C) 2009, 2010 Christian Grothoff (and other contributing authors) + Copyright (C) 2009-2013, 2016 GNUnet e.V. - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 2, or (at your - option) any later version. + GNUnet is free software: you can redistribute it and/or modify it + under the terms of the GNU Affero General Public License as published + by the Free Software Foundation, either version 3 of the License, + or (at your option) any later version. GNUnet is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. + Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. + SPDX-License-Identifier: AGPL3.0-or-later */ /** - * @file include/gnunet_statistics_service.h - * @brief API to create, modify and access statistics about - * the operation of GNUnet; all statistical values - * must be of type "unsigned long long". * @author Christian Grothoff + * + * @file + * API to create, modify and access statistics. + * + * @defgroup statistics Statistics service + * Track statistics or provide access to statistics. + * + * Create, modify and access statistics about the operation of GNUnet. + * + * All statistical values must be of type `unsigned long long`. + * + * @see [Documentation](https://gnunet.org/gnunet-statistics-subsystem) + * + * @{ */ #ifndef GNUNET_STATISTICS_SERVICE_H @@ -37,9 +47,7 @@ extern "C" #endif #endif -#include "gnunet_common.h" -#include "gnunet_configuration_lib.h" -#include "gnunet_scheduler_lib.h" +#include "gnunet_util_lib.h" /** * Version of the statistics API. @@ -58,99 +66,118 @@ struct GNUNET_STATISTICS_Handle; * @param subsystem name of subsystem that created the statistic * @param name the name of the datum * @param value the current value - * @param is_persistent GNUNET_YES if the value is persistent, GNUNET_NO if not - * @return GNUNET_OK to continue, GNUNET_SYSERR to abort iteration + * @param is_persistent #GNUNET_YES if the value is persistent, #GNUNET_NO if not + * @return #GNUNET_OK to continue, #GNUNET_SYSERR to abort iteration */ -typedef int (*GNUNET_STATISTICS_Iterator) (void *cls, - const char *subsystem, - const char *name, - uint64_t value, - int is_persistent); +typedef int +(*GNUNET_STATISTICS_Iterator) (void *cls, + const char *subsystem, + const char *name, + uint64_t value, + int is_persistent); + /** * Get handle for the statistics service. * - * @param sched scheduler to use * @param subsystem name of subsystem using the service * @param cfg services configuration in use * @return handle to use */ -struct GNUNET_STATISTICS_Handle - *GNUNET_STATISTICS_create (struct GNUNET_SCHEDULER_Handle *sched, - const char *subsystem, - const struct GNUNET_CONFIGURATION_Handle *cfg); +struct GNUNET_STATISTICS_Handle * +GNUNET_STATISTICS_create (const char *subsystem, + const struct GNUNET_CONFIGURATION_Handle *cfg); /** - * Destroy a handle (free all state associated with - * it). + * Destroy a handle (free all state associated with it). * * @param h statistics handle to destroy - * @param sync_first set to GNUNET_YES if pending SET requests should + * @param sync_first set to #GNUNET_YES if pending SET requests should * be completed */ -void GNUNET_STATISTICS_destroy (struct GNUNET_STATISTICS_Handle *h, - int sync_first); +void +GNUNET_STATISTICS_destroy (struct GNUNET_STATISTICS_Handle *h, + int sync_first); /** * Watch statistics from the peer (be notified whenever they change). - * Note that the only way to cancel a "watch" request is to destroy - * the statistics handle given as the first argument to this call. * * @param handle identification of the statistics service * @param subsystem limit to the specified subsystem, never NULL * @param name name of the statistic value, never NULL * @param proc function to call on each value - * @param proc_cls closure for proc - * @return GNUNET_OK on success, GNUNET_SYSERR on error + * @param proc_cls closure for @a proc + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error */ int GNUNET_STATISTICS_watch (struct GNUNET_STATISTICS_Handle *handle, - const char *subsystem, - const char *name, - GNUNET_STATISTICS_Iterator proc, - void *proc_cls); + const char *subsystem, + const char *name, + GNUNET_STATISTICS_Iterator proc, + void *proc_cls); + + +/** + * Stop watching statistics from the peer. + * + * @param handle identification of the statistics service + * @param subsystem limit to the specified subsystem, never NULL + * @param name name of the statistic value, never NULL + * @param proc function to call on each value + * @param proc_cls closure for @a proc + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error (no such watch) + */ +int +GNUNET_STATISTICS_watch_cancel (struct GNUNET_STATISTICS_Handle *handle, + const char *subsystem, + const char *name, + GNUNET_STATISTICS_Iterator proc, + void *proc_cls); /** - * Continuation called by the "get_all" and "get" functions. + * Continuation called by #GNUNET_STATISTICS_get() functions. * * @param cls closure - * @param success GNUNET_OK if statistics were - * successfully obtained, GNUNET_SYSERR if not. + * @param success #GNUNET_OK if statistics were + * successfully obtained, #GNUNET_SYSERR if not. */ -typedef void (*GNUNET_STATISTICS_Callback) (void *cls, int success); +typedef void +(*GNUNET_STATISTICS_Callback) (void *cls, + int success); + /** * Handle that can be used to cancel a statistics 'get' operation. */ struct GNUNET_STATISTICS_GetHandle; + /** * Get statistic from the peer. * * @param handle identification of the statistics service - * @param subsystem limit to the specified subsystem, NULL for our subsystem + * @param subsystem limit to the specified subsystem, NULL for all subsystems * @param name name of the statistic value, NULL for all values - * @param timeout after how long should we give up (and call - * notify with buf NULL and size 0)? * @param cont continuation to call when done (can be NULL) + * This callback CANNOT destroy the statistics handle in the same call. * @param proc function to call on each value - * @param cls closure for proc and cont + * @param cls closure for @a proc and @a cont * @return NULL on error */ struct GNUNET_STATISTICS_GetHandle * GNUNET_STATISTICS_get (struct GNUNET_STATISTICS_Handle *handle, const char *subsystem, const char *name, - struct GNUNET_TIME_Relative timeout, GNUNET_STATISTICS_Callback cont, - GNUNET_STATISTICS_Iterator proc, void *cls); + GNUNET_STATISTICS_Iterator proc, + void *cls); /** - * Cancel a 'get' request. Must be called before the 'cont' + * Cancel a #GNUNET_STATISTICS_get request. Must be called before the 'cont' * function is called. * * @param gh handle of the request to cancel @@ -161,7 +188,7 @@ GNUNET_STATISTICS_get_cancel (struct GNUNET_STATISTICS_GetHandle *gh); /** * Set statistic value for the peer. Will always use our - * subsystem (the argument used when "handle" was created). + * subsystem (the argument used when @a handle was created). * * @param handle identification of the statistics service * @param name name of the statistic value @@ -171,11 +198,13 @@ GNUNET_STATISTICS_get_cancel (struct GNUNET_STATISTICS_GetHandle *gh); void GNUNET_STATISTICS_set (struct GNUNET_STATISTICS_Handle *handle, const char *name, - uint64_t value, int make_persistent); + uint64_t value, + int make_persistent); + /** * Set statistic value for the peer. Will always use our - * subsystem (the argument used when "handle" was created). + * subsystem (the argument used when @a handle was created). * * @param handle identification of the statistics service * @param name name of the statistic value @@ -185,7 +214,8 @@ GNUNET_STATISTICS_set (struct GNUNET_STATISTICS_Handle *handle, void GNUNET_STATISTICS_update (struct GNUNET_STATISTICS_Handle *handle, const char *name, - int64_t delta, int make_persistent); + int64_t delta, + int make_persistent); @@ -196,4 +226,6 @@ GNUNET_STATISTICS_update (struct GNUNET_STATISTICS_Handle *handle, } #endif +/** @} */ /* end of group statistics */ + #endif