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_ats_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  * Solver functions
 199  *
 200  * Each solver is required to set up this struct contained in the plugin
 201  * environment struct in during startup
 202  */
 203 struct GNUNET_ATS_SolverFunctions
 204 {
 205
 206   /**
 207    * Add a new address for a peer to the solver
 208    *
 209    * The address is already contained in the addresses hashmap!
 210    */
 211   GAS_solver_address_add s_add;
 212
 213
 214   /**
 215    * Update the properties of an address in the solver
 216    */
 217   GAS_solver_address_property_changed s_address_update_property;
 218
 219
 220   /**
 221    * Update the session of an address in the solver
 222    */
 223   GAS_solver_address_session_changed s_address_update_session;
 224
 225
 226   /**
 227    * Notify the solver that in address is (not) actively used by transport
 228    * to communicate with a remote peer
 229    */
 230   GAS_solver_address_inuse_changed s_address_update_inuse;
 231
 232
 233   /**
 234    * Notify solver that the network an address is located in has changed
 235    */
 236   GAS_solver_address_network_changed s_address_update_network;
 237
 238   /**
 239    * Tell solver to notify ATS if the address to use changes for a specific
 240    * peer using the bandwidth changed callback
 241    *
 242    * The solver must only notify about changes for peers with pending address
 243    * requests!
 244    */
 245   GAS_solver_get_preferred_address s_get;
 246
 247   /**
 248   * Tell solver stop notifying ATS about changes for this peers
 249   *
 250   * The solver must only notify about changes for peers with pending address
 251   * requests!
 252   */
 253   GAS_solver_stop_get_preferred_address s_get_stop;
 254
 255
 256   /**
 257    * Delete an address in the solver
 258    *
 259    * The address is not contained in the address hashmap anymore!
 260    */
 261   GAS_solver_address_delete s_del;
 262
 263
 264   /**
 265    * Change relative preference for quality in solver
 266    */
 267   GAS_solver_address_change_preference s_pref;
 268
 269
 270   /**
 271    * Give feedback about the current assignment
 272    */
 273   GAS_solver_address_feedback_preference s_feedback;
 274
 275
 276   /**
 277    * Start a bulk operation
 278    *
 279    * Used if many values have to be updated at the same time.
 280    * When a bulk operation is pending the solver does not have to resolve
 281    * the problem since more updates will follow anyway
 282    *
 283    * For each call to bulk_start, a call to bulk_stop is required!
 284    */
 285   GAS_solver_bulk_start s_bulk_start;
 286
 287
 288   /**
 289    * Bulk operation done
 290    *
 291    * If no more bulk operations are pending, the solver can solve the problem
 292    * with the updated values
 293    */
 294   GAS_solver_bulk_stop s_bulk_stop;
 295 };
 296
 297
 298 /**
 299  * Callback to call from solver when bandwidth for address has changed
 300  *
 301  * @param address the with changed bandwidth assigned
 302  */
 303 typedef void
 304 (*GAS_bandwidth_changed_cb) (void *cls, struct ATS_Address *address);
 305
 306 /**
 307  * Callback to call from solver to obtain application preference values for a
 308  * peer
 309  *
 310  * @param cls the cls
 311  * @param id the peer id
 312  * @return carry of double values containing the preferences with
 313  *      GNUNET_ATS_PreferenceCount elements
 314  */
 315 typedef const double *
 316 (*GAS_get_preferences) (void *cls, const struct GNUNET_PeerIdentity *id);
 317
 318 /**
 319  * Callback to call from solver to obtain transport properties for an
 320  * address
 321  *
 322  * @param cls the cls
 323  * @param address the address
 324  * @return carry of double values containing the preferences with
 325  *      GNUNET_ATS_PreferenceCount elements
 326  */
 327 typedef const double *
 328 (*GAS_get_properties) (void *cls, const struct ATS_Address *address);
 329
 330
 331 /**
 332  * The ATS service will pass a pointer to a struct
 333  * of this type as the first and only argument to the
 334  * entry point of each ATS solver.
 335  */
 336 struct GNUNET_ATS_PluginEnvironment
 337 {
 338   /**
 339    * Configuration handle to be used by the solver
 340    */
 341   const struct GNUNET_CONFIGURATION_Handle *cfg;
 342
 343
 344   /**
 345    * Statistics handle to be used by the solver
 346    */
 347   const struct GNUNET_STATISTICS_Handle *stats;
 348
 349
 350   /**
 351    * Hashmap containing all addresses available
 352    */
 353   struct GNUNET_CONTAINER_MultiPeerMap *addresses;
 354
 355
 356   /**
 357    * ATS addresses callback to be notified about bandwidth assignment changes
 358    */
 359   GAS_bandwidth_changed_cb bandwidth_changed_cb;
 360
 361
 362   /**
 363    * ATS addresses closure to be notified about bandwidth assignment changes
 364    */
 365   void *bw_changed_cb_cls;
 366
 367
 368   /**
 369    * ATS addresses function to obtain preference values
 370    */
 371   GAS_get_preferences get_preferences;
 372
 373
 374   /**
 375    * ATS addresses function closure to obtain preference values
 376    */
 377   void *get_preference_cls;
 378
 379
 380   /**
 381    * ATS addresses function to obtain property values
 382    */
 383   GAS_get_properties get_property;
 384
 385
 386   /**
 387    * ATS addresses function closure to obtain property values
 388    */
 389   void *get_property_cls;
 390
 391
 392   /**
 393    * The ATS solver plugin functions to call
 394    */
 395   struct GNUNET_ATS_SolverFunctions sf;
 396
 397
 398   /**
 399    *  Available networks
 400    */
 401   int networks[GNUNET_ATS_NetworkTypeCount];
 402
 403
 404   /**
 405    * Number of networks available
 406    */
 407   int network_count;
 408
 409
 410   /**
 411    * Array of configured outbound quotas
 412    * Order according to networks in network array
 413    */
 414   unsigned long long out_quota[GNUNET_ATS_NetworkTypeCount];
 415
 416
 417   /**
 418    * Array of configured inbound quotas
 419    * Order according to networks in network array
 420    */
 421   unsigned long long in_quota[GNUNET_ATS_NetworkTypeCount];
 422 };
 423
 424 #endif