*/
/**
- * @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
*
/**
- * The transport service will pass a pointer to a struct
+ * The ATS service will pass a pointer to a struct
* of this type as the first and only argument to the
- * entry point of each transport plugin.
+ * entry point of each ATS solver.
*/
struct GNUNET_ATS_PluginEnvironment
{
/**
- * Closure for the various callbacks.
+ * Configuration handle to be used by the solver
+ */
+ const struct GNUNET_CONFIGURATION_Handle *cfg;
+
+
+ /**
+ * Statistics handle to be used by the solver
*/
- void *cls;
+ const struct GNUNET_STATISTICS_Handle *stats;
+
+ /**
+ * Hashmap containing all addresses available
+ */
+ struct GNUNET_CONTAINER_MultiPeerMap *addresses;
+
+
+ /**
+ * ATS addresses callback to be notified about bandwidth assignment changes
+ */
GAS_bandwidth_changed_cb bandwidth_changed_cb;
+
+
+ /**
+ * ATS addresses closure to be notified about bandwidth assignment changes
+ */
void *bw_changed_cb_cls;
- GAS_get_preferences get_preferences_cb;
+
+ /**
+ * ATS addresses function to obtain preference values
+ */
+ GAS_get_preferences get_preferences;
+
+
+ /**
+ * ATS addresses function closure to obtain preference values
+ */
void *get_preference_cls;
- GAS_get_properties get_property_cb;
+
+ /**
+ * ATS addresses function to obtain property values
+ */
+ GAS_get_properties get_property;
+
+
+ /**
+ * ATS addresses function closure to obtain property values
+ */
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
+ */
struct GNUNET_ATS_SolverFunctions sf;
- struct GNUNET_CONFIGURATION_Handle *cfg;
- struct GNUNET_STATISTICS_Handle *stats;
- struct GNUNET_CONTAINER_MultiPeerMap *addresses;
- /* Available networks */
+ /**
+ * Available networks
+ */
int networks[GNUNET_ATS_NetworkTypeCount];
+
+
+ /**
+ * Number of networks available
+ */
int network_count;
+
+ /**
+ * Array of configured outbound quotas
+ * Order according to networks in network array
+ */
unsigned long long out_quota[GNUNET_ATS_NetworkTypeCount];
+
+
+ /**
+ * Array of configured inbound quotas
+ * Order according to networks in network array
+ */
unsigned long long in_quota[GNUNET_ATS_NetworkTypeCount];
};
projects / oweals / gnunet.git / blobdiff