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