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   /**
  50    * Delay.  Time between when the time packet is sent and the packet
  51    * arrives.  FOREVER if we did not (successfully) measure yet.
  52    */
  53   struct GNUNET_TIME_Relative delay;
  54
  55   /**
  56    * Confirmed successful payload on this connection from this peer to
  57    * the other peer.
  58    *
  59    * Unit: [bytes/second]
  60    */
  61   uint32_t goodput_out;
  62
  63   /**
  64    * Confirmed useful payload on this connection to this peer from
  65    * the other peer.
  66    *
  67    * Unit: [bytes/second]
  68    */
  69   uint32_t goodput_in;
  70
  71   /**
  72    * Actual traffic on this connection from this peer to the other peer.
  73    * Includes transport overhead.
  74    *
  75    * Unit: [bytes/second]
  76    */
  77   uint32_t utilization_out;
  78
  79   /**
  80    * Actual traffic on this connection from the other peer to this peer.
  81    * Includes transport overhead.
  82    *
  83    * Unit: [bytes/second]
  84    */
  85   uint32_t utilization_in;
  86
  87   /**
  88    * Distance on network layer (required for distance-vector routing)
  89    * in hops.  Zero for direct connections (i.e. plain TCP/UDP).
  90    */
  91   uint32_t distance;
  92
  93   /**
  94    * MTU of the network layer, UINT32_MAX for no MTU (stream).
  95    *
  96    * Unit: [bytes]
  97    */
  98   uint32_t mtu;
  99
 100   /**
 101    * Which network scope does the respective address belong to?
 102    */
 103   enum GNUNET_NetworkType nt;
 104
 105   /**
 106    * What characteristics does this communicator have?
 107    */
 108   enum GNUNET_TRANSPORT_CommunicatorCharacteristics cc;
 109
 110 };
 111
 112
 113 /* ******************************** Transport API ***************************** */
 114
 115 /**
 116  * Handle to the ATS subsystem for bandwidth/transport transport information.
 117  */
 118 struct GNUNET_ATS_TransportHandle;
 119
 120 /**
 121  * Opaque session handle, to be defined by transport.  Contents not known to ATS.
 122  */
 123 struct GNUNET_ATS_Session;
 124
 125
 126 /**
 127  * Signature of a function called by ATS with the current bandwidth
 128  * allocation to be used as determined by ATS.
 129  *
 130  * @param cls closure
 131  * @param session session this is about
 132  * @param bandwidth_out assigned outbound bandwidth for the connection,
 133  *        0 to signal disconnect
 134  * @param bandwidth_in assigned inbound bandwidth for the connection,
 135  *        0 to signal disconnect
 136  */
 137 typedef void
 138 (*GNUNET_ATS_AllocationCallback) (void *cls,
 139                                   struct GNUNET_ATS_Session *session,
 140                                   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out,
 141                                   struct GNUNET_BANDWIDTH_Value32NBO 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 */