[GNUnet-SVN] r26152 - gnunet/src/ats

[gnunet]

Author: wachs
Date: 2013-02-18 17:11:05 +0100 (Mon, 18 Feb 2013)
New Revision: 26152

Modified:
   gnunet/src/ats/gnunet-service-ats_addresses_simplistic.c
Log:
docu


Modified: gnunet/src/ats/gnunet-service-ats_addresses_simplistic.c
===================================================================
--- gnunet/src/ats/gnunet-service-ats_addresses_simplistic.c    2013-02-18 
15:39:20 UTC (rev 26151)
+++ gnunet/src/ats/gnunet-service-ats_addresses_simplistic.c    2013-02-18 
16:11:05 UTC (rev 26152)
@@ -39,103 +39,130 @@
  *
  * ATS addresses : simplistic solver
  *
- * The simplistic solver ("simplistic") 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
+ *    The simplistic solver ("simplistic") 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
  *
- * 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
+ *    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
+ *     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 simplistic solver uses the addresses' solver_information
- * field to store the simplistic network it belongs to for each address.
+ *    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 simplistic solver uses the addresses' solver_information
+ *    field to store the simplistic network it belongs to for each address.
  *
- *  3.2 Initializing
+ *     3.2 Initializing
  *
- * When the simplistic 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.
+ *    When the simplistic 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
+ *     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.
+ *    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
+ *     3.4 Updating an address
  *
- * The main purpose of address updates is to update the ATS information for
- * addresse selection. Important for the simplistic 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_simplistic_address_delete and
- * the network in the address struct is updated. A lookup for the respective
- * new simplistic 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_simplistic_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.
+ *    The main purpose of address updates is to update the ATS information for
+ *    addresse selection. Important for the simplistic 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_simplistic_address_delete and
+ *    the network in the address struct is updated. A lookup for the respective
+ *    new simplistic 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_simplistic_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
+ *     3.5 Deleting an address
  *
- * When an address is removed from the solver removes the respective address
- * from the network and if the address was marked as active, it updates the
- * bandwidth distribution for this network.
+ *    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
+ *     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.
+ *    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
+ *     3.7 Choosing addresses
  *
- *  3.8 Changing preferences
+ *    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.9 Shutdown
+ *     3.8 Changing preferences
  *
+ *     3.9 Shutdown
+ *
+ *    During shutdown all network entries and aging processes are destroyed and
+ *    freed.
+ *
+ *
  * OLD DOCUMENTATION
  *
  * This solver ssigns in and outbound bandwidth equally for all addresses in