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  * Transport session for this address has changed
 147  *
 148  * NOTE: values in addresses are already updated
 149  *
 150  * @param solver solver handle
 151  * @param address the address
 152  * @param in_use usage state
 153  */
 154 typedef void
 155 (*GAS_solver_address_inuse_changed) (void *solver, struct ATS_Address *address,
 156     int in_use);
 157
 158 /**
 159  * Network scope for this address has changed
 160  *
 161  * NOTE: values in addresses are already updated
 162  *
 163  * @param solver solver handle
 164  * @param address the address
 165  * @param current_network the current network
 166  * @param new_network the new network
 167  */
 168 typedef void
 169 (*GAS_solver_address_network_changed) (void *solver,
 170     struct ATS_Address *address, uint32_t current_network, uint32_t new_network);
 171
 172 /**
 173  * Get the prefered address for a peer from solver
 174  *
 175  * @param solver the solver to use
 176  * @param addresses the address hashmap containing all addresses
 177  * @param peer the peer
 178  */
 179 typedef const struct ATS_Address *
 180 (*GAS_solver_get_preferred_address) (void *solver,
 181     const struct GNUNET_PeerIdentity *peer);
 182
 183 /**
 184  * Stop getting the prefered address for a peer from solver
 185  *
 186  * @param solver the solver to use
 187  * @param addresses the address hashmap containing all addresses
 188  * @param peer the peer
 189  */
 190 typedef void
 191 (*GAS_solver_stop_get_preferred_address) (void *solver,
 192     const struct GNUNET_PeerIdentity *peer);
 193
 194 /**
 195  * Solver functions
 196  *
 197  * Each solver is required to set up this struct contained in the plugin
 198  * environment struct in during startup
 199  */
 200 struct GNUNET_ATS_SolverFunctions
 201 {
 202
 203   /**
 204    * Add a new address for a peer to the solver
 205    *
 206    * The address is already contained in the addresses hashmap!
 207    */
 208   GAS_solver_address_add s_add;
 209
 210   /**
 211    * Update the properties of an address in the solver
 212    */
 213   GAS_solver_address_property_changed s_address_update_property;
 214
 215   /**
 216    * Update the session of an address in the solver
 217    */
 218   GAS_solver_address_session_changed s_address_update_session;
 219
 220   /**
 221    * Notify the solver that in address is (not) actively used by transport
 222    * to communicate with a remote peer
 223    */
 224   GAS_solver_address_inuse_changed s_address_update_inuse;
 225
 226   /**
 227    * Notify solver that the network an address is located in has changed
 228    */
 229   GAS_solver_address_network_changed s_address_update_network;
 230
 231   /**
 232    * Tell solver to notify ATS if the address to use changes for a specific
 233    * peer using the bandwidth changed callback
 234    *
 235    * The solver must only notify about changes for peers with pending address
 236    * requests!
 237    */
 238   GAS_solver_get_preferred_address s_get;
 239
 240   /**
 241    * Tell solver stop notifying ATS about changes for this peers
 242    *
 243    * The solver must only notify about changes for peers with pending address
 244    * requests!
 245    */
 246   GAS_solver_stop_get_preferred_address s_get_stop;
 247
 248   /**
 249    * Delete an address in the solver
 250    *
 251    * The address is not contained in the address hashmap anymore!
 252    */
 253   GAS_solver_address_delete s_del;
 254
 255   /**
 256    * Change relative preference for quality in solver
 257    */
 258   GAS_solver_address_change_preference s_pref;
 259
 260   /**
 261    * Give feedback about the current assignment
 262    */
 263   GAS_solver_address_feedback_preference s_feedback;
 264
 265   /**
 266    * Start a bulk operation
 267    *
 268    * Used if many values have to be updated at the same time.
 269    * When a bulk operation is pending the solver does not have to resolve
 270    * the problem since more updates will follow anyway
 271    *
 272    * For each call to bulk_start, a call to bulk_stop is required!
 273    */
 274   GAS_solver_bulk_start s_bulk_start;
 275
 276   /**
 277    * Bulk operation done
 278    *
 279    * If no more bulk operations are pending, the solver can solve the problem
 280    * with the updated values
 281    */
 282   GAS_solver_bulk_stop s_bulk_stop;
 283 };
 284
 285 /**
 286  * Operation codes for solver information callback
 287  *
 288  * Order of calls is expected to be:
 289  * GAS_OP_SOLVE_START
 290  *
 291  * GAS_OP_SOLVE_STOP
 292  * GAS_OP_SOLVE_UPDATE_NOTIFICATION_START
 293  * GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP
 294  *
 295  */
 296 enum GAS_Solver_Operation
 297 {
 298   /**
 299    * A solution iteration has been started
 300    */
 301   GAS_OP_SOLVE_START,
 302
 303   /**
 304    * A solution iteration has been finished
 305    */
 306   GAS_OP_SOLVE_STOP,
 307
 308   /**
 309    * The setup of the problem as a preparation to solve it was started
 310    */
 311   GAS_OP_SOLVE_SETUP_START,
 312
 313   /**
 314    * The setup of the problem as a preparation to solve is finished
 315    */
 316   GAS_OP_SOLVE_SETUP_STOP,
 317
 318   /**
 319    * Solving of the LP problem was started
 320    * MLP solver only
 321    */
 322   GAS_OP_SOLVE_MLP_LP_START,
 323
 324   /**
 325    * Solving of the LP problem is done
 326    * MLP solver only
 327    */
 328   GAS_OP_SOLVE_MLP_LP_STOP,
 329
 330   /**
 331    * Solving of the MLP problem was started
 332    * MLP solver only
 333    */
 334   GAS_OP_SOLVE_MLP_MLP_START,
 335
 336   /**
 337    * Solving of the MLP problem is done
 338    * MLP solver only
 339    */
 340   GAS_OP_SOLVE_MLP_MLP_STOP,
 341
 342   /**
 343    * After the problem was finished, start notifications about changes
 344    * to addresses
 345    */
 346   GAS_OP_SOLVE_UPDATE_NOTIFICATION_START,
 347
 348   /**
 349    * After the problem was finished, notifications about changes to addresses
 350    * are done
 351    */
 352   GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP
 353 };
 354
 355 /**
 356  * Status of a GAS_Solver_Operation operation
 357  */
 358 enum GAS_Solver_Status
 359 {
 360   /**
 361    * Success
 362    */
 363   GAS_STAT_SUCCESS,
 364
 365   /**
 366    * Failure
 367    */
 368   GAS_STAT_FAIL
 369 };
 370
 371 /**
 372  * Status of the operation
 373  */
 374 enum GAS_Solver_Additional_Information
 375 {
 376   /**
 377    * No more specific information
 378    */
 379   GAS_INFO_NONE,
 380
 381   /**
 382    * A full solution process is performed
 383    * Quite specific to the MLP solver
 384    */
 385   GAS_INFO_FULL,
 386
 387   /**
 388    * An existing solution was reused
 389    * Quite specific to the MLP solver
 390    */
 391   GAS_INFO_UPDATED,
 392
 393   /**
 394    * The proportional solver had to recalculate for a single network
 395    */
 396   GAS_INFO_PROP_SINGLE,
 397
 398   /**
 399    * The proportional solver had to recalculate for all networks
 400    */
 401   GAS_INFO_PROP_ALL
 402 };
 403
 404 /**
 405  * Callback to call with additional information
 406  * Used for measurement
 407  *
 408  * @param cls the closure
 409  * @param op the operation
 410  * @param peer the peer id
 411  * @param kind the preference kind to change
 412  * @param score the new preference score
 413  * @param pref_rel the normalized preference value for this kind over all clients
 414  */
 415 typedef void
 416 (*GAS_solver_information_callback) (void *cls, enum GAS_Solver_Operation op,
 417     enum GAS_Solver_Status stat, enum GAS_Solver_Additional_Information);
 418
 419 /**
 420  * Callback to call from solver when bandwidth for address has changed
 421  *
 422  * @param address the with changed bandwidth assigned
 423  */
 424 typedef void
 425 (*GAS_bandwidth_changed_cb) (void *cls, struct ATS_Address *address);
 426
 427 /**
 428  * Callback to call from solver to obtain application preference values for a
 429  * peer
 430  *
 431  * @param cls the cls
 432  * @param id the peer id
 433  * @return carry of double values containing the preferences with
 434  *      GNUNET_ATS_PreferenceCount elements
 435  */
 436 typedef const double *
 437 (*GAS_get_preferences) (void *cls, const struct GNUNET_PeerIdentity *id);
 438
 439 /**
 440  * Callback to call from solver to obtain transport properties for an
 441  * address
 442  *
 443  * @param cls the cls
 444  * @param address the address
 445  * @return carry of double values containing the preferences with
 446  *      GNUNET_ATS_PreferenceCount elements
 447  */
 448 typedef const double *
 449 (*GAS_get_properties) (void *cls, const struct ATS_Address *address);
 450
 451 /**
 452  * The ATS service will pass a pointer to a struct
 453  * of this type as the first and only argument to the
 454  * entry point of each ATS solver.
 455  */
 456 struct GNUNET_ATS_PluginEnvironment
 457 {
 458   /**
 459    * Configuration handle to be used by the solver
 460    */
 461   const struct GNUNET_CONFIGURATION_Handle *cfg;
 462
 463   /**
 464    * Statistics handle to be used by the solver
 465    */
 466   const struct GNUNET_STATISTICS_Handle *stats;
 467
 468   /**
 469    * Hashmap containing all addresses available
 470    */
 471   struct GNUNET_CONTAINER_MultiPeerMap *addresses;
 472
 473   /**
 474    * ATS addresses callback to be notified about bandwidth assignment changes
 475    */
 476   GAS_bandwidth_changed_cb bandwidth_changed_cb;
 477
 478   /**
 479    * ATS addresses closure to be notified about bandwidth assignment changes
 480    */
 481   void *bw_changed_cb_cls;
 482
 483   /**
 484    * ATS addresses function to obtain preference values
 485    */
 486   GAS_get_preferences get_preferences;
 487
 488   /**
 489    * ATS addresses function closure to obtain preference values
 490    */
 491   void *get_preference_cls;
 492
 493   /**
 494    * ATS addresses function to obtain property values
 495    */
 496   GAS_get_properties get_property;
 497
 498   /**
 499    * ATS addresses function closure to obtain property values
 500    */
 501   void *get_property_cls;
 502
 503   /**
 504    * Callback for solver to call with status information,
 505    * can be NULL
 506    */
 507   GAS_solver_information_callback info_cb;
 508
 509   /**
 510    * Closure for information callback,
 511    * can be NULL
 512    */
 513   void *info_cb_cls;
 514
 515   /**
 516    * The ATS solver plugin functions to call
 517    */
 518   struct GNUNET_ATS_SolverFunctions sf;
 519
 520   /**
 521    *  Available networks
 522    */
 523   int networks[GNUNET_ATS_NetworkTypeCount];
 524
 525   /**
 526    * Number of networks available
 527    */
 528   int network_count;
 529
 530   /**
 531    * Array of configured outbound quotas
 532    * Order according to networks in network array
 533    */
 534   unsigned long long out_quota[GNUNET_ATS_NetworkTypeCount];
 535
 536   /**
 537    * Array of configured inbound quotas
 538    * Order according to networks in network array
 539    */
 540   unsigned long long in_quota[GNUNET_ATS_NetworkTypeCount];
 541 };
 542
 543 #endif