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