src/include/gnunet_ats_transport_service.h

   1 /*
   2  This file is part of GNUnet.
   3  Copyright (C) 2010-2015, 2018 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  * @file
  20  * Bandwidth allocation API for the transport service
  21  *
  22  * @author Christian Grothoff
  23  * @author Matthias Wachs
  24  *
  25  * @defgroup ats  ATS service
  26  * Bandwidth allocation for transport service
  27  *
  28  * @see [Documentation](https://gnunet.org/ats-subsystem)
  29  *
  30  * @{
  31  */
  32 #ifndef GNUNET_ATS_TRANSPORT_SERVICE_H
  33 #define GNUNET_ATS_TRANSPORT_SERVICE_H
  34
  35 #include "gnunet_constants.h"
  36 #include "gnunet_util_lib.h"
  37 #include "gnunet_nt_lib.h"
  38 #include "gnunet_transport_communication_service.h"
  39
  40
  41 /**
  42  * ATS performance characteristics for an address.
  43  */
  44 struct GNUNET_ATS_Properties
  45 {
  46
  47   /**
  48    * Delay.  Time between when the time packet is sent and the packet
  49    * arrives.  FOREVER if we did not (successfully) measure yet.
  50    */
  51   struct GNUNET_TIME_Relative delay;
  52
  53   /**
  54    * Confirmed successful payload on this connection from this peer to
  55    * the other peer.
  56    *
  57    * Unit: [bytes/second]
  58    */
  59   uint32_t goodput_out;
  60
  61   /**
  62    * Confirmed useful payload on this connection to this peer from
  63    * the other peer.
  64    *
  65    * Unit: [bytes/second]
  66    */
  67   uint32_t goodput_in;
  68
  69   /**
  70    * Actual traffic on this connection from this peer to the other peer.
  71    * Includes transport overhead.
  72    *
  73    * Unit: [bytes/second]
  74    */
  75   uint32_t utilization_out;
  76
  77   /**
  78    * Actual traffic on this connection from the other peer to this peer.
  79    * Includes transport overhead.
  80    *
  81    * Unit: [bytes/second]
  82    */
  83   uint32_t utilization_in;
  84
  85   /**
  86    * Distance on network layer (required for distance-vector routing)
  87    * in hops.  Zero for direct connections (i.e. plain TCP/UDP).
  88    */
  89   uint32_t distance;
  90
  91   /**
  92    * MTU of the network layer, UINT32_MAX for no MTU (stream).
  93    *
  94    * Unit: [bytes]
  95    */
  96   uint32_t mtu;
  97
  98   /**
  99    * Which network scope does the respective address belong to?
 100    */
 101   enum GNUNET_NetworkType nt;
 102
 103   /**
 104    * What characteristics does this communicator have?
 105    */
 106   enum GNUNET_TRANSPORT_CommunicatorCharacteristics cc;
 107
 108 };
 109
 110
 111 /* ******************************** Scheduling API ***************************** */
 112
 113 /**
 114  * Handle to the ATS subsystem for bandwidth/transport scheduling information.
 115  */
 116 struct GNUNET_ATS_SchedulingHandle;
 117
 118 /**
 119  * Opaque session handle, to be defined by transport.  Contents not known to ATS.
 120  */
 121 struct GNUNET_ATS_Session;
 122
 123
 124 /**
 125  * Signature of a function called by ATS with the current bandwidth
 126  * allocation to be used as determined by ATS.
 127  *
 128  * @param cls closure
 129  * @param session session this is about
 130  * @param bandwidth_out assigned outbound bandwidth for the connection,
 131  *        0 to signal disconnect
 132  * @param bandwidth_in assigned inbound bandwidth for the connection,
 133  *        0 to signal disconnect
 134  */
 135 typedef void
 136 (*GNUNET_ATS_AllocationCallback) (void *cls,
 137                                   struct GNUNET_ATS_Session *session,
 138                                   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out,
 139                                   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in);
 140
 141
 142 /**
 143  * Signature of a function called by ATS suggesting transport to
 144  * try connecting with a particular address.
 145  *
 146  * @param cls closure
 147  * @param pid target peer
 148  * @param address the address to try
 149  */
 150 typedef void
 151 (*GNUNET_ATS_SuggestionCallback) (void *cls,
 152                                   const struct GNUNET_PeerIdentity *pid,
 153                                   const char *address);
 154
 155
 156 /**
 157  * Initialize the ATS scheduling subsystem.
 158  *
 159  * @param cfg configuration to use
 160  * @param alloc_cb notification to call whenever the allocation changed
 161  * @param alloc_cb_cls closure for @a alloc_cb
 162  * @param suggest_cb notification to call whenever the suggestation is made
 163  * @param suggest_cb_cls closure for @a suggest_cb
 164  * @return ats context
 165  */
 166 struct GNUNET_ATS_SchedulingHandle *
 167 GNUNET_ATS_scheduling_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
 168                             GNUNET_ATS_AllocationCallback alloc_cb,
 169                             void *alloc_cb_cls);
 170                             GNUNET_ATS_SuggestionCallback suggest_cb,
 171                             void *suggest_cb_cls);
 172
 173
 174 /**
 175  * Client is done with ATS scheduling, release resources.
 176  *
 177  * @param sh handle to release
 178  */
 179 void
 180 GNUNET_ATS_scheduling_done (struct GNUNET_ATS_SchedulingHandle *sh);
 181
 182
 183 /**
 184  * Handle used within ATS to track an address.
 185  */
 186 struct GNUNET_ATS_AddressRecord;
 187
 188
 189 /**
 190  * We have a new address ATS should know. Addresses have to be added with this
 191  * function before they can be: updated, set in use and destroyed
 192  *
 193  * @param sh handle
 194  * @param pid peer we connected to
 195  * @param address the address (human readable version), NULL if
 196  *        the session is inbound-only
 197  * @param session transport-internal handle for the address/queue
 198  * @param prop performance data for the address
 199  * @return handle to the address representation inside ATS, NULL
 200  *         on error (i.e. ATS knows this exact address already, or
 201  *         address is invalid)
 202  */
 203 struct GNUNET_ATS_AddressRecord *
 204 GNUNET_ATS_address_add (struct GNUNET_ATS_SchedulingHandle *sh,
 205                         const struct GNUNET_PeerIdentity *pid,
 206                         const char *address,
 207                         struct GNUNET_ATS_Session *session,
 208                         const struct GNUNET_ATS_Properties *prop);
 209
 210
 211 /**
 212  * We have updated performance statistics for a given address.  Based
 213  * on the information provided, ATS may update bandwidth assignments.
 214  *
 215  * @param ar address record to update information for
 216  * @param prop performance data for the address
 217  */
 218 void
 219 GNUNET_ATS_address_update (struct GNUNET_ATS_AddressRecord *ar,
 220                            const struct GNUNET_ATS_Properties *prop);
 221
 222
 223 /**
 224  * A session was destroyed, ATS should now schedule and
 225  * allocate under the assumption that this @a ar is no
 226  * longer in use.
 227  *
 228  * @param ar address record to drop
 229  */
 230 void
 231 GNUNET_ATS_address_del (struct GNUNET_ATS_AddressRecord *ar);
 232
 233
 234 #endif
 235
 236 /** @} */  /* end of group */
 237
 238 /* end of file gnunet-service-transport_ats.h */