From 605667faf9a8907486221f3f789ef0e1e81f5132 Mon Sep 17 00:00:00 2001 From: Matthias Wachs Date: Thu, 7 Nov 2013 09:49:16 +0000 Subject: [PATCH] extend info cb and documentation --- src/include/gnunet_ats_plugin.h | 143 ++++++++++++++++++++++---------- 1 file changed, 97 insertions(+), 46 deletions(-) diff --git a/src/include/gnunet_ats_plugin.h b/src/include/gnunet_ats_plugin.h index ed081f39a..15c3ebbf4 100644 --- a/src/include/gnunet_ats_plugin.h +++ b/src/include/gnunet_ats_plugin.h @@ -36,13 +36,11 @@ struct ATS_Address; - /* * Solver API * ---------- */ - /** * Change the preference for a peer * @@ -193,7 +191,6 @@ typedef void (*GAS_solver_stop_get_preferred_address) (void *solver, const struct GNUNET_PeerIdentity *peer); - /** * Solver functions * @@ -210,26 +207,22 @@ struct GNUNET_ATS_SolverFunctions */ GAS_solver_address_add s_add; - /** * Update the properties of an address in the solver */ 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 */ @@ -245,14 +238,13 @@ struct GNUNET_ATS_SolverFunctions GAS_solver_get_preferred_address s_get; /** - * Tell solver stop notifying ATS about changes for this peers - * - * The solver must only notify about changes for peers with pending address - * requests! - */ + * 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 an address in the solver * @@ -260,19 +252,16 @@ struct GNUNET_ATS_SolverFunctions */ 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 * @@ -284,7 +273,6 @@ struct GNUNET_ATS_SolverFunctions */ GAS_solver_bulk_start s_bulk_start; - /** * Bulk operation done * @@ -294,29 +282,89 @@ struct GNUNET_ATS_SolverFunctions 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, - GAS_OP_SOLVE_LP_START, - GAS_OP_SOLVE_LP_STOP, - GAS_OP_SOLVE_MLP_START, - GAS_OP_SOLVE_MLP_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 the operation + * Status of a GAS_Solver_Operation operation */ enum GAS_Solver_Status { + /** + * Success + */ GAS_STAT_SUCCESS, + + /** + * Failure + */ GAS_STAT_FAIL }; @@ -325,13 +373,33 @@ enum GAS_Solver_Status */ 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, - GAS_INFO_PROP_ALL, - GAS_INFO_PROP_SINGLE -}; + /** + * 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 @@ -345,11 +413,8 @@ enum GAS_Solver_Additional_Information * @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); - +(*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 @@ -383,7 +448,6 @@ typedef const double * 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 @@ -396,55 +460,46 @@ struct GNUNET_ATS_PluginEnvironment */ 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 */ void *get_preference_cls; - /** * 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 @@ -462,26 +517,22 @@ struct GNUNET_ATS_PluginEnvironment */ 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 -- 2.25.1