X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_ats_plugin.h;h=27f4a6f0f36f89d432b929949af29516598a75cf;hb=7eb7bd8666aeb2e855cd22b1ea7f44b87bb60400;hp=fe333399b437bfb2653632bc26d872cb7555a8f5;hpb=4d37bf113ef8e56aa9b50d6b140b0488a5ae6717;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_ats_plugin.h b/src/include/gnunet_ats_plugin.h index fe333399b..27f4a6f0f 100644 --- a/src/include/gnunet_ats_plugin.h +++ b/src/include/gnunet_ats_plugin.h @@ -1,6 +1,6 @@ /* This file is part of GNUnet - (C) 2009, 2010 Christian Grothoff (and other contributing authors) + Copyright (C) 2009-2015 GNUnet e.V. GNUnet is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published @@ -14,19 +14,25 @@ You should have received a copy of the GNU General Public License along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. + Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. */ /** - * @file include/gnunet_solver_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. - * Note that the destructors of ATS plugins will - * be given the value returned by the constructor - * and is expected to return a NULL pointer. * @author Christian Grothoff + * + * @file + * API for the ATS solvers. + * + * @defgroup ats-plugin ATS service plugin API + * Plugin API for the ATS service. + * + * Specifies the struct that is given to the plugin's entry method and the other + * struct that must be returned. Note that the destructors of ATS plugins will + * be given the value returned by the constructor and is expected to return a + * NULL pointer. + * + * @{ */ #ifndef PLUGIN_ATS_H #define PLUGIN_ATS_H @@ -34,14 +40,10 @@ #include "gnunet_ats_service.h" #include "gnunet_statistics_service.h" -struct ATS_Address; - - -/* - * Solver API - * ---------- +/** + * Representation of an address the plugin can choose from. */ - +struct ATS_Address; /** * Change the preference for a peer @@ -55,8 +57,10 @@ struct ATS_Address; */ typedef void (*GAS_solver_address_change_preference) (void *solver, - const struct GNUNET_PeerIdentity *peer, enum GNUNET_ATS_PreferenceKind kind, - double pref_rel); + const struct GNUNET_PeerIdentity *peer, + enum GNUNET_ATS_PreferenceKind kind, + double pref_rel); + /** * Give feedback about the current assignment @@ -69,10 +73,12 @@ typedef void * @param score the feedback score */ typedef void -(*GAS_solver_address_feedback_preference) (void *solver, void *application, - const struct GNUNET_PeerIdentity *peer, - const struct GNUNET_TIME_Relative scope, - enum GNUNET_ATS_PreferenceKind kind, double score); +(*GAS_solver_address_feedback_preference) (void *solver, + struct GNUNET_SERVICE_Client *application, + const struct GNUNET_PeerIdentity *peer, + const struct GNUNET_TIME_Relative scope, + enum GNUNET_ATS_PreferenceKind kind, + double score); /** * Notify the solver about a bulk operation changing possibly a lot of values @@ -83,6 +89,7 @@ typedef void typedef void (*GAS_solver_bulk_start) (void *solver); + /** * Mark a bulk operation as done * Solver will resolve if values have changed @@ -92,117 +99,78 @@ typedef void typedef void (*GAS_solver_bulk_stop) (void *solver); + /** * Add a single address within a network to the solver * * @param solver the solver Handle - * @param addresses the address hashmap containing all addresses * @param address the address to add * @param network network type of this address */ typedef void -(*GAS_solver_address_add) (void *solver, struct ATS_Address *address, - uint32_t network); +(*GAS_solver_address_add) (void *solver, + struct ATS_Address *address, + uint32_t network); + /** * Delete an address or just the session from the solver * * @param solver the solver Handle - * @param addresses the address hashmap containing all addresses * @param address the address to delete - * @param session_only remove address or just session */ typedef void -(*GAS_solver_address_delete) (void *solver, struct ATS_Address *address, - int session_only); +(*GAS_solver_address_delete) (void *solver, + struct ATS_Address *address); + /** * Transport properties for this address have changed * * @param solver solver handle * @param address the address - * @param type the ATSI type in HBO - * @param abs_value the absolute value of the property - * @param rel_value the normalized value */ typedef void (*GAS_solver_address_property_changed) (void *solver, - struct ATS_Address *address, uint32_t type, uint32_t abs_value, - double rel_value); - -/** - * Transport session for this address has changed - * - * NOTE: values in addresses are already updated - * - * @param solver solver handle - * @param address the address - * @param cur_session the current session - * @param new_session the new session - */ -typedef void -(*GAS_solver_address_session_changed) (void *solver, - struct ATS_Address *address, uint32_t cur_session, uint32_t new_session); + struct ATS_Address *address); -/** - * Transport session for this address has changed - * - * NOTE: values in addresses are already updated - * - * @param solver solver handle - * @param address the address - * @param in_use usage state - */ -typedef void -(*GAS_solver_address_inuse_changed) (void *solver, struct ATS_Address *address, - int in_use); - -/** - * Network scope for this address has changed - * - * NOTE: values in addresses are already updated - * - * @param solver solver handle - * @param address the address - * @param current_network the current network - * @param new_network the new network - */ -typedef void -(*GAS_solver_address_network_changed) (void *solver, - struct ATS_Address *address, uint32_t current_network, uint32_t new_network); /** * Get the prefered address for a peer from solver * * @param solver the solver to use - * @param addresses the address hashmap containing all addresses * @param peer the peer */ -typedef const struct ATS_Address * +typedef void (*GAS_solver_get_preferred_address) (void *solver, - const struct GNUNET_PeerIdentity *peer); + const struct GNUNET_PeerIdentity *peer); + /** * Stop getting the prefered address for a peer from solver * * @param solver the solver to use - * @param addresses the address hashmap containing all addresses * @param peer the peer */ typedef void (*GAS_solver_stop_get_preferred_address) (void *solver, - const struct GNUNET_PeerIdentity *peer); + const struct GNUNET_PeerIdentity *peer); /** - * Solver functions + * Solver functions. * - * Each solver is required to set up this struct contained in the plugin - * environment struct in during startup + * Each solver is required to set up and return an instance + * of this struct during initialization. */ struct GNUNET_ATS_SolverFunctions { + /** + * Closure to pass to all solver functions in this struct. + */ + void *cls; + /** * Add a new address for a peer to the solver * @@ -210,31 +178,11 @@ 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 - */ - GAS_solver_address_network_changed s_address_update_network; - /** * Tell solver to notify ATS if the address to use changes for a specific * peer using the bandwidth changed callback @@ -245,14 +193,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 +207,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 +228,6 @@ struct GNUNET_ATS_SolverFunctions */ GAS_solver_bulk_start s_bulk_start; - /** * Bulk operation done * @@ -295,17 +238,154 @@ struct GNUNET_ATS_SolverFunctions }; +/** + * 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 + */ +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 * * @param address the with changed bandwidth assigned */ typedef void -(*GAS_bandwidth_changed_cb) (void *cls, struct ATS_Address *address); +(*GAS_bandwidth_changed_cb) (void *cls, + struct ATS_Address *address); + /** - * Callback to call from solver to obtain application preference values for a - * peer + * Callback to call from solver to obtain application preference + * values for a peer. * * @param cls the cls * @param id the peer id @@ -313,25 +393,28 @@ typedef void * GNUNET_ATS_PreferenceCount elements */ typedef const double * -(*GAS_get_preferences) (void *cls, const struct GNUNET_PeerIdentity *id); +(*GAS_get_preferences) (void *cls, + const struct GNUNET_PeerIdentity *id); + /** - * Callback to call from solver to obtain transport properties for an - * address + * Callback to call from solver to obtain application connectivity + * preferences for a peer. * * @param cls the cls - * @param address the address - * @return carry of double values containing the preferences with - * GNUNET_ATS_PreferenceCount elements + * @param id the peer id + * @return 0 if connectivity is not desired, non-null if address + * suggestions are requested */ -typedef const double * -(*GAS_get_properties) (void *cls, const struct ATS_Address *address); +typedef unsigned int +(*GAS_get_connectivity) (void *cls, + const struct GNUNET_PeerIdentity *id); /** - * 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 ATS solver. + * The ATS plugin will pass a pointer to a struct + * of this type as to the initialization function + * of the ATS plugins. */ struct GNUNET_ATS_PluginEnvironment { @@ -340,72 +423,47 @@ struct GNUNET_ATS_PluginEnvironment */ const struct GNUNET_CONFIGURATION_Handle *cfg; - /** * Statistics handle to be used by the solver */ - const struct GNUNET_STATISTICS_Handle *stats; + struct GNUNET_STATISTICS_Handle *stats; + /** + * Closure to pass to all callbacks in this struct. + */ + void *cls; /** * 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; - - - /** - * The ATS solver plugin functions to call + * ATS addresses function to obtain preference values */ - struct GNUNET_ATS_SolverFunctions sf; - + GAS_get_connectivity get_connectivity; /** - * Available networks + * Callback for solver to call with status information, + * can be NULL */ - int networks[GNUNET_ATS_NetworkTypeCount]; - + GAS_solver_information_callback info_cb; /** - * Number of networks available + * Number of networks available, size of the @e out_quota + * and @e in_quota arrays. */ - int network_count; - + unsigned int network_count; /** * Array of configured outbound quotas @@ -413,7 +471,6 @@ struct GNUNET_ATS_PluginEnvironment */ unsigned long long out_quota[GNUNET_ATS_NetworkTypeCount]; - /** * Array of configured inbound quotas * Order according to networks in network array @@ -422,3 +479,5 @@ struct GNUNET_ATS_PluginEnvironment }; #endif + +/** @} */ /* end of group */