*/
/**
- * @file include/gnunet_solver_plugin.h
+ * @file include/gnunet_ats_plugin.h
* @brief API for the ATS solvers. This header
* specifies the struct that is given to the plugin's entry
* method and the other struct that must be returned.
/**
- * 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;
+};
+
+/**
+ * Operation codes for solver information callback
+ */
+enum GAS_Solver_Operation
+{
+ GAS_OP_SOLVE_START,
+ GAS_OP_SOLVE_STOP,
+ GAS_OP_SOLVE_SETUP_START,
+ GAS_OP_SOLVE_SETUP_STOP,
+ GAS_OP_SOLVE_LP_START,
+ GAS_OP_SOLVE_LP_STOP,
+ GAS_OP_SOLVE_MLP_START,
+ GAS_OP_SOLVE_MLP_STOP
};
+/**
+ * Status of the operation
+ */
+enum GAS_Solver_Status
+{
+ GAS_STAT_SUCCESS,
+ GAS_STAT_FAIL
+};
+
+/**
+ * Status of the operation
+ */
+enum GAS_Solver_Additional_Information
+{
+ GAS_INFO_NONE,
+ GAS_INFO_FULL,
+ GAS_INFO_UPDATED,
+ GAS_INFO_PROP_ALL,
+ GAS_INFO_PROP_SINGLE
+};
+
+
+/**
+ * Callback to call with additional information
+ * Used for measurement
+ *
+ * @param cls the closure
+ * @param op the operation
+ * @param peer the peer id
+ * @param kind the preference kind to change
+ * @param score the new preference score
+ * @param pref_rel the normalized preference value for this kind over all clients
+ */
+typedef void
+(*GAS_solver_information_callback) (void *cls,
+ enum GAS_Solver_Operation op,
+ enum GAS_Solver_Status stat,
+ enum GAS_Solver_Additional_Information);
+
+
/**
* Callback to call from solver when bandwidth for address has changed
*
*/
struct GNUNET_ATS_PluginEnvironment
{
- /**
- * Closure for the various callbacks.
- */
- void *cls;
-
-
/**
* Configuration handle to be used by the solver
*/
*/
void *get_preference_cls;
+
/**
* ATS addresses function to obtain property values
*/
- GAS_get_properties get_property_cb;
+ GAS_get_properties get_property;
/**
void *get_property_cls;
+ /**
+ * Callback for solver to call with status information,
+ * can be NULL
+ */
+ GAS_solver_information_callback info_cb;
+
+ /**
+ * Closure for information callback,
+ * can be NULL
+ */
+ void *info_cb_cls;
+
/**
* The ATS solver plugin functions to call
*/