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      SPDX-License-Identifier: AGPL3.0-or-later
  19  */
  20 /**
  21  * @file
  22  * Bandwidth allocation API for the transport service
  23  *
  24  * @author Christian Grothoff
  25  * @author Matthias Wachs
  26  *
  27  * @defgroup ats  ATS service
  28  * Bandwidth allocation for transport service
  29  *
  30  * @see [Documentation](https://gnunet.org/ats-subsystem)
  31  *
  32  * @{
  33  */
  34 #ifndef GNUNET_ATS_TRANSPORT_SERVICE_H
  35 #define GNUNET_ATS_TRANSPORT_SERVICE_H
  36
  37 #include "gnunet_constants.h"
  38 #include "gnunet_util_lib.h"
  39 #include "gnunet_nt_lib.h"
  40 #include "gnunet_transport_communication_service.h"
  41
  42
  43 /**
  44  * ATS performance characteristics for a session.
  45  */
  46 struct GNUNET_ATS_Properties {
  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 /* ******************************** Transport API ***************************** */
 111
 112 /**
 113  * Handle to the ATS subsystem for bandwidth/transport transport information.
 114  */
 115 struct GNUNET_ATS_TransportHandle;
 116
 117 /**
 118  * Opaque session handle, to be defined by transport.  Contents not known to ATS.
 119  */
 120 struct GNUNET_ATS_Session;
 121
 122
 123 /**
 124  * Signature of a function called by ATS with the current bandwidth
 125  * allocation to be used as determined by ATS.
 126  *
 127  * @param cls closure
 128  * @param session session this is about
 129  * @param bandwidth_out assigned outbound bandwidth for the connection,
 130  *        0 to signal disconnect
 131  * @param bandwidth_in assigned inbound bandwidth for the connection,
 132  *        0 to signal disconnect
 133  */
 134 typedef void
 135 (*GNUNET_ATS_AllocationCallback) (void *cls,
 136                                   struct GNUNET_ATS_Session *session,
 137                                   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out,
 138                                   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in);
 139
 140
 141 /**
 142  * Signature of a function called by ATS suggesting transport to
 143  * try connecting with a particular address.
 144  *
 145  * @param cls closure
 146  * @param pid target peer
 147  * @param address the address to try
 148  */
 149 typedef void
 150 (*GNUNET_ATS_SuggestionCallback) (void *cls,
 151                                   const struct GNUNET_PeerIdentity *pid,
 152                                   const char *address);
 153
 154
 155 /**
 156  * Initialize the ATS transport subsystem.
 157  *
 158  * @param cfg configuration to use
 159  * @param alloc_cb notification to call whenever the allocation changed
 160  * @param alloc_cb_cls closure for @a alloc_cb
 161  * @param suggest_cb notification to call whenever the suggestation is made
 162  * @param suggest_cb_cls closure for @a suggest_cb
 163  * @return ats context
 164  */
 165 struct GNUNET_ATS_TransportHandle *
 166 GNUNET_ATS_transport_init(const struct GNUNET_CONFIGURATION_Handle *cfg,
 167                           GNUNET_ATS_AllocationCallback alloc_cb,
 168                           void *alloc_cb_cls,
 169                           GNUNET_ATS_SuggestionCallback suggest_cb,
 170                           void *suggest_cb_cls);
 171
 172
 173 /**
 174  * Client is done with ATS transport, release resources.
 175  *
 176  * @param ath handle to release
 177  */
 178 void
 179 GNUNET_ATS_transport_done(struct GNUNET_ATS_TransportHandle *ath);
 180
 181
 182 /**
 183  * Handle used within ATS to track an session.
 184  */
 185 struct GNUNET_ATS_SessionRecord;
 186
 187
 188 /**
 189  * We have a new session ATS should know. Sessiones have to be added with this
 190  * function before they can be: updated, set in use and destroyed
 191  *
 192  * @param ath handle
 193  * @param pid peer we connected to
 194  * @param address the address (human readable version),
 195  * @param session transport-internal handle for the session/queue, NULL if
 196  *        the session is inbound-only
 197  * @param prop performance data for the session
 198  * @return handle to the session representation inside ATS, NULL
 199  *         on error (i.e. ATS knows this exact session already, or
 200  *         session is invalid)
 201  */
 202 struct GNUNET_ATS_SessionRecord *
 203 GNUNET_ATS_session_add(struct GNUNET_ATS_TransportHandle *ath,
 204                        const struct GNUNET_PeerIdentity *pid,
 205                        const char *address,
 206                        struct GNUNET_ATS_Session *session,
 207                        const struct GNUNET_ATS_Properties *prop);
 208
 209
 210 /**
 211  * We have updated performance statistics for a given session.  Based
 212  * on the information provided, ATS may update bandwidth assignments.
 213  *
 214  * @param ar session record to update information for
 215  * @param prop performance data for the session
 216  */
 217 void
 218 GNUNET_ATS_session_update(struct GNUNET_ATS_SessionRecord *ar,
 219                           const struct GNUNET_ATS_Properties *prop);
 220
 221
 222 /**
 223  * A session was destroyed, ATS should now schedule and
 224  * allocate under the assumption that this @a ar is no
 225  * longer in use.
 226  *
 227  * @param ar session record to drop
 228  */
 229 void
 230 GNUNET_ATS_session_del(struct GNUNET_ATS_SessionRecord *ar);
 231
 232
 233 #endif
 234
 235 /** @} */  /* end of group */
 236
 237 /* end of file gnunet-service-transport_ats.h */