src/ats/gnunet-service-ats_addresses.h

   1 /*
   2  This file is part of GNUnet.
   3  Copyright (C) 2011-2014 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  * @file ats/gnunet-service-ats_addresses.h
  21  * @brief ats service address management
  22  * @author Matthias Wachs
  23  * @author Christian Grothoff
  24  */
  25 #ifndef GNUNET_SERVICE_ATS_ADDRESSES_H
  26 #define GNUNET_SERVICE_ATS_ADDRESSES_H
  27
  28 #include "gnunet_util_lib.h"
  29 #include "gnunet_ats_service.h"
  30 #include "gnunet-service-ats.h"
  31 #include "ats.h"
  32
  33 /**
  34  * NOTE: Do not change this documentation. This documentation is based on
  35  * gnunet.org:/vcs/fsnsg/ats-paper.git/tech-doku/ats-tech-guide.tex
  36  * use build_txt.sh to generate plaintext output
  37  *
  38  *   1 ATS addresses : ATS address management
  39  *
  40  *    This ATS addresses ("addresses") component manages the addresses known to
  41  *    ATS service and suggests addresses to transport service when it is
  42  *    interested in address suggestion for a peer. ATS addresses also
  43  *    instantiates the bandwidth assignment mechanism (solver), notifies it
  44  *    about changes to addresses and forwards changes to bandwidth assignments
  45  *    to transport, depending if transport is interested in this change.
  46  *
  47  *     1.1 Input data
  48  *
  49  *       1.1.1 Addresses
  50  *
  51  *    Addresses are added by specifying peer ID, plugin, address, address length
  52  *    and session, if available. ATS information can be specified if available.
  53  *
  54  *       1.1.2 Networks
  55  *
  56  *    ATS specifies a fix set of networks an address can belong to. For each
  57  *    network an inbound and outbound quota will be specified. The available
  58  *    networks and addtional helper varaibles are defined in
  59  *    gnunet_ats_service.h. At the moment 5 networks are defined:
  60  *      * GNUNET_NT_UNSPECIFIED
  61  *      * GNUNET_NT_LOOPBACK
  62  *      * GNUNET_NT_LAN
  63  *      * GNUNET_NT_WAN
  64  *      * GNUNET_NT_WLAN
  65  *
  66  *    The total number of networks defined is stored in
  67  *    GNUNET_NT_COUNT GNUNET_ATS_NetworkType can be used array
  68  *    initializer for an int array, while GNUNET_ATS_NetworkType is an
  69  *    initializer for a char array containing a string description of all
  70  *    networks
  71  *
  72  *       1.1.3 Quotas
  73  *
  74  *    An inbound and outbound quota for each of the networks mentioned in 1.1.2
  75  *    is loaded from ats configuration during initialization. This quota defines
  76  *    to total amount of inbound and outbound traffic allowed for a specific
  77  *    network. The configuration values used are in section ats:
  78  *      * "NETWORK"_QUOTA_IN = <value>
  79  *      * "NETWORK"_QUOTA_IN = <value>
  80  *
  81  *    You can specify quotas by setting the <value> to a:
  82  *      * unrestricted: unlimited
  83  *      * number of bytes: e.g. 10240
  84  *      * fancy value: e.g. 64 Kib
  85  *
  86  *    unlimited is defined as GNUNET_ATS_MaxBandwidthString and equivalent to
  87  *    the value GNUNET_ATS_MaxBandwidth Important predefined values for quotas
  88  *    are:
  89  *      * GNUNET_ATS_DefaultBandwidth: 65536
  90  *      * GNUNET_ATS_MaxBandwidth: UINT32_MAX
  91  *      * GNUNET_CONSTANTS_DEFAULT_BW_IN_OUT: 1024
  92  *
  93  *    Details of loading quotas and default values will be described on
  94  *
  95  *       1.1.4 Preference values
  96  *
  97  *     1.2 Data structures used
  98  *
  99  *    Addresse uses struct ATS_Address for each address. The structs are stored
 100  *    in a linked list and provides a pointer void *solver_information for the
 101  *    solver to store address specific information. It provides the int values
 102  *    active which is set to GNUNET_YES if the address is select for transport
 103  *    use and used, representing that transport service is actively using this
 104  *    address. Address information are stored in peer, addr, addr_len, plugin.
 105  *
 106  *     1.3 Initialization
 107  *
 108  *    During initialization a hashmap to store addresses is created. The quotas
 109  *    for all networks defined for ATS are loaded from configuration. For each
 110  *    network first the logic will check if the string
 111  *    GNUNET_ATS_MaxBandwidthString is configured, if not it will try to convert
 112  *    the configured value as a fancy size and if this fails it will try to use
 113  *    it as a value_number. If no configuration value is found it will assign
 114  *    GNUNET_ATS_DefaultBandwidth. The most important step is to load the
 115  *    configured solver using configuration "[ats]:MODE". Current solvers are
 116  *    MODE_PROPORTIONAL, MODE_MLP. Interaction is done using a solver API
 117  *
 118  *     1.4 Solver API
 119  *
 120  *    Solver functions:
 121  *      * s_init: init the solver with required information
 122  *      * s_add: add a new address
 123  *      * s_update: update ATS values or session for an address
 124  *      * s_get: get prefered address for a peer
 125  *      * s_del: delete an address
 126  *      * s_pref: change preference value for a peer
 127  *      * s_done: shutdown solver
 128  *
 129  *    Callbacks: addresses provides a bandwidth_changed_cb callback to the
 130  *    solver which is called when bandwidth assigned to peer has changed
 131  *
 132  *     1.5 Shutdown
 133  *
 134  *    During shutdown all addresses are freed and the solver told to shutdown
 135  *
 136  *     1.6 Addresses and sessions
 137  *
 138  *    Addresses consist of the address itself and a numerical session. When a
 139  *    new address without a session is added it has no session, so it gets
 140  *    session 0 assigned. When an address with a session is added and an address
 141  *    object with session 0 is found, this object is updated with the session
 142  *    otherwise a new address object with this session assigned is created.
 143  *
 144  *       1.6.1 Terminology
 145  *
 146  *    Addresses a1,a2 with session s1, s2 are "exact" if:
 147  *    (a1 == a2)&&(s1 == s2)
 148  *    Addresses a1,a2 with session s1, s2 are "equivalent" if:
 149  *    (a1 == a2)&&((s1 == s2)||(s1 == 0)||(s2 == 0)
 150  *
 151  *     1.7 Address management
 152  *
 153  *    Transport service notifies ATS about changes to the addresses known to
 154  *    it.
 155  *
 156  *       1.7.1 Adding an address
 157  *
 158  *    When transport learns a new address it tells ATS and ATS is telling
 159  *    addresses about it using GAS_address_add. If not known to addresses it
 160  *    creates a new address object and calls solver's s_add. ATS information are
 161  *    deserialized and solver is notified about the session and ATS information
 162  *    using s_update.
 163  *
 164  *       1.7.2 Updating an address
 165  *
 166  *    Addresses does an lookup up for the existing address with the given
 167  *    session. If disassembles included ATS information and notifies the solver
 168  *    using s_update about the update.
 169  *
 170  *       1.7.3 Deleting an address
 171  *
 172  *    Addresses does an lookup for the exact address and session and if removes
 173  *    this address. If session != 0 the session is set to 0 and the address is
 174  *    kept. If session == 0, the addresses is removed.
 175  *
 176  *       1.7.4 Requesting an address suggestion
 177  *
 178  *    The address client issues a request address message to be notified about
 179  *    address suggestions for a specific peer. Addresses asks the solver with
 180  *    s_get. If no address is available, it will not send a response, otherwise
 181  *    it will respond with the choosen address.
 182  *
 183  *       1.7.5 Address suggestions
 184  *
 185  *    Addresses will notify the client automatically on any bandwidth_changed_cb
 186  *    by the solver if a address suggestion request is pending. If no address is
 187  *    available it will not respond at all If the client is not interested
 188  *    anymore, it has to cancel the address suggestion request.
 189  *
 190  *       1.7.6 Suggestions blocks and reset
 191  *
 192  *    After suggesting an address it is blocked for ATS_BLOCKING_DELTA sec. to
 193  *    prevent the client from being thrashed. If the client requires immediately
 194  *    it can reset this block using GAS_addresses_handle_backoff_reset.
 195  *
 196  *       1.7.7 Address lifecycle
 197  *
 198  *      * (add address)
 199  *      * (updated address)
 200  *      * (delete address)
 201  *
 202  *     1.8 Bandwidth assignment
 203  *
 204  *    The addresses are used to perform resource allocation operations. ATS
 205  *    addresses takes care of instantiating the solver configured and notifies
 206  *    the respective solver about address changes and receives changes to the
 207  *    bandwidth assignment from the solver. The current bandwidth assignment is
 208  *    sent to transport. The specific solvers will be described in the specific
 209  *    section.
 210  *
 211  *     1.9 Changing peer preferences
 212  *
 213  *    The bandwidth assigned to a peer can be influenced by setting a preference
 214  *    for a peer. The prefernce will be given to to the solver with s_pref which
 215  *    has to take care of the preference value
 216  */
 217
 218
 219 /*
 220  * How long will address suggestions blocked after a suggestion
 221  */
 222 #define ATS_BLOCKING_DELTA GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_MILLISECONDS, 100)
 223
 224 /**
 225  * Information provided by ATS normalization
 226  */
 227 struct GAS_NormalizationInfo
 228 {
 229   /**
 230    * Next index to use in averaging queue
 231    */
 232   unsigned int avg_queue_index;
 233
 234   /**
 235    * Averaging queue
 236    */
 237   uint64_t atsi_abs[GAS_normalization_queue_length];
 238
 239   /**
 240    * Averaged ATSI values from queue
 241    */
 242   uint64_t avg;
 243
 244   /**
 245    * Normalized values from queue to a range of values [1.0...2.0]
 246    */
 247   double norm;
 248 };
 249
 250
 251 /**
 252  * Address with additional information
 253  */
 254 struct ATS_Address
 255 {
 256   /**
 257    * Peer ID this address is for.
 258    */
 259   struct GNUNET_PeerIdentity peer;
 260
 261   /**
 262    * Address (in plugin-specific binary format).
 263    */
 264   const void *addr;
 265
 266   /**
 267    * Plugin name
 268    */
 269   char *plugin;
 270
 271   /**
 272    * Solver-specific information for this address
 273    */
 274   void *solver_information;
 275
 276   /**
 277    * ATS performance information for this address
 278    */
 279   struct GNUNET_ATS_Properties properties;
 280
 281   /**
 282    * Time when address had last activity (update, in uses)
 283    */
 284   struct GNUNET_TIME_Absolute t_last_activity;
 285
 286   /**
 287    * Time when address was added
 288    */
 289   struct GNUNET_TIME_Absolute t_added;
 290
 291   /**
 292    * Address length, number of bytes in @e addr.
 293    */
 294   size_t addr_len;
 295
 296   /**
 297    * Session ID, can never be 0.
 298    */
 299   uint32_t session_id;
 300
 301   /**
 302    * Field to store local flags.
 303    */
 304   enum GNUNET_HELLO_AddressInfo local_address_info;
 305
 306   /**
 307    * ATS performance information for this address, size of the @e atsi array.
 308    */
 309   uint32_t atsi_count;
 310
 311   /**
 312    * Inbound bandwidth assigned by solver
 313    */
 314   uint32_t assigned_bw_in;
 315
 316   /**
 317    * Outbound bandwidth assigned by solver
 318    */
 319   uint32_t assigned_bw_out;
 320
 321   /**
 322    * Inbound bandwidth assigned by solver in NBO
 323    */
 324   uint32_t last_notified_bw_in;
 325
 326   /**
 327    * Outbound bandwidth assigned by solver in NBO
 328    */
 329   uint32_t last_notified_bw_out;
 330
 331   /**
 332    * Is this the active address for this peer?
 333    */
 334   int active;
 335
 336   /**
 337    * Normalized delay information for this address.
 338    */
 339   struct GAS_NormalizationInfo norm_delay;
 340
 341   /**
 342    * Normalized distance information for this address.
 343    */
 344   struct GAS_NormalizationInfo norm_distance;
 345
 346   /**
 347    * Normalized utilization inbound for this address.
 348    */
 349   struct GAS_NormalizationInfo norm_utilization_in;
 350
 351     /**
 352    * Normalized utilization outbound for this address.
 353    */
 354   struct GAS_NormalizationInfo norm_utilization_out;
 355
 356 };
 357
 358
 359 /**
 360  * A multipeermap mapping peer identities to `struct ATS_Address`.
 361  */
 362 extern struct GNUNET_CONTAINER_MultiPeerMap *GSA_addresses;
 363
 364
 365 /**
 366  * Initialize address subsystem. The addresses subsystem manages the addresses
 367  * known and current performance information.
 368  */
 369 void
 370 GAS_addresses_init (void);
 371
 372
 373 /**
 374  * Shutdown address subsystem.
 375  */
 376 void
 377 GAS_addresses_done (void);
 378
 379
 380 /**
 381  * Add a new address for a peer.
 382  *
 383  * @param peer peer
 384  * @param plugin_name transport plugin name
 385  * @param plugin_addr plugin address
 386  * @param plugin_addr_len length of the @a plugin_addr
 387  * @param local_address_info the local address for the address
 388  * @param session_id session id, can never be 0.
 389  * @param prop performance information for this address
 390  */
 391 void
 392 GAS_addresses_add (const struct GNUNET_PeerIdentity *peer,
 393                    const char *plugin_name,
 394                    const void *plugin_addr,
 395                    size_t plugin_addr_len,
 396                    uint32_t local_address_info,
 397                    uint32_t session_id,
 398                    const struct GNUNET_ATS_Properties *prop);
 399
 400
 401 /**
 402  * Update an address with new performance information for a peer.
 403  *
 404  * @param peer peer
 405  * @param session_id session id, can never be 0
 406  * @param prop performance information for this address
 407  */
 408 void
 409 GAS_addresses_update (const struct GNUNET_PeerIdentity *peer,
 410                       uint32_t session_id,
 411                       const struct GNUNET_ATS_Properties *prop);
 412
 413
 414 /**
 415  * Remove an address for a peer.
 416  *
 417  * @param peer peer
 418  * @param session_id session id, can never be 0
 419  */
 420 void
 421 GAS_addresses_destroy (const struct GNUNET_PeerIdentity *peer,
 422                        uint32_t session_id);
 423
 424
 425 /**
 426  * Remove all addresses.
 427  */
 428 void
 429 GAS_addresses_destroy_all (void);
 430
 431
 432 /**
 433  * Iterator for #GAS_addresses_get_peer_info()
 434  *
 435  * @param cls closure
 436  * @param id the peer id
 437  * @param plugin_name plugin name
 438  * @param plugin_addr address
 439  * @param plugin_addr_len length of @a plugin_addr
 440  * @param address_active is address actively used
 441  * @param atsi ats performance information
 442  * @param local_address_info flags for the address
 443  * @param bandwidth_out current outbound bandwidth assigned to address
 444  * @param bandwidth_in current inbound bandwidth assigned to address
 445  */
 446 typedef void
 447 (*GNUNET_ATS_PeerInfo_Iterator) (void *cls,
 448                                  const struct GNUNET_PeerIdentity *id,
 449                                  const char *plugin_name,
 450                                  const void *plugin_addr,
 451                                  size_t plugin_addr_len,
 452                                  const int address_active,
 453                                  const struct GNUNET_ATS_Properties *prop,
 454                                  enum GNUNET_HELLO_AddressInfo local_address_info,
 455                                  struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out,
 456                                  struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in);
 457
 458
 459 /**
 460  * Return information all peers currently known to ATS
 461  *
 462  * @param peer the respective peer
 463  * @param pi_it the iterator to call for every peer
 464  * @param pi_it_cls the closure for @a pi_it
 465  */
 466 void
 467 GAS_addresses_get_peer_info (const struct GNUNET_PeerIdentity *peer,
 468                              GNUNET_ATS_PeerInfo_Iterator pi_it,
 469                              void *pi_it_cls);
 470
 471
 472 /**
 473  * Handle 'address list request' messages from clients.
 474  *
 475  * @param client client that sent the request
 476  * @param alrm the request message
 477  */
 478 void
 479 GAS_handle_request_address_list (struct GNUNET_SERVICE_Client *client,
 480                                  const struct AddressListRequestMessage *alrm);
 481
 482
 483 #endif
 484
 485 /* end of gnunet-service-ats_addresses.h */