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   /**
  49    * Delay.  Time between when the time packet is sent and the packet
  50    * arrives.  FOREVER if we did not (successfully) measure yet.
  51    */
  52   struct GNUNET_TIME_Relative delay;
  53
  54   /**
  55    * Confirmed successful payload on this connection from this peer to
  56    * the other peer.
  57    *
  58    * Unit: [bytes/second]
  59    */
  60   uint32_t goodput_out;
  61
  62   /**
  63    * Confirmed useful payload on this connection to this peer from
  64    * the other peer.
  65    *
  66    * Unit: [bytes/second]
  67    */
  68   uint32_t goodput_in;
  69
  70   /**
  71    * Actual traffic on this connection from this peer to the other peer.
  72    * Includes transport overhead.
  73    *
  74    * Unit: [bytes/second]
  75    */
  76   uint32_t utilization_out;
  77
  78   /**
  79    * Actual traffic on this connection from the other peer to this peer.
  80    * Includes transport overhead.
  81    *
  82    * Unit: [bytes/second]
  83    */
  84   uint32_t utilization_in;
  85
  86   /**
  87    * Distance on network layer (required for distance-vector routing)
  88    * in hops.  Zero for direct connections (i.e. plain TCP/UDP).
  89    */
  90   uint32_t distance;
  91
  92   /**
  93    * MTU of the network layer, UINT32_MAX for no MTU (stream).
  94    *
  95    * Unit: [bytes]
  96    */
  97   uint32_t mtu;
  98
  99   /**
 100    * Which network scope does the respective address belong to?
 101    */
 102   enum GNUNET_NetworkType nt;
 103
 104   /**
 105    * What characteristics does this communicator have?
 106    */
 107   enum GNUNET_TRANSPORT_CommunicatorCharacteristics cc;
 108 };
 109
 110
 111 /* ******************************** Transport API ***************************** */
 112
 113 /**
 114  * Handle to the ATS subsystem for bandwidth/transport transport information.
 115  */
 116 struct GNUNET_ATS_TransportHandle;
 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
 139                                   bandwidth_out,
 140                                   struct GNUNET_BANDWIDTH_Value32NBO
 141                                   bandwidth_in);
 142
 143
 144 /**
 145  * Signature of a function called by ATS suggesting transport to
 146  * try connecting with a particular address.
 147  *
 148  * @param cls closure
 149  * @param pid target peer
 150  * @param address the address to try
 151  */
 152 typedef void
 153 (*GNUNET_ATS_SuggestionCallback) (void *cls,
 154                                   const struct GNUNET_PeerIdentity *pid,
 155                                   const char *address);
 156
 157
 158 /**
 159  * Initialize the ATS transport subsystem.
 160  *
 161  * @param cfg configuration to use
 162  * @param alloc_cb notification to call whenever the allocation changed
 163  * @param alloc_cb_cls closure for @a alloc_cb
 164  * @param suggest_cb notification to call whenever the suggestation is made
 165  * @param suggest_cb_cls closure for @a suggest_cb
 166  * @return ats context
 167  */
 168 struct GNUNET_ATS_TransportHandle *
 169 GNUNET_ATS_transport_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
 170                            GNUNET_ATS_AllocationCallback alloc_cb,
 171                            void *alloc_cb_cls,
 172                            GNUNET_ATS_SuggestionCallback suggest_cb,
 173                            void *suggest_cb_cls);
 174
 175
 176 /**
 177  * Client is done with ATS transport, release resources.
 178  *
 179  * @param ath handle to release
 180  */
 181 void
 182 GNUNET_ATS_transport_done (struct GNUNET_ATS_TransportHandle *ath);
 183
 184
 185 /**
 186  * Handle used within ATS to track an session.
 187  */
 188 struct GNUNET_ATS_SessionRecord;
 189
 190
 191 /**
 192  * We have a new session ATS should know. Sessiones have to be added with this
 193  * function before they can be: updated, set in use and destroyed
 194  *
 195  * @param ath handle
 196  * @param pid peer we connected to
 197  * @param address the address (human readable version),
 198  * @param session transport-internal handle for the session/queue, NULL if
 199  *        the session is inbound-only
 200  * @param prop performance data for the session
 201  * @return handle to the session representation inside ATS, NULL
 202  *         on error (i.e. ATS knows this exact session already, or
 203  *         session is invalid)
 204  */
 205 struct GNUNET_ATS_SessionRecord *
 206 GNUNET_ATS_session_add (struct GNUNET_ATS_TransportHandle *ath,
 207                         const struct GNUNET_PeerIdentity *pid,
 208                         const char *address,
 209                         struct GNUNET_ATS_Session *session,
 210                         const struct GNUNET_ATS_Properties *prop);
 211
 212
 213 /**
 214  * We have updated performance statistics for a given session.  Based
 215  * on the information provided, ATS may update bandwidth assignments.
 216  *
 217  * @param ar session record to update information for
 218  * @param prop performance data for the session
 219  */
 220 void
 221 GNUNET_ATS_session_update (struct GNUNET_ATS_SessionRecord *ar,
 222                            const struct GNUNET_ATS_Properties *prop);
 223
 224
 225 /**
 226  * A session was destroyed, ATS should now schedule and
 227  * allocate under the assumption that this @a ar is no
 228  * longer in use.
 229  *
 230  * @param ar session record to drop
 231  */
 232 void
 233 GNUNET_ATS_session_del (struct GNUNET_ATS_SessionRecord *ar);
 234
 235
 236 #endif
 237
 238 /** @} */  /* end of group */
 239
 240 /* end of file gnunet-service-transport_ats.h */