/*
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
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
#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
*/
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
* @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
typedef void
(*GAS_solver_bulk_start) (void *solver);
+
/**
* Mark a bulk operation as done
* Solver will resolve if values have changed
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);
-
-/**
- * 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);
+ 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);
/**
- * 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 and return an instance
+ * of this struct during initialization.
*/
struct GNUNET_ATS_SolverFunctions
{
/**
- * Closure for all of the callbacks.
+ * Closure to pass to all solver functions in this struct.
*/
void *cls;
/**
- * Add an address to the solver
+ * Add a new address for a peer to the solver
+ *
+ * The address is already contained in the addresses hashmap!
*/
GAS_solver_address_add s_add;
+ /**
+ * Update the properties of an address in the solver
+ */
GAS_solver_address_property_changed s_address_update_property;
- GAS_solver_address_session_changed s_address_update_session;
-
- GAS_solver_address_inuse_changed s_address_update_inuse;
-
- 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
+ */
+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
* 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 transport 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.
+ * 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
{
/**
- * 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
+ */
+ struct GNUNET_STATISTICS_Handle *stats;
+
+ /**
+ * Closure to pass to all callbacks in this struct.
*/
void *cls;
- GAS_bandwidth_changed_cb bandwidth_changed_cb;
- void *bw_changed_cb_cls;
+ /**
+ * Hashmap containing all addresses available
+ */
+ struct GNUNET_CONTAINER_MultiPeerMap *addresses;
- GAS_get_preferences get_preferences_cb;
- void *get_preference_cls;
+ /**
+ * ATS addresses callback to be notified about bandwidth assignment changes
+ */
+ GAS_bandwidth_changed_cb bandwidth_changed_cb;
- GAS_get_properties get_property_cb;
- void *get_property_cls;
+ /**
+ * ATS addresses function to obtain preference values
+ */
+ GAS_get_preferences get_preferences;
- struct GNUNET_ATS_SolverFunctions sf;
+ /**
+ * ATS addresses function to obtain preference values
+ */
+ GAS_get_connectivity get_connectivity;
- struct GNUNET_CONFIGURATION_Handle *cfg;
- struct GNUNET_STATISTICS_Handle *stats;
- struct GNUNET_CONTAINER_MultiPeerMap *addresses;
+ /**
+ * Callback for solver to call with status information,
+ * can be NULL
+ */
+ GAS_solver_information_callback info_cb;
- /* Available networks */
- int networks[GNUNET_ATS_NetworkTypeCount];
- int network_count;
+ /**
+ * Number of networks available, size of the @e out_quota
+ * and @e in_quota arrays.
+ */
+ unsigned 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];
};
#endif
+
+/** @} */ /* end of group */
projects / oweals / gnunet.git / blobdiff