X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Ftransport%2Fgnunet-service-transport_ats.h;h=d9d7b555be0164fe67967361ded920c1f221a319;hb=abdec5e11ff11bb10d32c013e11344a54786f80f;hp=b203cc3232d41c107acdca622a20167bfe4bad7e;hpb=4939e6e943f7480ebc9d5c23b6cc3251e8a42286;p=oweals%2Fgnunet.git diff --git a/src/transport/gnunet-service-transport_ats.h b/src/transport/gnunet-service-transport_ats.h index b203cc323..d9d7b555b 100644 --- a/src/transport/gnunet-service-transport_ats.h +++ b/src/transport/gnunet-service-transport_ats.h @@ -1,6 +1,6 @@ /* This file is part of GNUnet. - (C) 2015 Christian Grothoff (and other contributing authors) + Copyright (C) 2015 GNUnet e.V. GNUnet is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published @@ -14,22 +14,13 @@ You should have received a copy of the GNU General Public License along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. + Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. */ /** * @file transport/gnunet-service-transport_ats.h * @brief interfacing between transport and ATS service * @author Christian Grothoff - * - * FIXME: - * - add API to give ATS feedback about an address that was - * suggested but did not work out (without fully 'deleting' - * it forever) - * - improve ATS API to take advantage of this new subsystem - * when calling ATS functions, make ATS API match this API - * more closely - * - combine with API to tell ATS about address "use" */ #ifndef GNUNET_SERVICE_TRANSPORT_ATS_H #define GNUNET_SERVICE_TRANSPORT_ATS_H @@ -51,82 +42,152 @@ GST_ats_done (void); /** - * Test if ATS knows about this address. + * Test if ATS knows about this @a address and @a session. + * Note that even if the address is expired, we return + * #GNUNET_YES if the respective session matches. * * @param address the address * @param session the session - * @return #GNUNET_YES if address is known, #GNUNET_NO if not. + * @return #GNUNET_YES if @a address is known, #GNUNET_NO if not. */ int GST_ats_is_known (const struct GNUNET_HELLO_Address *address, - struct Session *session); + struct GNUNET_ATS_Session *session); + /** - * Notify ATS about the new address including the network this address is - * located in. + * Test if ATS knows about this @a address. Note that + * expired addresses do not count. + * + * @param address the address + * @return #GNUNET_YES if @a address is known, #GNUNET_NO if not. + */ +int +GST_ats_is_known_no_session (const struct GNUNET_HELLO_Address *address); + + +/** + * Temporarily block a valid address for use by ATS for address + * suggestions. This function should be called if an address was + * suggested by ATS but failed to perform (i.e. failure to establish a + * session or to exchange the PING/PONG). + * + * @param address the address to block + * @param session the session (can be NULL) + */ +void +GST_ats_block_address (const struct GNUNET_HELLO_Address *address, + struct GNUNET_ATS_Session *session); + + +/** + * Reset address blocking time. Resets the exponential + * back-off timer for this address to zero. Called when + * an address was used to create a successful connection. + * + * @param address the address to reset the blocking timer + * @param session the session (can be NULL) + */ +void +GST_ats_block_reset (const struct GNUNET_HELLO_Address *address, + struct GNUNET_ATS_Session *session); + + +/** + * Notify ATS about a new inbound @a address. The @a address in + * combination with the @a session must be new, but this function will + * perform a santiy check. If the @a address is indeed new, make it + * available to ATS. * * @param address the address * @param session the session - * @param ats ats information - * @param ats_count number of @a ats information + * @param prop performance information + */ +void +GST_ats_add_inbound_address (const struct GNUNET_HELLO_Address *address, + struct GNUNET_ATS_Session *session, + const struct GNUNET_ATS_Properties *prop); + + +/** + * Notify ATS about a new address including the network this address is + * located in. The address must NOT be inbound and must be new to ATS. + * + * @param address the address + * @param prop performance information */ void GST_ats_add_address (const struct GNUNET_HELLO_Address *address, - struct Session *session, - const struct GNUNET_ATS_Information *ats, - uint32_t ats_count); + const struct GNUNET_ATS_Properties *prop); /** - * Notify ATS about a new session now existing for the given - * address. + * Notify ATS about a new @a session now existing for the given + * @a address. Essentially, an outbound @a address was used + * to establish a @a session. It is safe to call this function + * repeatedly for the same @a address and @a session pair. * * @param address the address * @param session the session */ void GST_ats_new_session (const struct GNUNET_HELLO_Address *address, - struct Session *session); + struct GNUNET_ATS_Session *session); + + +/** + * Notify ATS about utilization changes to an @a address. + * Does nothing if the @a address is not known to us. + * + * @param address our information about the address + * @param bps_in new utilization inbound + * @param bps_out new utilization outbound + */ +void +GST_ats_update_utilization (const struct GNUNET_HELLO_Address *address, + uint32_t bps_in, + uint32_t bps_out); /** - * Notify ATS about a new session now being in use (or not). + * Notify ATS about @a delay changes to properties of an @a address. + * Does nothing if the @a address is not known to us. * * @param address the address * @param session the session - * @param in_use #GNUNET_YES or #GNUNET_NO + * @param delay new delay value */ void -GST_ats_set_in_use (const struct GNUNET_HELLO_Address *address, - struct Session *session, - int in_use); +GST_ats_update_delay (const struct GNUNET_HELLO_Address *address, + struct GNUNET_TIME_Relative delay); /** - * Notify ATS about property changes to an address + * Notify ATS about DV @a distance change to an @a address. + * Does nothing if the @a address is not known to us. * * @param address the address - * @param session the session - * @param ats performance information - * @param ats_count number of elements in @a ats + * @param distance new distance value */ void -GST_ats_update_metrics (const struct GNUNET_HELLO_Address *address, - struct Session *session, - const struct GNUNET_ATS_Information *ats, - uint32_t ats_count); +GST_ats_update_distance (const struct GNUNET_HELLO_Address *address, + uint32_t distance); /** - * Notify ATS that the session (but not the address) of - * a given address is no longer relevant. + * Notify ATS that the @a session (but not the @a address) of + * a given @a address is no longer relevant. (The @a session + * went down.) This function may be called even if for the + * respective outbound address #GST_ats_new_session() was + * never called and thus the pair is unknown to ATS. In this + * case, the call is simply ignored. * * @param address the address * @param session the session */ void GST_ats_del_session (const struct GNUNET_HELLO_Address *address, - struct Session *session); + struct GNUNET_ATS_Session *session); /**