src/include/gnunet_ats_service.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2010,2011 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  * @file include/gnunet_ats_service.h
  22  * @brief automatic transport selection and outbound bandwidth determination
  23  * @author Christian Grothoff
  24  * @author Matthias Wachs
  25  *
  26  * TODO:
  27  * - move GNUNET_TRANSPORT_ATS* in here and rename...
  28  */
  29 #ifndef GNUNET_ATS_SERVICE_H
  30 #define GNUNET_ATS_SERVICE_H
  31
  32 #include "gnunet_constants.h"
  33 #include "gnunet_util_lib.h"
  34 #include "gnunet_transport_service.h"
  35 #include "gnunet_transport_plugin.h"
  36
  37
  38 /* ******************************** Scheduling API ***************************** */
  39
  40 /**
  41  * Handle to the ATS subsystem for bandwidth/transport scheduling information.
  42  */
  43 struct GNUNET_ATS_SchedulingHandle;
  44
  45
  46 /**
  47  * Opaque session handle, defined by plugins.  Contents not known to ATS.
  48  */
  49 struct Session;
  50
  51
  52 /**
  53  * Signature of a function called by ATS with the current bandwidth
  54  * and address preferences as determined by ATS.
  55  *
  56  * @param cls closure
  57  * @param peer identity of the new peer
  58  * @param plugin_name name of the plugin, NULL if we have no suggestion
  59  * @param plugin_addr suggested address, NULL if we have no suggestion
  60  * @param plugin_addr_len number of bytes in plugin_addr
  61  * @param session session to use
  62  * @param bandwidth_out assigned outbound bandwidth for the connection
  63  * @param bandwidth_in assigned inbound bandwidth for the connection
  64  * @param ats performance data for the address (as far as known)
  65  * @param ats_count number of performance records in 'ats'
  66  */
  67 typedef void (*GNUNET_ATS_AddressSuggestionCallback) (void *cls,
  68                                                       const struct
  69                                                       GNUNET_PeerIdentity *
  70                                                       peer,
  71                                                       const char *plugin_name,
  72                                                       const void *plugin_addr,
  73                                                       size_t plugin_addr_len,
  74                                                       struct Session * session,
  75                                                       struct
  76                                                       GNUNET_BANDWIDTH_Value32NBO
  77                                                       bandwidth_out,
  78                                                       struct
  79                                                       GNUNET_BANDWIDTH_Value32NBO
  80                                                       bandwidth_in,
  81                                                       const struct
  82                                                       GNUNET_TRANSPORT_ATS_Information
  83                                                       * ats,
  84                                                       uint32_t ats_count);
  85
  86
  87 /**
  88  * Initialize the ATS subsystem.
  89  *
  90  * @param cfg configuration to use
  91  * @param suggest_cb notification to call whenever the suggestation changed
  92  * @param suggest_cb_cls closure for 'suggest_cb'
  93  * @return ats context
  94  */
  95 struct GNUNET_ATS_SchedulingHandle *
  96 GNUNET_ATS_scheduling_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
  97                             GNUNET_ATS_AddressSuggestionCallback suggest_cb,
  98                             void *suggest_cb_cls);
  99
 100
 101 /**
 102  * Client is done with ATS scheduling, release resources.
 103  *
 104  * @param sh handle to release
 105  */
 106 void
 107 GNUNET_ATS_scheduling_done (struct GNUNET_ATS_SchedulingHandle *sh);
 108
 109
 110 /**
 111  * We would like to establish a new connection with a peer.  ATS
 112  * should suggest a good address to begin with.
 113  *
 114  * @param sh handle
 115  * @param peer identity of the peer we need an address for
 116  */
 117 void
 118 GNUNET_ATS_suggest_address (struct GNUNET_ATS_SchedulingHandle *sh,
 119                             const struct GNUNET_PeerIdentity *peer);
 120
 121
 122 /**
 123  * We have updated performance statistics for a given address.  Note
 124  * that this function can be called for addresses that are currently
 125  * in use as well as addresses that are valid but not actively in use.
 126  * Furthermore, the peer may not even be connected to us right now (in
 127  * which case the call may be ignored or the information may be stored
 128  * for later use).  Update bandwidth assignments.
 129  *
 130  * @param sh handle
 131  * @param peer identity of the new peer
 132  * @param plugin_name name of the transport plugin
 133  * @param plugin_addr address  (if available)
 134  * @param plugin_addr_len number of bytes in plugin_addr
 135  * @param session session handle (if available)
 136  * @param ats performance data for the address
 137  * @param ats_count number of performance records in 'ats'
 138  */
 139 void
 140 GNUNET_ATS_address_update (struct GNUNET_ATS_SchedulingHandle *sh,
 141                            const struct GNUNET_PeerIdentity *peer,
 142                            const char *plugin_name,
 143                            const void *plugin_addr, size_t plugin_addr_len,
 144                            struct Session *session,
 145                            const struct GNUNET_TRANSPORT_ATS_Information *ats,
 146                            uint32_t ats_count);
 147
 148
 149 /**
 150  * A session got destroyed, stop including it as a valid address.
 151  *
 152  * @param sh handle
 153  * @param peer identity of the peer
 154  * @param plugin_name name of the transport plugin
 155  * @param plugin_addr address  (if available)
 156  * @param plugin_addr_len number of bytes in plugin_addr
 157  * @param session session handle that is no longer valid (if available)
 158  */
 159 void
 160 GNUNET_ATS_address_destroyed (struct GNUNET_ATS_SchedulingHandle *sh,
 161                               const struct GNUNET_PeerIdentity *peer,
 162                               const char *plugin_name,
 163                               const void *plugin_addr,
 164                               size_t plugin_addr_len,
 165                               struct Session *session);
 166
 167
 168 /* ******************************** Performance API ***************************** */
 169
 170 /**
 171  * ATS Handle to obtain and/or modify performance information.
 172  */
 173 struct GNUNET_ATS_PerformanceHandle;
 174
 175
 176 /**
 177  * Signature of a function that is called with QoS information about a peer.
 178  *
 179  * @param cls closure
 180  * @param peer identity of the new peer
 181  * @param plugin_name name of the plugin, NULL if we have no suggestion
 182  * @param plugin_addr suggested address, NULL if we have no suggestion
 183  * @param plugin_addr_len number of bytes in plugin_addr
 184  * @param bandwidth_out assigned outbound bandwidth for the connection
 185  * @param bandwidth_in assigned inbound bandwidth for the connection
 186  * @param ats performance data for the address (as far as known)
 187  * @param ats_count number of performance records in 'ats'
 188  */
 189 typedef void (*GNUNET_ATS_PeerInformationCallback) (void *cls,
 190                                                     const struct
 191                                                     GNUNET_PeerIdentity *
 192                                                     peer,
 193                                                     const char *plugin_name,
 194                                                     const void *plugin_addr,
 195                                                     size_t plugin_addr_len,
 196                                                     struct
 197                                                     GNUNET_BANDWIDTH_Value32NBO
 198                                                     bandwidth_out,
 199                                                     struct
 200                                                     GNUNET_BANDWIDTH_Value32NBO
 201                                                     bandwidth_in,
 202                                                     const struct
 203                                                     GNUNET_TRANSPORT_ATS_Information
 204                                                     * ats,
 205                                                     uint32_t ats_count);
 206
 207
 208 /**
 209  * Get handle to access performance API of the ATS subsystem.
 210  *
 211  * @param cfg configuration to use
 212  * @param infocb function to call on performance changes, can be NULL
 213  * @param infocb_cls closure for infocb
 214  * @return ats performance context
 215  */
 216 struct GNUNET_ATS_PerformanceHandle *
 217 GNUNET_ATS_performance_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
 218                              GNUNET_ATS_PeerInformationCallback infocb,
 219                              void *infocb_cls);
 220
 221
 222 /**
 223  * Client is done using the ATS performance subsystem, release resources.
 224  *
 225  * @param ph handle
 226  */
 227 void
 228 GNUNET_ATS_performance_done (struct GNUNET_ATS_PerformanceHandle *ph);
 229
 230
 231 /**
 232  * Function called with reservation result.
 233  *
 234  * @param cls closure
 235  * @param peer identifies the peer
 236  * @param amount set to the amount that was actually reserved or unreserved;
 237  *               either the full requested amount or zero (no partial reservations)
 238  * @param res_delay if the reservation could not be satisfied (amount was 0), how
 239  *        long should the client wait until re-trying?
 240  */
 241 typedef void (*GNUNET_ATS_ReservationCallback) (void *cls,
 242                                                 const struct
 243                                                 GNUNET_PeerIdentity *
 244                                                 peer,
 245                                                 int32_t amount,
 246                                                 struct
 247                                                 GNUNET_TIME_Relative
 248                                                 res_delay);
 249
 250
 251
 252 /**
 253  * Context that can be used to cancel a peer information request.
 254  */
 255 struct GNUNET_ATS_ReservationContext;
 256
 257
 258 /**
 259  * Reserve inbound bandwidth from the given peer.  ATS will look at
 260  * the current amount of traffic we receive from the peer and ensure
 261  * that the peer could add 'amount' of data to its stream.
 262  *
 263  * @param ph performance handle
 264  * @param peer identifies the peer
 265  * @param amount reserve N bytes for receiving, negative
 266  *                amounts can be used to undo a (recent) reservation;
 267  * @param rcb function to call with the resulting reservation information
 268  * @param rcb_cls closure for info
 269  * @return NULL on error
 270  * @deprecated will be replaced soon
 271  */
 272 struct GNUNET_ATS_ReservationContext *
 273 GNUNET_ATS_reserve_bandwidth (struct GNUNET_ATS_PerformanceHandle *ph,
 274                               const struct GNUNET_PeerIdentity *peer,
 275                               int32_t amount,
 276                               GNUNET_ATS_ReservationCallback rcb,
 277                               void *rcb_cls);
 278
 279
 280 /**
 281  * Cancel request for reserving bandwidth.
 282  *
 283  * @param rc context returned by the original GNUNET_ATS_reserve_bandwidth call
 284  */
 285 void
 286 GNUNET_ATS_reserve_bandwidth_cancel (struct
 287                                      GNUNET_ATS_ReservationContext *rc);
 288
 289
 290
 291 /**
 292  * Enum defining all known preference categories.
 293  */
 294 enum GNUNET_ATS_PreferenceKind
 295 {
 296
 297   /**
 298    * End of preference list.
 299    */
 300   GNUNET_ATS_PREFERENCE_END = 0,
 301
 302   /**
 303    * Change the peer's bandwidth value (value per byte of bandwidth in
 304    * the goal function) to the given amount.  The argument is followed
 305    * by a double value giving the desired value (can be negative).
 306    * Preference changes are forgotten if peers disconnect.
 307    */
 308   GNUNET_ATS_PREFERENCE_BANDWIDTH,
 309
 310   /**
 311    * Change the peer's latency value to the given amount.  The
 312    * argument is followed by a double value giving the desired value
 313    * (can be negative).  The absolute score in the goal function is
 314    * the inverse of the latency in ms (minimum: 1 ms) multiplied by
 315    * the latency preferences.
 316    */
 317   GNUNET_ATS_PREFERENCE_LATENCY
 318
 319 };
 320
 321
 322 /**
 323  * Change preferences for the given peer. Preference changes are forgotten if peers
 324  * disconnect.
 325  *
 326  * @param ph performance handle
 327  * @param peer identifies the peer
 328  * @param ... 0-terminated specification of the desired changes
 329  */
 330 void
 331 GNUNET_ATS_change_preference (struct GNUNET_ATS_PerformanceHandle *ph,
 332                               const struct GNUNET_PeerIdentity *peer,
 333                               ...);
 334
 335
 336
 337 #endif
 338 /* end of file gnunet-service-transport_ats.h */