add design sketch for new ATS API

4 files changed, 370 insertions, 1 deletions

diff --git a/src/include/Makefile.am b/src/include/Makefile.am
index 185f649ac..9d0c4f8ea 100644
--- a/src/include/Makefile.am
+++ b/src/include/Makefile.am
@@ -29,6 +29,8 @@ gnunetinclude_HEADERS = \
   gnunet_applications.h \
   gnunet_arm_service.h \
   gnunet_ats_service.h \
+  gnunet_ats_application_service.h \
+  gnunet_ats_transport_service.h \
   gnunet_ats_plugin.h \
   gnunet_bandwidth_lib.h \
   gnunet_bio_lib.h \
diff --git a/src/include/gnunet_ats_application_service.h b/src/include/gnunet_ats_application_service.h
new file mode 100644
index 000000000..af92d5639
--- /dev/null
+++ b/src/include/gnunet_ats_application_service.h
@@ -0,0 +1,99 @@
+/*
+ This file is part of GNUnet.
+ Copyright (C) 2010-2015, 2018 GNUnet e.V.
+
+ GNUnet is free software: you can redistribute it and/or modify it
+ under the terms of the GNU Affero General Public License as published
+ by the Free Software Foundation, either version 3 of the License,
+ or (at your option) any later version.
+
+ GNUnet is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+/**
+ * @file
+ * Bandwidth allocation API for applications to interact with
+ *
+ * @author Christian Grothoff
+ * @author Matthias Wachs
+ *
+ * @defgroup ats  ATS service
+ * Bandwidth allocation
+ *
+ * @see [Documentation](https://gnunet.org/ats-subsystem)
+ *
+ * @{
+ */
+#ifndef GNUNET_ATS_APPLICATION_SERVICE_H
+#define GNUNET_ATS_APPLICATION_SERVICE_H
+
+#include "gnunet_constants.h"
+#include "gnunet_util_lib.h"
+
+/**
+ * Handle to the ATS subsystem for making suggestions about
+ * connections the peer would like to have.
+ */
+struct GNUNET_ATS_ConnectivityHandle;
+
+
+/**
+ * Initialize the ATS connectivity suggestion client handle.
+ *
+ * @param cfg configuration to use
+ * @return ats connectivity handle, NULL on error
+ */
+struct GNUNET_ATS_ConnectivityHandle *
+GNUNET_ATS_connectivity_init (const struct GNUNET_CONFIGURATION_Handle *cfg);
+
+
+/**
+ * Shutdown ATS connectivity suggestion client.
+ *
+ * @param ch handle to destroy
+ */
+void
+GNUNET_ATS_connectivity_done (struct GNUNET_ATS_ConnectivityHandle *ch);
+
+
+/**
+ * Handle for address suggestion requests.
+ */
+struct GNUNET_ATS_ConnectivitySuggestHandle;
+
+
+/**
+ * An application would like to communicate with a peer.  ATS should
+ * allocate bandwith using a suitable address for requiremetns @a pk
+ * to transport.
+ *
+ * @param ch handle
+ * @param peer identity of the peer we need an address for
+ * @param pk what kind of connectivity will the application require (can be
+ *         #GNUNET_MQ_PREFERENCE_NONE, we will still try to connect)
+ * @param bw desired bandwith, can be zero (we will still try to connect)
+ * @return suggestion handle, NULL if request is already pending
+ */
+struct GNUNET_ATS_ConnectivitySuggestHandle *
+GNUNET_ATS_connectivity_suggest (struct GNUNET_ATS_ConnectivityHandle *ch,
+                                 const struct GNUNET_PeerIdentity *peer,
+                                 enum GNUNET_MQ_PreferenceKind pk,
+                                 struct GNUNET_BANDWIDTH_Value32NBO bw);
+
+
+/**
+ * We no longer care about communicating with a peer.
+ *
+ * @param sh handle
+ */
+void
+GNUNET_ATS_connectivity_suggest_cancel (struct GNUNET_ATS_ConnectivitySuggestHandle *sh);
+
+/** @} */  /* end of group */
+
+/* end of file gnunet_ats_application_service.h */
diff --git a/src/include/gnunet_ats_transport_service.h b/src/include/gnunet_ats_transport_service.h
new file mode 100644
index 000000000..b069f8b24
--- /dev/null
+++ b/src/include/gnunet_ats_transport_service.h
@@ -0,0 +1,238 @@
+/*
+ This file is part of GNUnet.
+ Copyright (C) 2010-2015, 2018 GNUnet e.V.
+
+ GNUnet is free software: you can redistribute it and/or modify it
+ under the terms of the GNU Affero General Public License as published
+ by the Free Software Foundation, either version 3 of the License,
+ or (at your option) any later version.
+
+ GNUnet is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+/**
+ * @file
+ * Bandwidth allocation API for the transport service
+ *
+ * @author Christian Grothoff
+ * @author Matthias Wachs
+ *
+ * @defgroup ats  ATS service
+ * Bandwidth allocation for transport service
+ *
+ * @see [Documentation](https://gnunet.org/ats-subsystem)
+ *
+ * @{
+ */
+#ifndef GNUNET_ATS_TRANSPORT_SERVICE_H
+#define GNUNET_ATS_TRANSPORT_SERVICE_H
+
+#include "gnunet_constants.h"
+#include "gnunet_util_lib.h"
+#include "gnunet_nt_lib.h"
+#include "gnunet_transport_communication_service.h"
+
+
+/**
+ * ATS performance characteristics for an address.
+ */
+struct GNUNET_ATS_Properties
+{
+
+  /**
+   * Delay.  Time between when the time packet is sent and the packet
+   * arrives.  FOREVER if we did not (successfully) measure yet.
+   */
+  struct GNUNET_TIME_Relative delay;
+
+  /**
+   * Confirmed successful payload on this connection from this peer to
+   * the other peer.
+   *
+   * Unit: [bytes/second]
+   */
+  uint32_t goodput_out;
+
+  /**
+   * Confirmed useful payload on this connection to this peer from
+   * the other peer.
+   *
+   * Unit: [bytes/second]
+   */
+  uint32_t goodput_in;
+
+  /**
+   * Actual traffic on this connection from this peer to the other peer.
+   * Includes transport overhead.
+   *
+   * Unit: [bytes/second]
+   */
+  uint32_t utilization_out;
+
+  /**
+   * Actual traffic on this connection from the other peer to this peer.
+   * Includes transport overhead.
+   *
+   * Unit: [bytes/second]
+   */
+  uint32_t utilization_in;
+
+  /**
+   * Distance on network layer (required for distance-vector routing)
+   * in hops.  Zero for direct connections (i.e. plain TCP/UDP).
+   */
+  uint32_t distance;
+
+  /**
+   * MTU of the network layer, UINT32_MAX for no MTU (stream).
+   *
+   * Unit: [bytes]
+   */
+  uint32_t mtu;
+
+  /**
+   * Which network scope does the respective address belong to?
+   */
+  enum GNUNET_NetworkType nt;
+
+  /**
+   * What characteristics does this communicator have?
+   */
+  enum GNUNET_TRANSPORT_CommunicatorCharacteristics cc;
+
+};
+
+
+/* ******************************** Scheduling API ***************************** */
+
+/**
+ * Handle to the ATS subsystem for bandwidth/transport scheduling information.
+ */
+struct GNUNET_ATS_SchedulingHandle;
+
+/**
+ * Opaque session handle, to be defined by transport.  Contents not known to ATS.
+ */
+struct GNUNET_ATS_Session;
+
+
+/**
+ * Signature of a function called by ATS with the current bandwidth
+ * allocation to be used as determined by ATS.
+ *
+ * @param cls closure
+ * @param session session this is about
+ * @param bandwidth_out assigned outbound bandwidth for the connection,
+ *        0 to signal disconnect
+ * @param bandwidth_in assigned inbound bandwidth for the connection,
+ *        0 to signal disconnect
+ */
+typedef void
+(*GNUNET_ATS_AllocationCallback) (void *cls,
+                                  struct GNUNET_ATS_Session *session,
+                                  struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out,
+                                  struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in);
+
+
+/**
+ * Signature of a function called by ATS suggesting transport to
+ * try connecting with a particular address.
+ *
+ * @param cls closure
+ * @param pid target peer
+ * @param address the address to try
+ */
+typedef void
+(*GNUNET_ATS_SuggestionCallback) (void *cls,
+                                  const struct GNUNET_PeerIdentity *pid,
+                                  const char *address);
+
+
+/**
+ * Initialize the ATS scheduling subsystem.
+ *
+ * @param cfg configuration to use
+ * @param alloc_cb notification to call whenever the allocation changed
+ * @param alloc_cb_cls closure for @a alloc_cb
+ * @param suggest_cb notification to call whenever the suggestation is made
+ * @param suggest_cb_cls closure for @a suggest_cb
+ * @return ats context
+ */
+struct GNUNET_ATS_SchedulingHandle *
+GNUNET_ATS_scheduling_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
+                            GNUNET_ATS_AllocationCallback alloc_cb,
+                            void *alloc_cb_cls);
+                            GNUNET_ATS_SuggestionCallback suggest_cb,
+                            void *suggest_cb_cls);
+
+
+/**
+ * Client is done with ATS scheduling, release resources.
+ *
+ * @param sh handle to release
+ */
+void
+GNUNET_ATS_scheduling_done (struct GNUNET_ATS_SchedulingHandle *sh);
+
+
+/**
+ * Handle used within ATS to track an address.
+ */
+struct GNUNET_ATS_AddressRecord;
+
+
+/**
+ * We have a new address ATS should know. Addresses have to be added with this
+ * function before they can be: updated, set in use and destroyed
+ *
+ * @param sh handle
+ * @param pid peer we connected to
+ * @param address the address (human readable version), NULL if
+ *        the session is inbound-only
+ * @param session transport-internal handle for the address/queue
+ * @param prop performance data for the address
+ * @return handle to the address representation inside ATS, NULL
+ *         on error (i.e. ATS knows this exact address already, or
+ *         address is invalid)
+ */
+struct GNUNET_ATS_AddressRecord *
+GNUNET_ATS_address_add (struct GNUNET_ATS_SchedulingHandle *sh,
+                        const struct GNUNET_PeerIdentity *pid,
+                        const char *address,
+                        struct GNUNET_ATS_Session *session,
+                        const struct GNUNET_ATS_Properties *prop);
+
+
+/**
+ * We have updated performance statistics for a given address.  Based
+ * on the information provided, ATS may update bandwidth assignments.
+ *
+ * @param ar address record to update information for
+ * @param prop performance data for the address
+ */
+void
+GNUNET_ATS_address_update (struct GNUNET_ATS_AddressRecord *ar,
+                           const struct GNUNET_ATS_Properties *prop);
+
+
+/**
+ * A session was destroyed, ATS should now schedule and
+ * allocate under the assumption that this @a ar is no
+ * longer in use.
+ *
+ * @param ar address record to drop
+ */
+void
+GNUNET_ATS_address_del (struct GNUNET_ATS_AddressRecord *ar);
+
+
+#endif
+
+/** @} */  /* end of group */
+
+/* end of file gnunet-service-transport_ats.h */
diff --git a/src/include/gnunet_transport_communication_service.h b/src/include/gnunet_transport_communication_service.h
index fed681f0f..e80ba85cf 100644
--- a/src/include/gnunet_transport_communication_service.h
+++ b/src/include/gnunet_transport_communication_service.h
@@ -11,7 +11,7 @@
      WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      Affero General Public License for more details.
