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