src/include/gnunet_load_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2010 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
  19 /**
  20  * @author Christian Grothoff
  21  *
  22  * @file
  23  * Functions related to load calculations
  24  *
  25  * @defgroup load  Load library
  26  * Load calculations.
  27  * @{
  28  */
  29
  30 #ifndef GNUNET_LOAD_LIB_H
  31 #define GNUNET_LOAD_LIB_H
  32
  33 #ifdef __cplusplus
  34 extern "C"
  35 {
  36 #if 0                           /* keep Emacsens' auto-indent happy */
  37 }
  38 #endif
  39 #endif
  40
  41 #include "gnunet_common.h"
  42 #include "gnunet_time_lib.h"
  43
  44 /**
  45  * Opaque load handle.
  46  */
  47 struct GNUNET_LOAD_Value;
  48
  49 /**
  50  * Create a new load value.
  51  *
  52  * @param autodecline speed at which this value should automatically
  53  *        decline in the absence of external events; at the given
  54  *        frequency, 0-load values will be added to the load
  55  * @return the new load value
  56  */
  57 struct GNUNET_LOAD_Value *
  58 GNUNET_LOAD_value_init (struct GNUNET_TIME_Relative autodecline);
  59
  60
  61 /**
  62  * Change the value by which the load automatically declines.
  63  *
  64  * @param load load to update
  65  * @param autodecline frequency of load decline
  66  */
  67 void
  68 GNUNET_LOAD_value_set_decline (struct GNUNET_LOAD_Value *load,
  69                                struct GNUNET_TIME_Relative autodecline);
  70
  71
  72 /**
  73  * Free a load value.
  74  *
  75  * @param lv value to free
  76  */
  77 #define GNUNET_LOAD_value_free(lv) GNUNET_free (lv)
  78
  79
  80 /**
  81  * Get the current load.
  82  *
  83  * @param load load handle
  84  * @return zero for below-average load, otherwise
  85  *         number of std. devs we are above average;
  86  *         100 if the latest updates were so large
  87  *         that we could not do proper calculations
  88  */
  89 double
  90 GNUNET_LOAD_get_load (struct GNUNET_LOAD_Value *load);
  91
  92
  93 /**
  94  * Get the average value given to update so far.
  95  *
  96  * @param load load handle
  97  * @return zero if update was never called
  98  */
  99 double
 100 GNUNET_LOAD_get_average (struct GNUNET_LOAD_Value *load);
 101
 102
 103 /**
 104  * Update the current load.
 105  *
 106  * @param load to update
 107  * @param data latest measurement value (for example, delay)
 108  */
 109 void
 110 GNUNET_LOAD_update (struct GNUNET_LOAD_Value *load, uint64_t data);
 111
 112
 113 #if 0                           /* keep Emacsens' auto-indent happy */
 114 {
 115 #endif
 116 #ifdef __cplusplus
 117 }
 118 #endif
 119
 120 /* ifndef GNUNET_LOAD_LIB_H */
 121 #endif
 122
 123 /** @} */  /* end of group */
 124
 125 /* end of gnunet_load_lib.h */