-    
+
      You should have received a copy of the GNU Affero General Public License
      along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
@@ -80,12 +80,36 @@ struct GNUNET_TRANSPORT_CommunicatorHandle;
 
 
 /**
+ * What characteristics does this communicator have?
+ */
+enum GNUNET_TRANSPORT_CommunicatorCharacteristics {
+
+  /**
+   * Characteristics are unknown (i.e. DV).
+   */
+  GNUNET_TRANSPORT_CC_UNKNOWN = 0,
+
+  /**
+   * Transmission is reliabile (with ACKs), i.e. TCP/HTTP/HTTPS.
+   */
+  GNUNET_TRANSPORT_CC_RELIABLE = 1,
+
+  /**
+   * Transmission is unreliable (i.e. UDP)
+   */
+  GNUNET_TRANSPORT_CC_UNRELIABILE = 2
+
+};
+
+
+/**
  * Connect to the transport service.
  *
  * @param cfg configuration to use
  * @param config_section section of the configuration to use for options
  * @param addr_prefix address prefix for addresses supported by this
  *        communicator, could be NULL for incoming-only communicators
+ * @param cc what characteristics does the communicator have?
  * @param mq_init function to call to initialize a message queue given
  *                the address of another peer, can be NULL if the
  *                communicator only supports receiving messages
@@ -96,6 +120,7 @@ struct GNUNET_TRANSPORT_CommunicatorHandle *
 GNUNET_TRANSPORT_communicator_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
                                        const char *config_section_name,
                                        const char *addr_prefix,
+                                       enum GNUNET_TRANSPORT_CommunicatorCharacteristics cc,
                                        GNUNET_TRANSPORT_CommunicatorMqInit mq_init,
                                        void *mq_init_cls);
 
@@ -162,14 +187,17 @@ struct GNUNET_TRANSPORT_QueueHandle;
  * Possible states of a connection.
  */
 enum GNUNET_TRANSPORT_ConnectionStatus {
+
   /**
    * Connection is down.
    */
   GNUNET_TRANSPORT_CS_DOWN = -1,
+
   /**
    * this is an outbound connection (transport initiated)
    */
   GNUNET_TRANSPORT_CS_OUTBOUND = 0,
+
   /**
    * this is an inbound connection (communicator initiated)
    */
@@ -188,6 +216,7 @@ enum GNUNET_TRANSPORT_ConnectionStatus {
  * @param mtu maximum message size supported by queue, 0 if
  *            sending is not supported, SIZE_MAX for no MTU
  * @param nt which network type does the @a address belong to?
+ * @param distance how many hops does this queue use (DV-only)?
  * @param cs what is the connection status of the queue?
  * @param mq message queue of the @a peer
  * @return API handle identifying the new MQ
@@ -198,6 +227,7 @@ GNUNET_TRANSPORT_communicator_mq_add (struct GNUNET_TRANSPORT_CommunicatorHandle
                                       const char *address,
                                       uint32_t mtu,
                                       enum GNUNET_ATS_Network_Type nt,
+                                      uint32_t distance,
                                       enum GNUNET_TRANSPORT_ConnectionStatus cs,
                                       struct GNUNET_MQ_Handle *mq);