From 03a39827ef721653ad9509ce12173bd674592caf Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 8 Feb 2015 22:46:45 +0000 Subject: -updating comments --- src/ats/plugin_ats_proportional.c | 194 +++----------------------------------- 1 file changed, 15 insertions(+), 179 deletions(-) diff --git a/src/ats/plugin_ats_proportional.c b/src/ats/plugin_ats_proportional.c index bacb57e02..d65cbb289 100644 --- a/src/ats/plugin_ats_proportional.c +++ b/src/ats/plugin_ats_proportional.c @@ -17,7 +17,6 @@ Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ - /** * @file ats/plugin_ats_proportional.c * @brief ATS proportional solver @@ -30,189 +29,24 @@ #include "gnunet_ats_service.h" #include "gnunet-service-ats_addresses.h" -#define PROP_STABILITY_FACTOR 1.25 - - #define LOG(kind,...) GNUNET_log_from (kind, "ats-proportional",__VA_ARGS__) - /** - * - * NOTE: Do not change this documentation. This documentation is based - * on gnunet.org:/vcs/fsnsg/ats-paper.git/tech-doku/ats-tech-guide.tex - * use build_txt.sh to generate plaintext output - * - * ATS addresses : proportional solver - * - * The proportional solver ("proportional") distributes the available - * bandwidth fair over all the addresses influenced by the - * preference values. For each available network type an in- and - * outbound quota is configured and the bandwidth available in - * these networks is distributed over the addresses. The solver - * first assigns every addresses the minimum amount of bandwidth - * #GNUNET_CONSTANTS_DEFAULT_BW_IN_OUT and then distributes the - * remaining bandwidth available according to the preference - * values. For each peer only a single address gets bandwidth - * assigned and only one address marked as active. The most - * important functionality for the solver is implemented in: * - * find_address_it is an hashmap iterator returning the prefered - * address for an peer * update_quota_per_network distributes - * available bandwidth for a network over active addresses - * - * Changes to addresses automatically have an impact on the the - * bandwidth assigned to other addresses in the same network since - * the solver distributes the remaining bandwidth over the - * addresses in the network. When changes to the addresses occur, - * the solver first performs the changes, like adding or deleting - * addresses, and then updates bandwidth assignment for the - * affected network. Bandwidth assignment is only recalculated on - * demand when an address is requested by a client for a peer or - * when the addresses available have changed or an address changed - * the network it is located in. When the bandwidth assignment has - * changed the callback is called with the new bandwidth - * assignments. The bandwidth distribution for a network is - * recalculated due to: * address suggestion requests * address - * deletions * address switching networks during address update * - * preference changes - * - * 3.1 Data structures used - * - * For each ATS network (e.g. WAN, LAN, loopback) a struct Network - * is used to specify network related information as total adresses - * and active addresses in this network and the configured in- and - * outbound quota. Each network also contains a list of addresses - * added to the solver located in this network. The proportional - * solver uses the addresses' solver_information field to store the - * proportional network it belongs to for each address. - * - * 3.2 Initializing - * - * When the proportional solver is initialized the solver creates a - * new solver handle and initializes the network structures with - * the quotas passed from addresses and returns the handle solver. - * - * 3.3 Adding an address - * - * When a new address is added to the solver using s_add, a lookup - * for the network for this address is done and the address is - * enqueued in in the linked list of the network. - * - * 3.4 Updating an address - * - * The main purpose of address updates is to update the ATS - * information for addresse selection. Important for the proportional - * solver is when an address switches network it is located - * in. This is common because addresses added by transport's - * validation mechanism are commonly located in - * #GNUNET_ATS_NET_UNSPECIFIED. Addresses in validation are located - * in this network type and only if a connection is successful on - * return of payload data transport switches to the real network - * the address is located in. When an address changes networks it - * is first of all removed from the old network using the solver - * API function #GAS_proportional_address_delete() and the network in - * the address struct is updated. A lookup for the respective new - * proportional network is done and stored in the addresse's - * solver_information field. Next the address is re-added to the - * solver using the solver API function - * #GAS_proportional_address_add(). If the address was marked as in - * active, the solver checks if bandwidth is available in the - * network and if yes sets the address to active and updates the - * bandwidth distribution in this network. If no bandwidth is - * available it sets the bandwidth for this address to 0 and tries - * to suggest an alternative address. If an alternative address was - * found, addresses' callback is called for this address. - * - * 3.5 Deleting an address - * - * When an address is removed from the solver, it removes the - * respective address from the network and if the address was - * marked as active, it updates the bandwidth distribution for this - * network. - * - * 3.6 Requesting addresses - * - * When an address is requested for a peer the solver performs a - * lookup for the peer entry in addresses address hashmap and - * selects the best address. The selection of the most suitable - * address is done in the find_address_it hashmap iterator - * described in detail in section 3.7. If no address is returned, - * no address can be suggested at the moment. If the address - * returned is marked as active, the solver can return this - * address. If the address is not marked as active, the solver - * checks if another address belongign to this peer is marked as - * active and marks the address as inactive, updates the bandwidth - * for this address to 0, call the bandwidth changed callback for - * this address due to the change and updates quota assignment for - * the addresse's network. the now in-active address is belonging - * to. The solver marks the new address as active and updates the - * bandwidth assignment for this network. - * - * 3.7 Choosing addresses - * - * Choosing the best possible address for suggestion is done by - * iterating over all addresses of a peer stored in addresses' - * hashmap and using the hashmap iterator find_address_it to select - * the best available address. Several checks are done when an - * address is selected. First if this address is currently blocked - * by addresses from being suggested. An address is blocked for the - * duration of #ATS_BLOCKING_DELTA when it is suggested to - * transport. Next it is checked if at least - * #GNUNET_CONSTANTS_DEFAULT_BW_IN_OUT bytes bandwidth is available - * in the addresse's network, because suggesting an address without - * bandwidth does not make sense. This also ensures that all active - * addresses in this network get at least the minimum amount of - * bandwidth assigned. In the next step the solver ensures that for - * tcp connections inbound connections are prefered over outbound - * connections. In the next stet the solver ensures that - * connections are prefered in the following order: * connections - * are already established and have bandwidth assigned * - * connections with a shorter distance * connectes have a shorter - * latency - * - * 3.8 Changing preferences - * - * 3.9 Shutdown - * - * During shutdown all network entries and aging processes are - * destroyed and freed. - * - * - * OLD DOCUMENTATION - * - * This solver assigns in and outbound bandwidth equally for all - * addresses in specific network type (WAN, LAN) based on configured - * in and outbound quota for this network. - * - * The solver is notified by addresses about changes to the addresses - * and recalculates the bandwith assigned if required. The solver - * notifies addresses by calling the GAS_bandwidth_changed_cb - * callback. - * - * - Initialization - * - * - * - * - * For each peer only a single is selected and marked as "active" in the address - * struct. - * - * E.g.: - * - * You have the networks WAN and LAN and quotas - * WAN_TOTAL_IN, WAN_TOTAL_OUT - * LAN_TOTAL_IN, LAN_TOTAL_OUT - * - * If you have x addresses in the network segment LAN, the quotas are - * QUOTA_PER_ADDRESS = LAN_TOTAL_OUT / x - * - * Quotas are automatically recalculated and reported back when addresses are - * - requested - * + * How much do we value stability over adaptation by default. A low + * value (close to 1.0) means we adapt as soon as possible, a larger + * value means that we have to have the respective factor of an + * advantage (or delay) before we adapt and sacrifice stability. */ +#define PROP_STABILITY_FACTOR 1.25 + /** - * Default value to assume for the proportionality factor, - * if none is given in the configuration. + * Default value to assume for the proportionality factor, if none is + * given in the configuration. This factor determines how strong the + * bandwidth allocation will orient itself on the application + * preferences. A lower factor means a more balanced bandwidth + * distribution while a larger number means a distribution more in + * line with application (bandwidth) preferences. */ #define PROPORTIONALITY_FACTOR 2.0 @@ -1050,6 +884,8 @@ GAS_proportional_change_preference (void *solver, { struct GAS_PROPORTIONAL_Handle *s = solver; + if (GNUNET_ATS_PREFERENCE_BANDWIDTH != kind) + return; /* we do not care */ distribute_bandwidth_in_network (s, NULL); } @@ -1172,7 +1008,7 @@ GAS_proportional_bulk_stop (void *solver) * * @param solver solver handle * @param address the address - * @param type the ATSI type in HBO + * @param type the ATSI type * @param abs_value the absolute value of the property * @param rel_value the normalized value */ -- cgit v1.2.3