src/include/gnunet_ats_service.h

   1 /*
   2  This file is part of GNUnet.
   3  Copyright (C) 2010-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  * @file
  17  * Automatic transport selection and outbound bandwidth determination
  18  *
  19  * @author Christian Grothoff
  20  * @author Matthias Wachs
  21  *
  22  * @defgroup ats  ATS service
  23  * Automatic Transport Selection and outbound bandwidth determination
  24  *
  25  * @see [Documentation](https://gnunet.org/ats-subsystem)
  26  *
  27  * @{
  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_hello_lib.h"
  35
  36 /**
  37  * Types of networks (with separate quotas) we support.
  38  */
  39 enum GNUNET_ATS_Network_Type
  40 {
  41   /**
  42    * Category of last resort.
  43    */
  44   GNUNET_ATS_NET_UNSPECIFIED = 0,
  45
  46   /**
  47    * Loopback (same host).
  48    */
  49   GNUNET_ATS_NET_LOOPBACK = 1,
  50
  51   /**
  52    * Local area network.
  53    */
  54   GNUNET_ATS_NET_LAN = 2,
  55
  56   /**
  57    * Wide area network (i.e. Internet)
  58    */
  59   GNUNET_ATS_NET_WAN = 3,
  60
  61   /**
  62    * Wireless LAN (i.e. 802.11abgn)
  63    */
  64   GNUNET_ATS_NET_WLAN = 4,
  65
  66   /**
  67    * Bluetooth LAN
  68    */
  69   GNUNET_ATS_NET_BT = 5,
  70
  71 /**
  72  * Number of network types supported by ATS
  73  */
  74 #define GNUNET_ATS_NetworkTypeCount 6
  75
  76 };
  77
  78
  79 /**
  80  * Default bandwidth assigned to a network : 64 KB/s
  81  */
  82 #define GNUNET_ATS_DefaultBandwidth 65536
  83
  84 /**
  85  * Undefined value for an `enum GNUNET_ATS_Property`
  86  */
  87 #define GNUNET_ATS_VALUE_UNDEFINED UINT32_MAX
  88
  89 /**
  90  * String representation for GNUNET_ATS_VALUE_UNDEFINED
  91  */
  92 #define GNUNET_ATS_VALUE_UNDEFINED_STR "undefined"
  93
  94 /**
  95  * Maximum bandwidth assigned to a network : 4095 MB/s
  96  */
  97 #define GNUNET_ATS_MaxBandwidth UINT32_MAX
  98
  99 /**
 100  * Textual equivalent for GNUNET_ATS_MaxBandwidth
 101  */
 102 #define GNUNET_ATS_MaxBandwidthString "unlimited"
 103
 104
 105 /**
 106  * ATS performance characteristics for an address.
 107  */
 108 struct GNUNET_ATS_Properties
 109 {
 110
 111   /**
 112    * Delay.  Time between when the time packet is sent and the packet
 113    * arrives.  FOREVER if we did not measure yet.
 114    */
 115   struct GNUNET_TIME_Relative delay;
 116
 117   /**
 118    * Actual traffic on this connection from this peer to the other peer.
 119    * Includes transport overhead.
 120    *
 121    * Unit: [bytes/second]
 122    */
 123   uint32_t utilization_out;
 124
 125   /**
 126    * Actual traffic on this connection from the other peer to this peer.
 127    * Includes transport overhead.
 128    *
 129    * Unit: [bytes/second]
 130    */
 131   uint32_t utilization_in;
 132
 133   /**
 134    * Distance on network layer (required for distance-vector routing)
 135    * in hops.  Zero for direct connections (i.e. plain TCP/UDP).
 136    */
 137   unsigned int distance;
 138
 139   /**
 140    * Which network scope does the respective address belong to?
 141    * This property does not change.
 142    */
 143   enum GNUNET_ATS_Network_Type scope;
 144
 145 };
 146
 147
 148 /**
 149  * ATS performance characteristics for an address in
 150  * network byte order (for IPC).
 151  */
 152 struct GNUNET_ATS_PropertiesNBO
 153 {
 154
 155   /**
 156    * Actual traffic on this connection from this peer to the other peer.
 157    * Includes transport overhead.
 158    *
 159    * Unit: [bytes/second]
 160    */
 161   uint32_t utilization_out GNUNET_PACKED;
 162
 163   /**
 164    * Actual traffic on this connection from the other peer to this peer.
 165    * Includes transport overhead.
 166    *
 167    * Unit: [bytes/second]
 168    */
 169   uint32_t utilization_in GNUNET_PACKED;
 170
 171   /**
 172    * Which network scope does the respective address belong to?
 173    * This property does not change.
 174    */
 175   uint32_t scope GNUNET_PACKED;
 176
 177   /**
 178    * Distance on network layer (required for distance-vector routing)
 179    * in hops.  Zero for direct connections (i.e. plain TCP/UDP).
 180    */
 181   uint32_t distance GNUNET_PACKED;
 182
 183   /**
 184    * Delay.  Time between when the time packet is sent and the packet
 185    * arrives.  FOREVER if we did not measure yet.
 186    */
 187   struct GNUNET_TIME_RelativeNBO delay;
 188
 189 };
 190
 191
 192
 193 /* ********************* LAN Characterization library ************************ */
 194 /* Note: these functions do not really communicate with the ATS service */
 195
 196
 197 /**
 198  * Convert ATS properties from host to network byte order.
 199  *
 200  * @param nbo[OUT] value written
 201  * @param hbo value read
 202  */
 203 void
 204 GNUNET_ATS_properties_hton (struct GNUNET_ATS_PropertiesNBO *nbo,
 205                             const struct GNUNET_ATS_Properties *hbo);
 206
 207
 208 /**
 209  * Convert ATS properties from network to host byte order.
 210  *
 211  * @param hbo[OUT] value written
 212  * @param nbo value read
 213  */
 214 void
 215 GNUNET_ATS_properties_ntoh (struct GNUNET_ATS_Properties *hbo,
 216                             const struct GNUNET_ATS_PropertiesNBO *nbo);
 217
 218
 219
 220 /**
 221  * Convert a `enum GNUNET_ATS_Network_Type` to a string
 222  *
 223  * @param net the network type
 224  * @return a string or NULL if invalid
 225  */
 226 const char *
 227 GNUNET_ATS_print_network_type (enum GNUNET_ATS_Network_Type net);
 228
 229
 230 /**
 231  * Handle for the LAN Characterization library.
 232  */
 233 struct GNUNET_ATS_InterfaceScanner;
 234
 235
 236 /**
 237  * Returns where the address is located: loopback, LAN or WAN.
 238  *
 239  * @param is handle from #GNUNET_ATS_interface_scanner_init()
 240  * @param addr address
 241  * @param addrlen address length
 242  * @return type of the network the address belongs to
 243  */
 244 enum GNUNET_ATS_Network_Type
 245 GNUNET_ATS_scanner_address_get_type (struct GNUNET_ATS_InterfaceScanner *is,
 246                                      const struct sockaddr *addr,
 247                                      socklen_t addrlen);
 248
 249
 250 /**
 251  * Initialize the ATS address characterization client handle.
 252  *
 253  * @return scanner handle, NULL on error
 254  */
 255 struct GNUNET_ATS_InterfaceScanner *
 256 GNUNET_ATS_scanner_init (void);
 257
 258
 259 /**
 260  * Terminate interface scanner.
 261  *
 262  * @param is scanner we are done with
 263  */
 264 void
 265 GNUNET_ATS_scanner_done (struct GNUNET_ATS_InterfaceScanner *is);
 266
 267
 268
 269 /* ********************Connection Suggestion API ***************************** */
 270
 271 /**
 272  * Handle to the ATS subsystem for making suggestions about
 273  * connections the peer would like to have.
 274  */
 275 struct GNUNET_ATS_ConnectivityHandle;
 276
 277 /**
 278  * Handle for address suggestion requests.
 279  */
 280 struct GNUNET_ATS_ConnectivitySuggestHandle;
 281
 282
 283 /**
 284  * Initialize the ATS connectivity suggestion client handle.
 285  *
 286  * @param cfg configuration to use
 287  * @return ats connectivity handle, NULL on error
 288  */
 289 struct GNUNET_ATS_ConnectivityHandle *
 290 GNUNET_ATS_connectivity_init (const struct GNUNET_CONFIGURATION_Handle *cfg);
 291
 292
 293 /**
 294  * Shutdown ATS connectivity suggestion client.
 295  *
 296  * @param ch handle to destroy
 297  */
 298 void
 299 GNUNET_ATS_connectivity_done (struct GNUNET_ATS_ConnectivityHandle *ch);
 300
 301
 302 /**
 303  * We would like to establish a new connection with a peer.  ATS
 304  * should suggest a good address to begin with.
 305  *
 306  * @param ch handle
 307  * @param peer identity of the peer we need an address for
 308  * @param strength how urgent is the need for such a suggestion
 309  * @return suggestion handle, NULL if request is already pending
 310  */
 311 struct GNUNET_ATS_ConnectivitySuggestHandle *
 312 GNUNET_ATS_connectivity_suggest (struct GNUNET_ATS_ConnectivityHandle *ch,
 313                                  const struct GNUNET_PeerIdentity *peer,
 314                                  uint32_t strength);
 315
 316
 317 /**
 318  * We no longer care about being connected to a peer.
 319  *
 320  * @param sh handle
 321  */
 322 void
 323 GNUNET_ATS_connectivity_suggest_cancel (struct GNUNET_ATS_ConnectivitySuggestHandle *sh);
 324
 325
 326 /* ******************************** Scheduling API ***************************** */
 327
 328 /**
 329  * Handle to the ATS subsystem for bandwidth/transport scheduling information.
 330  */
 331 struct GNUNET_ATS_SchedulingHandle;
 332
 333 /**
 334  * Opaque session handle, defined by plugins.  Contents not known to ATS.
 335  */
 336 struct GNUNET_ATS_Session;
 337
 338
 339 /**
 340  * Signature of a function called by ATS with the current bandwidth
 341  * and address preferences as determined by ATS.  If our connection
 342  * to ATS dies and thus all suggestions become invalid, this function
 343  * is called ONCE with all arguments (except @a cls) being NULL/0.
 344  *
 345  * @param cls closure
 346  * @param peer for which we suggest an address, NULL if ATS connection died
 347  * @param address suggested address (including peer identity of the peer),
 348  *             may be NULL to signal disconnect from peer
 349  * @param session session to use, NULL to establish a new outgoing session
 350  * @param bandwidth_out assigned outbound bandwidth for the connection,
 351  *        0 to signal disconnect
 352  * @param bandwidth_in assigned inbound bandwidth for the connection,
 353  *        0 to signal disconnect
 354  */
 355 typedef void
 356 (*GNUNET_ATS_AddressSuggestionCallback) (void *cls,
 357                                          const struct GNUNET_PeerIdentity *peer,
 358                                          const struct GNUNET_HELLO_Address *address,
 359                                          struct GNUNET_ATS_Session *session,
 360                                          struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out,
 361                                          struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in);
 362
 363
 364 /**
 365  * Initialize the ATS scheduling subsystem.
 366  *
 367  * @param cfg configuration to use
 368  * @param suggest_cb notification to call whenever the suggestation changed
 369  * @param suggest_cb_cls closure for @a suggest_cb
 370  * @return ats context
 371  */
 372 struct GNUNET_ATS_SchedulingHandle *
 373 GNUNET_ATS_scheduling_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
 374                             GNUNET_ATS_AddressSuggestionCallback suggest_cb,
 375                             void *suggest_cb_cls);
 376
 377
 378 /**
 379  * Client is done with ATS scheduling, release resources.
 380  *
 381  * @param sh handle to release
 382  */
 383 void
 384 GNUNET_ATS_scheduling_done (struct GNUNET_ATS_SchedulingHandle *sh);
 385
 386
 387 /**
 388  * Handle used within ATS to track an address.
 389  */
 390 struct GNUNET_ATS_AddressRecord;
 391
 392
 393 /**
 394  * We have a new address ATS should know. Addresses have to be added with this
 395  * function before they can be: updated, set in use and destroyed
 396  *
 397  * @param sh handle
 398  * @param address the address
 399  * @param session session handle (if available, i.e. for incoming connections)
 400  * @param prop performance data for the address
 401  * @return handle to the address representation inside ATS, NULL
 402  *         on error (i.e. ATS knows this exact address already, or
 403  *         address is invalid)
 404  */
 405 struct GNUNET_ATS_AddressRecord *
 406 GNUNET_ATS_address_add (struct GNUNET_ATS_SchedulingHandle *sh,
 407                         const struct GNUNET_HELLO_Address *address,
 408                         struct GNUNET_ATS_Session *session,
 409                         const struct GNUNET_ATS_Properties *prop);
 410
 411
 412 /**
 413  * An address was used to initiate a session.
 414  *
 415  * @param ar address record to update information for
 416  * @param session session handle
 417  */
 418 void
 419 GNUNET_ATS_address_add_session (struct GNUNET_ATS_AddressRecord *ar,
 420                                 struct GNUNET_ATS_Session *session);
 421
 422
 423 /**
 424  * A @a session was destroyed, disassociate it from the given address
 425  * record.  If this was an incoming addess, destroys the address as
 426  * well.
 427  *
 428  * @param ar address record to update information for
 429  * @param session session handle
 430  * @return #GNUNET_YES if the @a ar was destroyed because
 431  *                     it was an incoming address,
 432  *         #GNUNET_NO if the @ar was kept because we can
 433  *                    use it still to establish a new session
 434  */
 435 int
 436 GNUNET_ATS_address_del_session (struct GNUNET_ATS_AddressRecord *ar,
 437                                 struct GNUNET_ATS_Session *session);
 438
 439
 440 /**
 441  * We have updated performance statistics for a given address.  Note
 442  * that this function can be called for addresses that are currently
 443  * in use as well as addresses that are valid but not actively in use.
 444  * Furthermore, the peer may not even be connected to us right now (@a
 445  * session value of NULL used to signal disconnect, or somehow we
 446  * otherwise got updated on @a ats information).  Based on the
 447  * information provided, ATS may update bandwidth assignments and
 448  * suggest to switch addresses.
 449  *
 450  * @param ar address record to update information for
 451  * @param prop performance data for the address
 452  */
 453 void
 454 GNUNET_ATS_address_update (struct GNUNET_ATS_AddressRecord *ar,
 455                            const struct GNUNET_ATS_Properties *prop);
 456
 457
 458 /**
 459  * An address got destroyed, stop using it as a valid address.
 460  *
 461  * @param ar address record to destroy, it's validation has
 462  *           expired and ATS may no longer use it
 463  */
 464 void
 465 GNUNET_ATS_address_destroy (struct GNUNET_ATS_AddressRecord *ar);
 466
 467
 468
 469 /* ******************************** Performance API ***************************** */
 470
 471 /**
 472  * ATS Handle to obtain and/or modify performance information.
 473  */
 474 struct GNUNET_ATS_PerformanceHandle;
 475
 476 /**
 477  * Signature of a function that is called with QoS information about an address.
 478  *
 479  * @param cls closure
 480  * @param address the address, NULL if ATS service was disconnected or
 481  *        when the iteration is completed in the case of
 482  *        #GNUNET_ATS_performance_list_addresses()
 483  * @param address_active #GNUNET_YES if this address is actively used
 484  *        to maintain a connection to a peer;
 485  *        #GNUNET_NO if the address is not actively used;
 486  *        #GNUNET_SYSERR if this address is no longer available for ATS
 487  * @param bandwidth_out assigned outbound bandwidth for the connection
 488  * @param bandwidth_in assigned inbound bandwidth for the connection
 489  * @param prop performance data for the address
 490  */
 491 typedef void
 492 (*GNUNET_ATS_AddressInformationCallback) (void *cls,
 493                                           const struct GNUNET_HELLO_Address *address,
 494                                           int address_active,
 495                                           struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out,
 496                                           struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in,
 497                                           const struct GNUNET_ATS_Properties *prop);
 498
 499
 500 /**
 501  * Handle for an address listing operation
 502  */
 503 struct GNUNET_ATS_AddressListHandle;
 504
 505
 506 /**
 507  * Get handle to access performance API of the ATS subsystem.
 508  *
 509  * @param cfg configuration to use
 510  * @param addr_info_cb callback called when performance characteristics for
 511  *      an address change
 512  * @param addr_info_cb_cls closure for @a addr_info_cb
 513  * @return ats performance context
 514  */
 515 struct GNUNET_ATS_PerformanceHandle *
 516 GNUNET_ATS_performance_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
 517                              GNUNET_ATS_AddressInformationCallback addr_info_cb,
 518                              void *addr_info_cb_cls);
 519
 520
 521 /**
 522  * Get information about addresses known to the ATS subsystem.
 523  *
 524  * @param ph the performance handle to use
 525  * @param peer peer idm can be NULL for all peers
 526  * @param all #GNUNET_YES to get information about all addresses or #GNUNET_NO to
 527  *        get only address currently used
 528  * @param infocb callback to call with the addresses,
 529  *        will callback with address == NULL when done
 530  * @param infocb_cls closure for @a infocb
 531  * @return handle to abort the operation
 532  */
 533 struct GNUNET_ATS_AddressListHandle *
 534 GNUNET_ATS_performance_list_addresses (struct GNUNET_ATS_PerformanceHandle *ph,
 535                                        const struct GNUNET_PeerIdentity *peer,
 536                                        int all,
 537                                        GNUNET_ATS_AddressInformationCallback infocb,
 538                                        void *infocb_cls);
 539
 540
 541 /**
 542  * Cancel a pending address listing operation
 543  *
 544  * @param alh the `struct GNUNET_ATS_AddressListHandle` handle to cancel
 545  */
 546 void
 547 GNUNET_ATS_performance_list_addresses_cancel (struct GNUNET_ATS_AddressListHandle *alh);
 548
 549
 550 /**
 551  * Client is done using the ATS performance subsystem, release resources.
 552  *
 553  * @param ph handle
 554  */
 555 void
 556 GNUNET_ATS_performance_done (struct GNUNET_ATS_PerformanceHandle *ph);
 557
 558
 559 /**
 560  * Function called with reservation result.
 561  *
 562  * @param cls closure
 563  * @param peer identifies the peer
 564  * @param amount set to the amount that was actually reserved or unreserved;
 565  *               either the full requested amount or zero (no partial reservations)
 566  * @param res_delay if the reservation could not be satisfied (amount was 0), how
 567  *        long should the client wait until re-trying?
 568  */
 569 typedef void
 570 (*GNUNET_ATS_ReservationCallback) (void *cls,
 571                                    const struct GNUNET_PeerIdentity *peer,
 572                                    int32_t amount,
 573                                    struct GNUNET_TIME_Relative res_delay);
 574
 575
 576 /**
 577  * Context that can be used to cancel a peer information request.
 578  */
 579 struct GNUNET_ATS_ReservationContext;
 580
 581
 582 /**
 583  * Reserve inbound bandwidth from the given peer.  ATS will look at
 584  * the current amount of traffic we receive from the peer and ensure
 585  * that the peer could add 'amount' of data to its stream.
 586  *
 587  * @param ph performance handle
 588  * @param peer identifies the peer
 589  * @param amount reserve N bytes for receiving, negative
 590  *                amounts can be used to undo a (recent) reservation;
 591  * @param rcb function to call with the resulting reservation information
 592  * @param rcb_cls closure for @a rcb
 593  * @return NULL on error
 594  * @deprecated will be replaced soon
 595  */
 596 struct GNUNET_ATS_ReservationContext *
 597 GNUNET_ATS_reserve_bandwidth (struct GNUNET_ATS_PerformanceHandle *ph,
 598                               const struct GNUNET_PeerIdentity *peer,
 599                               int32_t amount,
 600                               GNUNET_ATS_ReservationCallback rcb,
 601                               void *rcb_cls);
 602
 603
 604 /**
 605  * Cancel request for reserving bandwidth.
 606  *
 607  * @param rc context returned by the original GNUNET_ATS_reserve_bandwidth call
 608  */
 609 void
 610 GNUNET_ATS_reserve_bandwidth_cancel (struct GNUNET_ATS_ReservationContext *rc);
 611
 612
 613 /**
 614  * ATS preference types as array initializer
 615  */
 616 #define GNUNET_ATS_PreferenceType {GNUNET_ATS_PREFERENCE_BANDWIDTH, GNUNET_ATS_PREFERENCE_LATENCY, GNUNET_ATS_PREFERENCE_END}
 617
 618 /**
 619  * ATS preference types as string array initializer
 620  */
 621 #define GNUNET_ATS_PreferenceTypeString {"BANDWIDTH", "LATENCY", "END" }
 622
 623 /**
 624  * Enum defining all known preference categories.
 625  */
 626 enum GNUNET_ATS_PreferenceKind
 627 {
 628
 629   /**
 630    * Change the peer's bandwidth value (value per byte of bandwidth in
 631    * the goal function) to the given amount.  The argument is followed
 632    * by a double value giving the desired value (can be negative).
 633    * Preference changes are forgotten if peers disconnect.
 634    */
 635   GNUNET_ATS_PREFERENCE_BANDWIDTH = 0,
 636
 637   /**
 638    * Change the peer's latency value to the given amount.  The
 639    * argument is followed by a double value giving the desired value
 640    * (can be negative).  The absolute score in the goal function is
 641    * the inverse of the latency in microseconds (minimum: 1
 642    * microsecond) multiplied by the latency preferences.
 643    */
 644   GNUNET_ATS_PREFERENCE_LATENCY = 1,
 645
 646   /**
 647    * End of preference list.
 648    */
 649   GNUNET_ATS_PREFERENCE_END = 2
 650
 651 };
 652
 653
 654 /**
 655  * Convert a GNUNET_ATS_PreferenceType to a string
 656  *
 657  * @param type the preference type
 658  * @return a string or NULL if invalid
 659  */
 660 const char *
 661 GNUNET_ATS_print_preference_type (enum GNUNET_ATS_PreferenceKind type);
 662
 663
 664 /**
 665  * Change preferences for the given peer. Preference changes are forgotten if peers
 666  * disconnect.
 667  *
 668  * @param ph performance handle @param peer identifies the peer
 669  * @param ... #GNUNET_ATS_PREFERENCE_END-terminated specification of the
 670  * desired changes
 671  */
 672 void
 673 GNUNET_ATS_performance_change_preference (struct GNUNET_ATS_PerformanceHandle *ph,
 674                                           const struct GNUNET_PeerIdentity *peer,
 675                                           ...);
 676
 677
 678 /**
 679  * Application feedback on how good preference requirements are fulfilled
 680  * for the preferences included in the given time scope [now - scope .. now]
 681  *
 682  * An application notifies ATS if (and only if) it has feedback information
 683  * for specific properties. This values are valid until the feedback scores are
 684  * updated by the application.
 685  *
 686  * If the application has no feedback for this preference kind the application
 687  * will not explicitly call for this property and will not include it in this
 688  * function call.
 689  *
 690  * @param ph performance handle
 691  * @param scope the time interval this valid for: [now - scope .. now]
 692  * @param peer identifies the peer
 693  * @param ... #GNUNET_ATS_PREFERENCE_END-terminated specification of the desired changes
 694  */
 695 void
 696 GNUNET_ATS_performance_give_feedback (struct GNUNET_ATS_PerformanceHandle *ph,
 697                                       const struct GNUNET_PeerIdentity *peer,
 698                                       const struct GNUNET_TIME_Relative scope,
 699                                       ...);
 700
 701 #endif
 702
 703 /** @} */  /* end of group */
 704
 705 /* end of file gnunet-service-transport_ats.h */