src/include/gnunet_ats_plugin.h

   1 /*
   2    This file is part of GNUnet
   3    Copyright (C) 2009-2015 GNUnet e.V.
   4
   5    GNUnet is free software: you can redistribute it and/or modify it
   6    under the terms of the GNU Affero General Public License as published
   7    by the Free Software Foundation, either version 3 of the License,
   8    or (at your 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    Affero General Public License for more details.
  14
  15    You should have received a copy of the GNU Affero General Public License
  16    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18      SPDX-License-Identifier: AGPL3.0-or-later
  19  */
  20
  21 /**
  22  * @author Christian Grothoff
  23  *
  24  * @file
  25  * API for the ATS solvers.
  26  *
  27  * @defgroup ats-plugin  ATS service plugin API
  28  * Plugin API for the ATS service.
  29  *
  30  * Specifies the struct that is given to the plugin's entry method and the other
  31  * struct that must be returned.  Note that the destructors of ATS plugins will
  32  * be given the value returned by the constructor and is expected to return a
  33  * NULL pointer.
  34  *
  35  * @{
  36  */
  37 #ifndef PLUGIN_ATS_H
  38 #define PLUGIN_ATS_H
  39
  40 #include "gnunet_ats_service.h"
  41 #include "gnunet_statistics_service.h"
  42
  43 /**
  44  * Representation of an address the plugin can choose from.
  45  */
  46 struct ATS_Address;
  47
  48 /**
  49  * Change the preference for a peer
  50  *
  51  * @param handle the solver handle
  52  * @param client the client sending this request
  53  * @param peer the peer id
  54  * @param kind the preference kind to change
  55  * @param score the new preference score
  56  * @param pref_rel the normalized preference value for this kind over all clients
  57  */
  58 typedef void
  59 (*GAS_solver_address_change_preference) (void *solver,
  60                                          const struct GNUNET_PeerIdentity *peer,
  61                                          enum GNUNET_ATS_PreferenceKind kind,
  62                                          double pref_rel);
  63
  64
  65 /**
  66  * Give feedback about the current assignment
  67  *
  68  * @param handle the solver handle
  69  * @param application the application sending this request
  70  * @param peer the peer id
  71  * @param scope the time interval for this feedback: [now - scope .. now]
  72  * @param kind the preference kind for this feedback
  73  * @param score the feedback score
  74  */
  75 typedef void
  76 (*GAS_solver_address_feedback_preference) (void *solver,
  77                                            struct GNUNET_SERVICE_Client *
  78                                            application,
  79                                            const struct
  80                                            GNUNET_PeerIdentity *peer,
  81                                            const struct GNUNET_TIME_Relative
  82                                            scope,
  83                                            enum GNUNET_ATS_PreferenceKind kind,
  84                                            double score);
  85
  86 /**
  87  * Notify the solver about a bulk operation changing possibly a lot of values
  88  * Solver will not resolve until all bulk operations are marked as done
  89  *
  90  * @param solver the solver
  91  */
  92 typedef void
  93 (*GAS_solver_bulk_start) (void *solver);
  94
  95
  96 /**
  97  * Mark a bulk operation as done
  98  * Solver will resolve if values have changed
  99  *
 100  * @param solver the solver
 101  */
 102 typedef void
 103 (*GAS_solver_bulk_stop) (void *solver);
 104
 105
 106 /**
 107  * Add a single address within a network to the solver
 108  *
 109  * @param solver the solver Handle
 110  * @param address the address to add
 111  * @param network network type of this address
 112  */
 113 typedef void
 114 (*GAS_solver_address_add) (void *solver,
 115                            struct ATS_Address *address,
 116                            uint32_t network);
 117
 118
 119 /**
 120  * Delete an address or just the session from the solver
 121  *
 122  * @param solver the solver Handle
 123  * @param address the address to delete
 124  */
 125 typedef void
 126 (*GAS_solver_address_delete) (void *solver,
 127                               struct ATS_Address *address);
 128
 129
 130 /**
 131  * Transport properties for this address have changed
 132  *
 133  * @param solver solver handle
 134  * @param address the address
 135  */
 136 typedef void
 137 (*GAS_solver_address_property_changed) (void *solver,
 138                                         struct ATS_Address *address);
 139
 140
 141 /**
 142  * Get the prefered address for a peer from solver
 143  *
 144  * @param solver the solver to use
 145  * @param peer the peer
 146  */
 147 typedef void
 148 (*GAS_solver_get_preferred_address) (void *solver,
 149                                      const struct GNUNET_PeerIdentity *peer);
 150
 151
 152 /**
 153  * Stop getting the prefered address for a peer from solver
 154  *
 155  * @param solver the solver to use
 156  * @param peer the peer
 157  */
 158 typedef void
 159 (*GAS_solver_stop_get_preferred_address) (void *solver,
 160                                           const struct
 161                                           GNUNET_PeerIdentity *peer);
 162
 163
 164 /**
 165  * Solver functions.
 166  *
 167  * Each solver is required to set up and return an instance
 168  * of this struct during initialization.
 169  */
 170 struct GNUNET_ATS_SolverFunctions
 171 {
 172   /**
 173    * Closure to pass to all solver functions in this struct.
 174    */
 175   void *cls;
 176
 177   /**
 178    * Add a new address for a peer to the solver
 179    *
 180    * The address is already contained in the addresses hashmap!
 181    */
 182   GAS_solver_address_add s_add;
 183
 184   /**
 185    * Update the properties of an address in the solver
 186    */
 187   GAS_solver_address_property_changed s_address_update_property;
 188
 189   /**
 190    * Tell solver to notify ATS if the address to use changes for a specific
 191    * peer using the bandwidth changed callback
 192    *
 193    * The solver must only notify about changes for peers with pending address
 194    * requests!
 195    */
 196   GAS_solver_get_preferred_address s_get;
 197
 198   /**
 199    * Tell solver stop notifying ATS about changes for this peers
 200    *
 201    * The solver must only notify about changes for peers with pending address
 202    * requests!
 203    */
 204   GAS_solver_stop_get_preferred_address s_get_stop;
 205
 206   /**
 207    * Delete an address in the solver
 208    *
 209    * The address is not contained in the address hashmap anymore!
 210    */
 211   GAS_solver_address_delete s_del;
 212
 213   /**
 214    * Change relative preference for quality in solver
 215    */
 216   GAS_solver_address_change_preference s_pref;
 217
 218   /**
 219    * Give feedback about the current assignment
 220    */
 221   GAS_solver_address_feedback_preference s_feedback;
 222
 223   /**
 224    * Start a bulk operation
 225    *
 226    * Used if many values have to be updated at the same time.
 227    * When a bulk operation is pending the solver does not have to resolve
 228    * the problem since more updates will follow anyway
 229    *
 230    * For each call to bulk_start, a call to bulk_stop is required!
 231    */
 232   GAS_solver_bulk_start s_bulk_start;
 233
 234   /**
 235    * Bulk operation done
 236    *
 237    * If no more bulk operations are pending, the solver can solve the problem
 238    * with the updated values
 239    */
 240   GAS_solver_bulk_stop s_bulk_stop;
 241 };
 242
 243
 244 /**
 245  * Operation codes for solver information callback
 246  *
 247  * Order of calls is expected to be:
 248  * #GAS_OP_SOLVE_START
 249  * #GAS_OP_SOLVE_STOP
 250  * #GAS_OP_SOLVE_UPDATE_NOTIFICATION_START
 251  * #GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP
 252  *
 253  */
 254 enum GAS_Solver_Operation
 255 {
 256   /**
 257    * A solution iteration has been started
 258    */
 259   GAS_OP_SOLVE_START,
 260
 261   /**
 262    * A solution iteration has been finished
 263    */
 264   GAS_OP_SOLVE_STOP,
 265
 266   /**
 267    * The setup of the problem as a preparation to solve it was started
 268    */
 269   GAS_OP_SOLVE_SETUP_START,
 270
 271   /**
 272    * The setup of the problem as a preparation to solve is finished
 273    */
 274   GAS_OP_SOLVE_SETUP_STOP,
 275
 276   /**
 277    * Solving of the LP problem was started
 278    * MLP solver only
 279    */
 280   GAS_OP_SOLVE_MLP_LP_START,
 281
 282   /**
 283    * Solving of the LP problem is done
 284    * MLP solver only
 285    */
 286   GAS_OP_SOLVE_MLP_LP_STOP,
 287
 288   /**
 289    * Solving of the MLP problem was started
 290    * MLP solver only
 291    */
 292   GAS_OP_SOLVE_MLP_MLP_START,
 293
 294   /**
 295    * Solving of the MLP problem is done
 296    * MLP solver only
 297    */
 298   GAS_OP_SOLVE_MLP_MLP_STOP,
 299
 300   /**
 301    * After the problem was finished, start notifications about changes
 302    * to addresses
 303    */
 304   GAS_OP_SOLVE_UPDATE_NOTIFICATION_START,
 305
 306   /**
 307    * After the problem was finished, notifications about changes to addresses
 308    * are done
 309    */
 310   GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP
 311 };
 312
 313
 314 /**
 315  * Status of a GAS_Solver_Operation operation
 316  */
 317 enum GAS_Solver_Status
 318 {
 319   /**
 320    * Success
 321    */
 322   GAS_STAT_SUCCESS,
 323
 324   /**
 325    * Failure
 326    */
 327   GAS_STAT_FAIL
 328 };
 329
 330
 331 /**
 332  * Status of the operation
 333  */
 334 enum GAS_Solver_Additional_Information
 335 {
 336   /**
 337    * No more specific information
 338    */
 339   GAS_INFO_NONE,
 340
 341   /**
 342    * A full solution process is performed
 343    * Quite specific to the MLP solver
 344    */
 345   GAS_INFO_FULL,
 346
 347   /**
 348    * An existing solution was reused
 349    * Quite specific to the MLP solver
 350    */
 351   GAS_INFO_UPDATED,
 352
 353   /**
 354    * The proportional solver had to recalculate for a single network
 355    */
 356   GAS_INFO_PROP_SINGLE,
 357
 358   /**
 359    * The proportional solver had to recalculate for all networks
 360    */
 361   GAS_INFO_PROP_ALL
 362 };
 363
 364
 365 /**
 366  * Callback to call with additional information
 367  * Used for measurement
 368  *
 369  * @param cls the closure
 370  * @param op the operation
 371  */
 372 typedef void
 373 (*GAS_solver_information_callback) (void *cls,
 374                                     enum GAS_Solver_Operation op,
 375                                     enum GAS_Solver_Status stat,
 376                                     enum GAS_Solver_Additional_Information);
 377
 378
 379 /**
 380  * Callback to call from solver when bandwidth for address has changed
 381  *
 382  * @param address the with changed bandwidth assigned
 383  */
 384 typedef void
 385 (*GAS_bandwidth_changed_cb) (void *cls,
 386                              struct ATS_Address *address);
 387
 388
 389 /**
 390  * Callback to call from solver to obtain application preference
 391  * values for a peer.
 392  *
 393  * @param cls the cls
 394  * @param id the peer id
 395  * @return carry of double values containing the preferences with
 396  *      GNUNET_ATS_PreferenceCount elements
 397  */
 398 typedef const double *
 399 (*GAS_get_preferences) (void *cls,
 400                         const struct GNUNET_PeerIdentity *id);
 401
 402
 403 /**
 404  * Callback to call from solver to obtain application connectivity
 405  * preferences for a peer.
 406  *
 407  * @param cls the cls
 408  * @param id the peer id
 409  * @return 0 if connectivity is not desired, non-null if address
 410  *      suggestions are requested
 411  */
 412 typedef unsigned int
 413 (*GAS_get_connectivity) (void *cls,
 414                          const struct GNUNET_PeerIdentity *id);
 415
 416
 417 /**
 418  * The ATS plugin will pass a pointer to a struct
 419  * of this type as to the initialization function
 420  * of the ATS plugins.
 421  */
 422 struct GNUNET_ATS_PluginEnvironment
 423 {
 424   /**
 425    * Configuration handle to be used by the solver
 426    */
 427   const struct GNUNET_CONFIGURATION_Handle *cfg;
 428
 429   /**
 430    * Statistics handle to be used by the solver
 431    */
 432   struct GNUNET_STATISTICS_Handle *stats;
 433
 434   /**
 435    * Closure to pass to all callbacks in this struct.
 436    */
 437   void *cls;
 438
 439   /**
 440    * Hashmap containing all addresses available
 441    */
 442   struct GNUNET_CONTAINER_MultiPeerMap *addresses;
 443
 444   /**
 445    * ATS addresses callback to be notified about bandwidth assignment changes
 446    */
 447   GAS_bandwidth_changed_cb bandwidth_changed_cb;
 448
 449   /**
 450    * ATS addresses function to obtain preference values
 451    */
 452   GAS_get_preferences get_preferences;
 453
 454   /**
 455    * ATS addresses function to obtain preference values
 456    */
 457   GAS_get_connectivity get_connectivity;
 458
 459   /**
 460    * Callback for solver to call with status information,
 461    * can be NULL
 462    */
 463   GAS_solver_information_callback info_cb;
 464
 465   /**
 466    * Number of networks available, size of the @e out_quota
 467    * and @e in_quota arrays.
 468    */
 469   unsigned int network_count;
 470
 471   /**
 472    * Array of configured outbound quotas
 473    * Order according to networks in network array
 474    */
 475   unsigned long long out_quota[GNUNET_NT_COUNT];
 476
 477   /**
 478    * Array of configured inbound quotas
 479    * Order according to networks in network array
 480    */
 481   unsigned long long in_quota[GNUNET_NT_COUNT];
 482 };
 483
 484 #endif
 485
 486 /** @} */  /* end of group */