*/
/**
- * @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.
struct ATS_Address;
-
/*
* Solver API
* ----------
*/
-
/**
* Change the preference for a peer
*
(*GAS_solver_stop_get_preferred_address) (void *solver,
const struct GNUNET_PeerIdentity *peer);
-
/**
- * 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;
/**
* 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
+ *
+ * Order of calls is expected to be:
+ * GAS_OP_SOLVE_START
+ *
+ * GAS_OP_SOLVE_STOP
+ * GAS_OP_SOLVE_UPDATE_NOTIFICATION_START
+ * GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP
+ *
+ */
+enum GAS_Solver_Operation
+{
+ /**
+ * A solution iteration has been started
+ */
+ GAS_OP_SOLVE_START,
+
+ /**
+ * A solution iteration has been finished
+ */
+ GAS_OP_SOLVE_STOP,
+
+ /**
+ * The setup of the problem as a preparation to solve it was started
+ */
+ GAS_OP_SOLVE_SETUP_START,
+
+ /**
+ * The setup of the problem as a preparation to solve is finished
+ */
+ GAS_OP_SOLVE_SETUP_STOP,
+
+ /**
+ * Solving of the LP problem was started
+ * MLP solver only
+ */
+ GAS_OP_SOLVE_MLP_LP_START,
+
+ /**
+ * Solving of the LP problem is done
+ * MLP solver only
+ */
+ GAS_OP_SOLVE_MLP_LP_STOP,
+
+ /**
+ * Solving of the MLP problem was started
+ * MLP solver only
+ */
+ GAS_OP_SOLVE_MLP_MLP_START,
+ /**
+ * Solving of the MLP problem is done
+ * MLP solver only
+ */
+ GAS_OP_SOLVE_MLP_MLP_STOP,
+
+ /**
+ * After the problem was finished, start notifications about changes
+ * to addresses
+ */
+ GAS_OP_SOLVE_UPDATE_NOTIFICATION_START,
+
+ /**
+ * After the problem was finished, notifications about changes to addresses
+ * are done
+ */
+ GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP
};
+/**
+ * Status of a GAS_Solver_Operation operation
+ */
+enum GAS_Solver_Status
+{
+ /**
+ * Success
+ */
+ GAS_STAT_SUCCESS,
+
+ /**
+ * Failure
+ */
+ GAS_STAT_FAIL
+};
+
+/**
+ * Status of the operation
+ */
+enum GAS_Solver_Additional_Information
+{
+ /**
+ * No more specific information
+ */
+ GAS_INFO_NONE,
+
+ /**
+ * A full solution process is performed
+ * Quite specific to the MLP solver
+ */
+ GAS_INFO_FULL,
+
+ /**
+ * An existing solution was reused
+ * Quite specific to the MLP solver
+ */
+ GAS_INFO_UPDATED,
+
+ /**
+ * The proportional solver had to recalculate for a single network
+ */
+ GAS_INFO_PROP_SINGLE,
+
+ /**
+ * The proportional solver had to recalculate for all networks
+ */
+ GAS_INFO_PROP_ALL
+};
+
+/**
+ * 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
typedef const double *
(*GAS_get_properties) (void *cls, const struct ATS_Address *address);
-
/**
* The ATS service will pass a pointer to a struct
* of this type as the first and only argument to the
*/
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;
-
/**
* Statistics handle to be used by the solver
*/
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;
-
/**
* ATS addresses function to obtain preference values
*/
GAS_get_preferences get_preferences;
-
/**
* ATS addresses function closure to obtain preference values
*/
/**
* ATS addresses function to obtain property values
*/
- GAS_get_properties get_property_cb;
-
+ 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;
-
/**
* 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
projects / oweals / gnunet.git / blobdiff