X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_ats_plugin.h;h=27f4a6f0f36f89d432b929949af29516598a75cf;hb=7a7ec54a324da4820202582126795a8ac6bbe94d;hp=02875a07076a2467440884e95bb0ec9413e953dd;hpb=15dd8e6cc1199d611d804853e134882bf13b234a;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_ats_plugin.h b/src/include/gnunet_ats_plugin.h index 02875a070..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_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. - * 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,12 +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 @@ -53,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 @@ -67,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 @@ -81,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 @@ -90,104 +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); -/** - * 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 * @@ -200,16 +183,6 @@ struct GNUNET_ATS_SolverFunctions */ 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 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 @@ -264,15 +237,15 @@ 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 + * #GAS_OP_SOLVE_START + * #GAS_OP_SOLVE_STOP + * #GAS_OP_SOLVE_UPDATE_NOTIFICATION_START + * #GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP * */ enum GAS_Solver_Operation @@ -334,6 +307,7 @@ enum GAS_Solver_Operation GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP }; + /** * Status of a GAS_Solver_Operation operation */ @@ -350,6 +324,7 @@ enum GAS_Solver_Status GAS_STAT_FAIL }; + /** * Status of the operation */ @@ -383,20 +358,20 @@ enum GAS_Solver_Additional_Information 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); +(*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 @@ -404,11 +379,13 @@ typedef void * @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 @@ -416,24 +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 { @@ -445,7 +426,12 @@ struct GNUNET_ATS_PluginEnvironment /** * 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 @@ -457,30 +443,15 @@ struct GNUNET_ATS_PluginEnvironment */ 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 + * ATS addresses function to obtain preference values */ - void *get_property_cls; + GAS_get_connectivity get_connectivity; /** * Callback for solver to call with status information, @@ -489,25 +460,10 @@ struct GNUNET_ATS_PluginEnvironment GAS_solver_information_callback info_cb; /** - * Closure for information callback, - * can be NULL + * Number of networks available, size of the @e out_quota + * and @e in_quota arrays. */ - 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; + unsigned int network_count; /** * Array of configured outbound quotas @@ -523,3 +479,5 @@ struct GNUNET_ATS_PluginEnvironment }; #endif + +/** @} */ /* end of group */