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