[GNUnet-SVN] r30025 - gnunet/src/include

[gnunet]

Author: wachs
Date: 2013-10-09 09:48:25 +0200 (Wed, 09 Oct 2013)
New Revision: 30025

Modified:
   gnunet/src/include/gnunet_ats_plugin.h
Log:
documentation for solver api


Modified: gnunet/src/include/gnunet_ats_plugin.h
===================================================================
--- gnunet/src/include/gnunet_ats_plugin.h      2013-10-09 07:37:11 UTC (rev 
30024)
+++ gnunet/src/include/gnunet_ats_plugin.h      2013-10-09 07:48:25 UTC (rev 
30025)
@@ -195,65 +195,103 @@
 
 
 /**
- * Each plugin is required to return a pointer to a struct of this
- * type as the return value from its entry point.
+ * Solver functions
+ *
+ * Each solver is required to set up this struct contained in the plugin
+ * environment struct in during startup
  */
 struct GNUNET_ATS_SolverFunctions
 {
 
   /**
-   * Closure for all of the callbacks.
+   * Add a new address for a peer to the solver
+   *
+   * The address is already contained in the addresses hashmap!
    */
-  void *cls;
+  GAS_solver_address_add s_add;
 
+
   /**
-   * Add an address to the solver
+   * Update the properties of an address in the solver
    */
-  GAS_solver_address_add s_add;
-
   GAS_solver_address_property_changed s_address_update_property;
 
+
+  /**
+   * Update the session of an address in the solver
+   */
   GAS_solver_address_session_changed s_address_update_session;
 
+
+  /**
+   * Notify the solver that in address is (not) actively used by transport
+   * to communicate with a remote peer
+   */
   GAS_solver_address_inuse_changed s_address_update_inuse;
 
+
+  /**
+   * Notify solver that the network an address is located in has changed
+   */
   GAS_solver_address_network_changed s_address_update_network;
 
   /**
-   * Get address from solver
+   * Tell solver to notify ATS if the address to use changes for a specific
+   * peer using the bandwidth changed callback
+   *
+   * The solver must only notify about changes for peers with pending address
+   * requests!
    */
   GAS_solver_get_preferred_address s_get;
 
   /**
-   * Get address from solver
-   */
+  * Tell solver stop notifying ATS about changes for this peers
+  *
+  * The solver must only notify about changes for peers with pending address
+  * requests!
+  */
   GAS_solver_stop_get_preferred_address s_get_stop;
 
+
   /**
-   * Delete address in solver
+   * Delete an address in the solver
+   *
+   * The address is not contained in the address hashmap anymore!
    */
   GAS_solver_address_delete s_del;
 
+
   /**
    * Change relative preference for quality in solver
    */
   GAS_solver_address_change_preference s_pref;
 
+
   /**
    * Give feedback about the current assignment
    */
   GAS_solver_address_feedback_preference s_feedback;
 
+
   /**
    * Start a bulk operation
+   *
+   * Used if many values have to be updated at the same time.
+   * When a bulk operation is pending the solver does not have to resolve
+   * the problem since more updates will follow anyway
+   *
+   * For each call to bulk_start, a call to bulk_stop is required!
    */
   GAS_solver_bulk_start s_bulk_start;
 
+
   /**
    * Bulk operation done
+   *
+   * If no more bulk operations are pending, the solver can solve the problem
+   * with the updated values
    */
   GAS_solver_bulk_stop s_bulk_stop;
-
 };
 
 
@@ -298,12 +336,6 @@
 struct GNUNET_ATS_PluginEnvironment
 {
   /**
-   * Closure for the various callbacks.
-   */
-  void *cls;
-
-
-  /**
    * Configuration handle to be used by the solver
    */
   const struct GNUNET_CONFIGURATION_Handle *cfg;
@@ -344,10 +376,11 @@
    */
   void *get_preference_cls;
 
+
   /**
    * ATS addresses function to obtain property values
    */
-  GAS_get_properties get_property_cb;
+  GAS_get_properties get_property;
 
 
   /**