src/ats/gnunet-service-ats_plugins.h

   1 /*
   2  This file is part of GNUnet.
   3  (C) 2011-2014 Christian Grothoff (and other contributing authors)
   4
   5  GNUnet is free software; you can redistribute it and/or modify
   6  it under the terms of the GNU General Public License as published
   7  by the Free Software Foundation; either version 3, or (at your
   8  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  General Public License for more details.
  14
  15  You should have received a copy of the GNU General Public License
  16  along with GNUnet; see the file COPYING.  If not, write to the
  17  Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18  Boston, MA 02111-1307, USA.
  19  */
  20
  21 /**
  22  * @file ats/gnunet-service-ats_plugins.h
  23  * @brief ats service plugin management
  24  * @author Matthias Wachs
  25  * @author Christian Grothoff
  26  */
  27 #ifndef GNUNET_SERVICE_ATS_PLUGINS_H
  28 #define GNUNET_SERVICE_ATS_PLUGINS_H
  29
  30 #include "gnunet-service-ats_addresses.h"
  31
  32
  33 /**
  34  * Available ressource assignment modes
  35  */
  36 enum ATS_Mode
  37 {
  38   /**
  39    * proportional mode:
  40    *
  41    * Assign each peer an equal amount of bandwidth (bw)
  42    *
  43    * bw_per_peer = bw_total / #active addresses
  44    */
  45   MODE_PROPORTIONAL,
  46
  47   /**
  48    * MLP mode:
  49    *
  50    * Solve ressource assignment as an optimization problem
  51    * Uses an mixed integer programming solver
  52    */
  53   MODE_MLP,
  54
  55   /**
  56    * Reinforcement Learning mode:
  57    *
  58    * Solve resource assignment using a learning agent
  59    */
  60   MODE_RIL
  61 };
  62
  63
  64 /**
  65  * Initialize address subsystem. The addresses subsystem manages the addresses
  66  * known and current performance information. It has a solver component
  67  * responsible for the resource allocation. It tells the solver about changes
  68  * and receives updates when the solver changes the ressource allocation.
  69  *
  70  * @param cfg configuration to use
  71  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error (failed to load
  72  *         solver plugin)
  73  */
  74 int
  75 GAS_plugins_init (const struct GNUNET_CONFIGURATION_Handle *cfg);
  76
  77
  78 /**
  79  * Shutdown address subsystem.
  80  */
  81 void
  82 GAS_plugins_done (void);
  83
  84
  85 /**
  86  * The preference changed for a peer, update solver.
  87  *
  88  * @param peer the peer
  89  * @param kind the ATS kind
  90  * @param pref_rel the new relative preference value
  91  */
  92 void
  93 GAS_normalized_preference_changed (const struct GNUNET_PeerIdentity *peer,
  94                                    enum GNUNET_ATS_PreferenceKind kind,
  95                                    double pref_rel);
  96
  97
  98 /**
  99  * The relative value for a property changed
 100  *
 101  * @param address the peer
 102  * @param type the ATS type
 103  * @param prop_rel the new relative preference value
 104  */
 105 void
 106 GAS_normalized_property_changed (struct ATS_Address *address,
 107                                  uint32_t type,
 108                                  double prop_rel);
 109
 110
 111 /**
 112  * Tell the solver that the given address can now be used
 113  * for talking to the respective peer.
 114  *
 115  * @param new_address the new address
 116  * @param addr_net network scope the address is in
 117  * @param atsi performance data for the address
 118  * @param atsi_count size of the @a atsi array
 119  */
 120 void
 121 GAS_plugin_new_address (struct ATS_Address *new_address,
 122                         enum GNUNET_ATS_Network_Type addr_net,
 123                         const struct GNUNET_ATS_Information *atsi,
 124                         uint32_t atsi_count);
 125
 126
 127 /**
 128  * Tell the solver that updated performance data was
 129  * observed for the given address.
 130  *
 131  * @param new_address the new address
 132  * @param atsi updated performance data for the address
 133  * @param atsi_count size of the @a atsi array
 134  */
 135 void
 136 GAS_plugin_update_address (struct ATS_Address *address,
 137                            const struct GNUNET_ATS_Information *atsi,
 138                            uint32_t atsi_count);
 139
 140
 141 /**
 142  * Tell the solver that the given address is no longer valid
 143  * can cannot be used any longer.
 144  *
 145  * @param address address that was deleted
 146  */
 147 void
 148 GAS_plugin_delete_address (struct ATS_Address *address);
 149
 150
 151 /**
 152  * Tell the solver that the given client has expressed its
 153  * appreciation for the past performance of a given connection.
 154  *
 155  * @param application client providing the feedback
 156  * @param peer peer the feedback is about
 157  * @param scope timeframe the feedback applies to
 158  * @param kind performance property the feedback relates to
 159  * @param score_abs degree of the appreciation
 160  */
 161 void
 162 GAS_plugin_preference_feedback (struct GNUNET_SERVER_Client *application,
 163                                 const struct GNUNET_PeerIdentity *peer,
 164                                 const struct GNUNET_TIME_Relative scope,
 165                                 enum GNUNET_ATS_PreferenceKind kind,
 166                                 float score_abs);
 167
 168
 169
 170
 171 /**
 172  * Stop instant solving, there are many state updates
 173  * happening in bulk right now.
 174  */
 175 void
 176 GAS_plugin_solver_lock (void);
 177
 178
 179 /**
 180  * Resume instant solving, we are done with the bulk state updates.
 181  */
 182 void
 183 GAS_plugin_solver_unlock (void);
 184
 185
 186 /**
 187  * Notify the plugin that a request to connect to
 188  * a particular peer was given to us.
 189  *
 190  * @param pid identity of peer we now care about
 191  */
 192 void
 193 GAS_plugin_request_connect_start (const struct GNUNET_PeerIdentity *pid);
 194
 195
 196 /**
 197  * Notify the plugin that a request to connect to
 198  * a particular peer was dropped.
 199  *
 200  * @param pid identity of peer we care now less about
 201  */
 202 void
 203 GAS_plugin_request_connect_stop (const struct GNUNET_PeerIdentity *pid);
 204
 205
 206 #endif