-updating comments

1 files 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
  */