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  * Solver API
  41  * ----------
  42  */
  43
  44 /**
  45  * Change the preference for a peer
  46  *
  47  * @param handle the solver handle
  48  * @param client the client sending this request
  49  * @param peer the peer id
  50  * @param kind the preference kind to change
  51  * @param score the new preference score
  52  * @param pref_rel the normalized preference value for this kind over all clients
  53  */
  54 typedef void
  55 (*GAS_solver_address_change_preference) (void *solver,
  56     const struct GNUNET_PeerIdentity *peer, enum GNUNET_ATS_PreferenceKind kind,
  57     double pref_rel);
  58
  59 /**
  60  * Give feedback about the current assignment
  61  *
  62  * @param handle the solver handle
  63  * @param application the application sending this request
  64  * @param peer the peer id
  65  * @param scope the time interval for this feedback: [now - scope .. now]
  66  * @param kind the preference kind for this feedback
  67  * @param score the feedback score
  68  */
  69 typedef void
  70 (*GAS_solver_address_feedback_preference) (void *solver, void *application,
  71     const struct GNUNET_PeerIdentity *peer,
  72     const struct GNUNET_TIME_Relative scope,
  73     enum GNUNET_ATS_PreferenceKind kind, double score);
  74
  75 /**
  76  * Notify the solver about a bulk operation changing possibly a lot of values
  77  * Solver will not resolve until all bulk operations are marked as done
  78  *
  79  * @param solver the solver
  80  */
  81 typedef void
  82 (*GAS_solver_bulk_start) (void *solver);
  83
  84 /**
  85  * Mark a bulk operation as done
  86  * Solver will resolve if values have changed
  87  *
  88  * @param solver the solver
  89  */
  90 typedef void
  91 (*GAS_solver_bulk_stop) (void *solver);
  92
  93 /**
  94  * Add a single address within a network to the solver
  95  *
  96  * @param solver the solver Handle
  97  * @param addresses the address hashmap containing all addresses
  98  * @param address the address to add
  99  * @param network network type of this address
 100  */
 101 typedef void
 102 (*GAS_solver_address_add) (void *solver, struct ATS_Address *address,
 103     uint32_t network);
 104
 105 /**
 106  * Delete an address or just the session from the solver
 107  *
 108  * @param solver the solver Handle
 109  * @param addresses the address hashmap containing all addresses
 110  * @param address the address to delete
 111  * @param session_only remove address or just session
 112  */
 113 typedef void
 114 (*GAS_solver_address_delete) (void *solver, struct ATS_Address *address,
 115     int session_only);
 116
 117 /**
 118  * Transport properties for this address have changed
 119  *
 120  * @param solver solver handle
 121  * @param address the address
 122  * @param type the ATSI type in HBO
 123  * @param abs_value the absolute value of the property
 124  * @param rel_value the normalized value
 125  */
 126 typedef void
 127 (*GAS_solver_address_property_changed) (void *solver,
 128     struct ATS_Address *address, uint32_t type, uint32_t abs_value,
 129     double rel_value);
 130
 131 /**
 132  * Transport session for this address has changed
 133  *
 134  * NOTE: values in addresses are already updated
 135  *
 136  * @param solver solver handle
 137  * @param address the address
 138  * @param cur_session the current session
 139  * @param new_session the new session
 140  */
 141 typedef void
 142 (*GAS_solver_address_session_changed) (void *solver,
 143     struct ATS_Address *address, uint32_t cur_session, uint32_t new_session);
 144
 145
 146 /**
 147  * Network scope for this address has changed
 148  *
 149  * NOTE: values in addresses are already updated
 150  *
 151  * @param solver solver handle
 152  * @param address the address
 153  * @param current_network the current network
 154  * @param new_network the new network
 155  */
 156 typedef void
 157 (*GAS_solver_address_network_changed) (void *solver,
 158     struct ATS_Address *address, uint32_t current_network, uint32_t new_network);
 159
 160 /**
 161  * Get the prefered address for a peer from solver
 162  *
 163  * @param solver the solver to use
 164  * @param addresses the address hashmap containing all addresses
 165  * @param peer the peer
 166  */
 167 typedef const struct ATS_Address *
 168 (*GAS_solver_get_preferred_address) (void *solver,
 169     const struct GNUNET_PeerIdentity *peer);
 170
 171 /**
 172  * Stop getting the prefered address for a peer from solver
 173  *
 174  * @param solver the solver to use
 175  * @param addresses the address hashmap containing all addresses
 176  * @param peer the peer
 177  */
 178 typedef void
 179 (*GAS_solver_stop_get_preferred_address) (void *solver,
 180     const struct GNUNET_PeerIdentity *peer);
 181
 182 /**
 183  * Solver functions
 184  *
 185  * Each solver is required to set up this struct contained in the plugin
 186  * environment struct in during startup
 187  */
 188 struct GNUNET_ATS_SolverFunctions
 189 {
 190
 191   /**
 192    * Add a new address for a peer to the solver
 193    *
 194    * The address is already contained in the addresses hashmap!
 195    */
 196   GAS_solver_address_add s_add;
 197
 198   /**
 199    * Update the properties of an address in the solver
 200    */
 201   GAS_solver_address_property_changed s_address_update_property;
 202
 203   /**
 204    * Update the session of an address in the solver
 205    */
 206   GAS_solver_address_session_changed s_address_update_session;
 207
 208   /**
 209    * Notify solver that the network an address is located in has changed
 210    */
 211   GAS_solver_address_network_changed s_address_update_network;
 212
 213   /**
 214    * Tell solver to notify ATS if the address to use changes for a specific
 215    * peer using the bandwidth changed callback
 216    *
 217    * The solver must only notify about changes for peers with pending address
 218    * requests!
 219    */
 220   GAS_solver_get_preferred_address s_get;
 221
 222   /**
 223    * Tell solver stop notifying ATS about changes for this peers
 224    *
 225    * The solver must only notify about changes for peers with pending address
 226    * requests!
 227    */
 228   GAS_solver_stop_get_preferred_address s_get_stop;
 229
 230   /**
 231    * Delete an address in the solver
 232    *
 233    * The address is not contained in the address hashmap anymore!
 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    * Used if many values have to be updated at the same time.
 251    * When a bulk operation is pending the solver does not have to resolve
 252    * the problem since more updates will follow anyway
 253    *
 254    * For each call to bulk_start, a call to bulk_stop is required!
 255    */
 256   GAS_solver_bulk_start s_bulk_start;
 257
 258   /**
 259    * Bulk operation done
 260    *
 261    * If no more bulk operations are pending, the solver can solve the problem
 262    * with the updated values
 263    */
 264   GAS_solver_bulk_stop s_bulk_stop;
 265 };
 266
 267 /**
 268  * Operation codes for solver information callback
 269  *
 270  * Order of calls is expected to be:
 271  * GAS_OP_SOLVE_START
 272  *
 273  * GAS_OP_SOLVE_STOP
 274  * GAS_OP_SOLVE_UPDATE_NOTIFICATION_START
 275  * GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP
 276  *
 277  */
 278 enum GAS_Solver_Operation
 279 {
 280   /**
 281    * A solution iteration has been started
 282    */
 283   GAS_OP_SOLVE_START,
 284
 285   /**
 286    * A solution iteration has been finished
 287    */
 288   GAS_OP_SOLVE_STOP,
 289
 290   /**
 291    * The setup of the problem as a preparation to solve it was started
 292    */
 293   GAS_OP_SOLVE_SETUP_START,
 294
 295   /**
 296    * The setup of the problem as a preparation to solve is finished
 297    */
 298   GAS_OP_SOLVE_SETUP_STOP,
 299
 300   /**
 301    * Solving of the LP problem was started
 302    * MLP solver only
 303    */
 304   GAS_OP_SOLVE_MLP_LP_START,
 305
 306   /**
 307    * Solving of the LP problem is done
 308    * MLP solver only
 309    */
 310   GAS_OP_SOLVE_MLP_LP_STOP,
 311
 312   /**
 313    * Solving of the MLP problem was started
 314    * MLP solver only
 315    */
 316   GAS_OP_SOLVE_MLP_MLP_START,
 317
 318   /**
 319    * Solving of the MLP problem is done
 320    * MLP solver only
 321    */
 322   GAS_OP_SOLVE_MLP_MLP_STOP,
 323
 324   /**
 325    * After the problem was finished, start notifications about changes
 326    * to addresses
 327    */
 328   GAS_OP_SOLVE_UPDATE_NOTIFICATION_START,
 329
 330   /**
 331    * After the problem was finished, notifications about changes to addresses
 332    * are done
 333    */
 334   GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP
 335 };
 336
 337 /**
 338  * Status of a GAS_Solver_Operation operation
 339  */
 340 enum GAS_Solver_Status
 341 {
 342   /**
 343    * Success
 344    */
 345   GAS_STAT_SUCCESS,
 346
 347   /**
 348    * Failure
 349    */
 350   GAS_STAT_FAIL
 351 };
 352
 353 /**
 354  * Status of the operation
 355  */
 356 enum GAS_Solver_Additional_Information
 357 {
 358   /**
 359    * No more specific information
 360    */
 361   GAS_INFO_NONE,
 362
 363   /**
 364    * A full solution process is performed
 365    * Quite specific to the MLP solver
 366    */
 367   GAS_INFO_FULL,
 368
 369   /**
 370    * An existing solution was reused
 371    * Quite specific to the MLP solver
 372    */
 373   GAS_INFO_UPDATED,
 374
 375   /**
 376    * The proportional solver had to recalculate for a single network
 377    */
 378   GAS_INFO_PROP_SINGLE,
 379
 380   /**
 381    * The proportional solver had to recalculate for all networks
 382    */
 383   GAS_INFO_PROP_ALL
 384 };
 385
 386 /**
 387  * Callback to call with additional information
 388  * Used for measurement
 389  *
 390  * @param cls the closure
 391  * @param op the operation
 392  * @param peer the peer id
 393  * @param kind the preference kind to change
 394  * @param score the new preference score
 395  * @param pref_rel the normalized preference value for this kind over all clients
 396  */
 397 typedef void
 398 (*GAS_solver_information_callback) (void *cls, enum GAS_Solver_Operation op,
 399     enum GAS_Solver_Status stat, enum GAS_Solver_Additional_Information);
 400
 401 /**
 402  * Callback to call from solver when bandwidth for address has changed
 403  *
 404  * @param address the with changed bandwidth assigned
 405  */
 406 typedef void
 407 (*GAS_bandwidth_changed_cb) (void *cls, struct ATS_Address *address);
 408
 409 /**
 410  * Callback to call from solver to obtain application preference values for a
 411  * peer
 412  *
 413  * @param cls the cls
 414  * @param id the peer id
 415  * @return carry of double values containing the preferences with
 416  *      GNUNET_ATS_PreferenceCount elements
 417  */
 418 typedef const double *
 419 (*GAS_get_preferences) (void *cls, const struct GNUNET_PeerIdentity *id);
 420
 421 /**
 422  * Callback to call from solver to obtain transport properties for an
 423  * address
 424  *
 425  * @param cls the cls
 426  * @param address the address
 427  * @return carry of double values containing the preferences with
 428  *      GNUNET_ATS_PreferenceCount elements
 429  */
 430 typedef const double *
 431 (*GAS_get_properties) (void *cls, const struct ATS_Address *address);
 432
 433 /**
 434  * The ATS service will pass a pointer to a struct
 435  * of this type as the first and only argument to the
 436  * entry point of each ATS solver.
 437  */
 438 struct GNUNET_ATS_PluginEnvironment
 439 {
 440   /**
 441    * Configuration handle to be used by the solver
 442    */
 443   const struct GNUNET_CONFIGURATION_Handle *cfg;
 444
 445   /**
 446    * Statistics handle to be used by the solver
 447    */
 448   const struct GNUNET_STATISTICS_Handle *stats;
 449
 450   /**
 451    * Hashmap containing all addresses available
 452    */
 453   struct GNUNET_CONTAINER_MultiPeerMap *addresses;
 454
 455   /**
 456    * ATS addresses callback to be notified about bandwidth assignment changes
 457    */
 458   GAS_bandwidth_changed_cb bandwidth_changed_cb;
 459
 460   /**
 461    * ATS addresses closure to be notified about bandwidth assignment changes
 462    */
 463   void *bw_changed_cb_cls;
 464
 465   /**
 466    * ATS addresses function to obtain preference values
 467    */
 468   GAS_get_preferences get_preferences;
 469
 470   /**
 471    * ATS addresses function closure to obtain preference values
 472    */
 473   void *get_preference_cls;
 474
 475   /**
 476    * ATS addresses function to obtain property values
 477    */
 478   GAS_get_properties get_property;
 479
 480   /**
 481    * ATS addresses function closure to obtain property values
 482    */
 483   void *get_property_cls;
 484
 485   /**
 486    * Callback for solver to call with status information,
 487    * can be NULL
 488    */
 489   GAS_solver_information_callback info_cb;
 490
 491   /**
 492    * Closure for information callback,
 493    * can be NULL
 494    */
 495   void *info_cb_cls;
 496
 497   /**
 498    * The ATS solver plugin functions to call
 499    */
 500   struct GNUNET_ATS_SolverFunctions sf;
 501
 502   /**
 503    *  Available networks
 504    */
 505   int networks[GNUNET_ATS_NetworkTypeCount];
 506
 507   /**
 508    * Number of networks available
 509    */
 510   int network_count;
 511
 512   /**
 513    * Array of configured outbound quotas
 514    * Order according to networks in network array
 515    */
 516   unsigned long long out_quota[GNUNET_ATS_NetworkTypeCount];
 517
 518   /**
 519    * Array of configured inbound quotas
 520    * Order according to networks in network array
 521    */
 522   unsigned long long in_quota[GNUNET_ATS_NetworkTypeCount];
 523 };
 524
 525 #endif