src/include/gnunet_ats_plugin.h

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