src/include/gnunet_ats_plugin.h

   1 /*
   2  This file is part of GNUnet
   3  (C) 2009, 2010 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 include/gnunet_solver_plugin.h
  23  * @brief API for the ATS solvers.  This header
  24  *        specifies the struct that is given to the plugin's entry
  25  *        method and the other struct that must be returned.
  26  *        Note that the destructors of ATS plugins will
  27  *        be given the value returned by the constructor
  28  *        and is expected to return a NULL pointer.
  29  * @author Christian Grothoff
  30  */
  31 #ifndef PLUGIN_ATS_H
  32 #define PLUGIN_ATS_H
  33
  34 #include "gnunet_ats_service.h"
  35 #include "gnunet_statistics_service.h"
  36
  37 struct ATS_Address;
  38
  39
  40 /*
  41  * Solver API
  42  * ----------
  43  */
  44
  45
  46 /**
  47  * Change the preference for a peer
  48  *
  49  * @param handle the solver handle
  50  * @param client the client sending this request
  51  * @param peer the peer id
  52  * @param kind the preference kind to change
  53  * @param score the new preference score
  54  * @param pref_rel the normalized preference value for this kind over all clients
  55  */
  56 typedef void
  57 (*GAS_solver_address_change_preference) (void *solver,
  58     const struct GNUNET_PeerIdentity *peer, enum GNUNET_ATS_PreferenceKind kind,
  59     double pref_rel);
  60
  61 /**
  62  * Give feedback about the current assignment
  63  *
  64  * @param handle the solver handle
  65  * @param application the application sending this request
  66  * @param peer the peer id
  67  * @param scope the time interval for this feedback: [now - scope .. now]
  68  * @param kind the preference kind for this feedback
  69  * @param score the feedback score
  70  */
  71 typedef void
  72 (*GAS_solver_address_feedback_preference) (void *solver, void *application,
  73     const struct GNUNET_PeerIdentity *peer,
  74     const struct GNUNET_TIME_Relative scope,
  75     enum GNUNET_ATS_PreferenceKind kind, double score);
  76
  77 /**
  78  * Notify the solver about a bulk operation changing possibly a lot of values
  79  * Solver will not resolve until all bulk operations are marked as done
  80  *
  81  * @param solver the solver
  82  */
  83 typedef void
  84 (*GAS_solver_bulk_start) (void *solver);
  85
  86 /**
  87  * Mark a bulk operation as done
  88  * Solver will resolve if values have changed
  89  *
  90  * @param solver the solver
  91  */
  92 typedef void
  93 (*GAS_solver_bulk_stop) (void *solver);
  94
  95 /**
  96  * Add a single address within a network to the solver
  97  *
  98  * @param solver the solver Handle
  99  * @param addresses the address hashmap containing all addresses
 100  * @param address the address to add
 101  * @param network network type of this address
 102  */
 103 typedef void
 104 (*GAS_solver_address_add) (void *solver, struct ATS_Address *address,
 105     uint32_t network);
 106
 107 /**
 108  * Delete an address or just the session from the solver
 109  *
 110  * @param solver the solver Handle
 111  * @param addresses the address hashmap containing all addresses
 112  * @param address the address to delete
 113  * @param session_only remove address or just session
 114  */
 115 typedef void
 116 (*GAS_solver_address_delete) (void *solver, struct ATS_Address *address,
 117     int session_only);
 118
 119 /**
 120  * Transport properties for this address have changed
 121  *
 122  * @param solver solver handle
 123  * @param address the address
 124  * @param type the ATSI type in HBO
 125  * @param abs_value the absolute value of the property
 126  * @param rel_value the normalized value
 127  */
 128 typedef void
 129 (*GAS_solver_address_property_changed) (void *solver,
 130     struct ATS_Address *address, uint32_t type, uint32_t abs_value,
 131     double rel_value);
 132
 133 /**
 134  * Transport session for this address has changed
 135  *
 136  * NOTE: values in addresses are already updated
 137  *
 138  * @param solver solver handle
 139  * @param address the address
 140  * @param cur_session the current session
 141  * @param new_session the new session
 142  */
 143 typedef void
 144 (*GAS_solver_address_session_changed) (void *solver,
 145     struct ATS_Address *address, uint32_t cur_session, uint32_t new_session);
 146
 147 /**
 148  * Transport session for this address has changed
 149  *
 150  * NOTE: values in addresses are already updated
 151  *
 152  * @param solver solver handle
 153  * @param address the address
 154  * @param in_use usage state
 155  */
 156 typedef void
 157 (*GAS_solver_address_inuse_changed) (void *solver, struct ATS_Address *address,
 158     int in_use);
 159
 160 /**
 161  * Network scope for this address has changed
 162  *
 163  * NOTE: values in addresses are already updated
 164  *
 165  * @param solver solver handle
 166  * @param address the address
 167  * @param current_network the current network
 168  * @param new_network the new network
 169  */
 170 typedef void
 171 (*GAS_solver_address_network_changed) (void *solver,
 172     struct ATS_Address *address, uint32_t current_network, uint32_t new_network);
 173
 174 /**
 175  * Get the prefered address for a peer from solver
 176  *
 177  * @param solver the solver to use
 178  * @param addresses the address hashmap containing all addresses
 179  * @param peer the peer
 180  */
 181 typedef const struct ATS_Address *
 182 (*GAS_solver_get_preferred_address) (void *solver,
 183     const struct GNUNET_PeerIdentity *peer);
 184
 185 /**
 186  * Stop getting the prefered address for a peer from solver
 187  *
 188  * @param solver the solver to use
 189  * @param addresses the address hashmap containing all addresses
 190  * @param peer the peer
 191  */
 192 typedef void
 193 (*GAS_solver_stop_get_preferred_address) (void *solver,
 194     const struct GNUNET_PeerIdentity *peer);
 195
 196
 197 /**
 198  * Each plugin is required to return a pointer to a struct of this
 199  * type as the return value from its entry point.
 200  */
 201 struct GNUNET_ATS_SolverFunctions
 202 {
 203
 204   /**
 205    * Closure for all of the callbacks.
 206    */
 207   void *cls;
 208
 209   /**
 210    * Add an address to the solver
 211    */
 212   GAS_solver_address_add s_add;
 213
 214   GAS_solver_address_property_changed s_address_update_property;
 215
 216   GAS_solver_address_session_changed s_address_update_session;
 217
 218   GAS_solver_address_inuse_changed s_address_update_inuse;
 219
 220   GAS_solver_address_network_changed s_address_update_network;
 221
 222   /**
 223    * Get address from solver
 224    */
 225   GAS_solver_get_preferred_address s_get;
 226
 227   /**
 228    * Get address from solver
 229    */
 230   GAS_solver_stop_get_preferred_address s_get_stop;
 231
 232   /**
 233    * Delete address in solver
 234    */
 235   GAS_solver_address_delete s_del;
 236
 237   /**
 238    * Change relative preference for quality in solver
 239    */
 240   GAS_solver_address_change_preference s_pref;
 241
 242   /**
 243    * Give feedback about the current assignment
 244    */
 245   GAS_solver_address_feedback_preference s_feedback;
 246
 247   /**
 248    * Start a bulk operation
 249    */
 250   GAS_solver_bulk_start s_bulk_start;
 251
 252   /**
 253    * Bulk operation done
 254    */
 255   GAS_solver_bulk_stop s_bulk_stop;
 256
 257 };
 258
 259
 260 /**
 261  * Callback to call from solver when bandwidth for address has changed
 262  *
 263  * @param address the with changed bandwidth assigned
 264  */
 265 typedef void
 266 (*GAS_bandwidth_changed_cb) (void *cls, struct ATS_Address *address);
 267
 268 /**
 269  * Callback to call from solver to obtain application preference values for a
 270  * peer
 271  *
 272  * @param cls the cls
 273  * @param id the peer id
 274  * @return carry of double values containing the preferences with
 275  *      GNUNET_ATS_PreferenceCount elements
 276  */
 277 typedef const double *
 278 (*GAS_get_preferences) (void *cls, const struct GNUNET_PeerIdentity *id);
 279
 280 /**
 281  * Callback to call from solver to obtain transport properties for an
 282  * address
 283  *
 284  * @param cls the cls
 285  * @param address the address
 286  * @return carry of double values containing the preferences with
 287  *      GNUNET_ATS_PreferenceCount elements
 288  */
 289 typedef const double *
 290 (*GAS_get_properties) (void *cls, const struct ATS_Address *address);
 291
 292
 293 /**
 294  * The transport service will pass a pointer to a struct
 295  * of this type as the first and only argument to the
 296  * entry point of each transport plugin.
 297  */
 298 struct GNUNET_ATS_PluginEnvironment
 299 {
 300   /**
 301    * Closure for the various callbacks.
 302    */
 303   void *cls;
 304
 305   GAS_bandwidth_changed_cb bandwidth_changed_cb;
 306   void *bw_changed_cb_cls;
 307
 308   GAS_get_preferences get_preferences_cb;
 309   void *get_preference_cls;
 310
 311   GAS_get_properties get_property_cb;
 312   void *get_property_cls;
 313
 314   struct GNUNET_ATS_SolverFunctions sf;
 315
 316   struct GNUNET_CONFIGURATION_Handle *cfg;
 317   struct GNUNET_STATISTICS_Handle *stats;
 318   struct GNUNET_CONTAINER_MultiPeerMap *addresses;
 319
 320   /* Available networks */
 321   int networks[GNUNET_ATS_NetworkTypeCount];
 322   int network_count;
 323
 324   unsigned long long out_quota[GNUNET_ATS_NetworkTypeCount];
 325   unsigned long long in_quota[GNUNET_ATS_NetworkTypeCount];
 326 };
 327
 328 #endif