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  * Operation codes for solver information callback
 300  */
 301 enum GAS_Solver_Operation
 302 {
 303   GAS_OP_SOLVE_START,
 304   GAS_OP_SOLVE_STOP,
 305   GAS_OP_SOLVE_SETUP_START,
 306   GAS_OP_SOLVE_SETUP_STOP,
 307   GAS_OP_SOLVE_LP_START,
 308   GAS_OP_SOLVE_LP_STOP,
 309   GAS_OP_SOLVE_MLP_START,
 310   GAS_OP_SOLVE_MLP_STOP
 311 };
 312
 313
 314 /**
 315  * Status of the operation
 316  */
 317 enum GAS_Solver_Status
 318 {
 319   GAS_STAT_SUCCESS,
 320   GAS_STAT_FAIL
 321 };
 322
 323 /**
 324  * Status of the operation
 325  */
 326 enum GAS_Solver_Additional_Information
 327 {
 328   GAS_INFO_NONE,
 329   GAS_INFO_FULL,
 330   GAS_INFO_UPDATED,
 331   GAS_INFO_PROP_ALL,
 332   GAS_INFO_PROP_SINGLE
 333 };
 334
 335
 336 /**
 337  * Callback to call with additional information
 338  * Used for measurement
 339  *
 340  * @param cls the closure
 341  * @param op the operation
 342  * @param peer the peer id
 343  * @param kind the preference kind to change
 344  * @param score the new preference score
 345  * @param pref_rel the normalized preference value for this kind over all clients
 346  */
 347 typedef void
 348 (*GAS_solver_information_callback) (void *cls,
 349     enum GAS_Solver_Operation op,
 350     enum GAS_Solver_Status stat,
 351     enum GAS_Solver_Additional_Information);
 352
 353
 354 /**
 355  * Callback to call from solver when bandwidth for address has changed
 356  *
 357  * @param address the with changed bandwidth assigned
 358  */
 359 typedef void
 360 (*GAS_bandwidth_changed_cb) (void *cls, struct ATS_Address *address);
 361
 362 /**
 363  * Callback to call from solver to obtain application preference values for a
 364  * peer
 365  *
 366  * @param cls the cls
 367  * @param id the peer id
 368  * @return carry of double values containing the preferences with
 369  *      GNUNET_ATS_PreferenceCount elements
 370  */
 371 typedef const double *
 372 (*GAS_get_preferences) (void *cls, const struct GNUNET_PeerIdentity *id);
 373
 374 /**
 375  * Callback to call from solver to obtain transport properties for an
 376  * address
 377  *
 378  * @param cls the cls
 379  * @param address the address
 380  * @return carry of double values containing the preferences with
 381  *      GNUNET_ATS_PreferenceCount elements
 382  */
 383 typedef const double *
 384 (*GAS_get_properties) (void *cls, const struct ATS_Address *address);
 385
 386
 387 /**
 388  * The ATS service will pass a pointer to a struct
 389  * of this type as the first and only argument to the
 390  * entry point of each ATS solver.
 391  */
 392 struct GNUNET_ATS_PluginEnvironment
 393 {
 394   /**
 395    * Configuration handle to be used by the solver
 396    */
 397   const struct GNUNET_CONFIGURATION_Handle *cfg;
 398
 399
 400   /**
 401    * Statistics handle to be used by the solver
 402    */
 403   const struct GNUNET_STATISTICS_Handle *stats;
 404
 405
 406   /**
 407    * Hashmap containing all addresses available
 408    */
 409   struct GNUNET_CONTAINER_MultiPeerMap *addresses;
 410
 411
 412   /**
 413    * ATS addresses callback to be notified about bandwidth assignment changes
 414    */
 415   GAS_bandwidth_changed_cb bandwidth_changed_cb;
 416
 417
 418   /**
 419    * ATS addresses closure to be notified about bandwidth assignment changes
 420    */
 421   void *bw_changed_cb_cls;
 422
 423
 424   /**
 425    * ATS addresses function to obtain preference values
 426    */
 427   GAS_get_preferences get_preferences;
 428
 429
 430   /**
 431    * ATS addresses function closure to obtain preference values
 432    */
 433   void *get_preference_cls;
 434
 435
 436   /**
 437    * ATS addresses function to obtain property values
 438    */
 439   GAS_get_properties get_property;
 440
 441
 442   /**
 443    * ATS addresses function closure to obtain property values
 444    */
 445   void *get_property_cls;
 446
 447
 448   /**
 449    * Callback for solver to call with status information,
 450    * can be NULL
 451    */
 452   GAS_solver_information_callback info_cb;
 453
 454   /**
 455    * Closure for information callback,
 456    * can be NULL
 457    */
 458   void *info_cb_cls;
 459
 460   /**
 461    * The ATS solver plugin functions to call
 462    */
 463   struct GNUNET_ATS_SolverFunctions sf;
 464
 465
 466   /**
 467    *  Available networks
 468    */
 469   int networks[GNUNET_ATS_NetworkTypeCount];
 470
 471
 472   /**
 473    * Number of networks available
 474    */
 475   int network_count;
 476
 477
 478   /**
 479    * Array of configured outbound quotas
 480    * Order according to networks in network array
 481    */
 482   unsigned long long out_quota[GNUNET_ATS_NetworkTypeCount];
 483
 484
 485   /**
 486    * Array of configured inbound quotas
 487    * Order according to networks in network array
 488    */
 489   unsigned long long in_quota[GNUNET_ATS_NetworkTypeCount];
 490 };
 491
 492 #endif