2 This file is part of GNUnet
3 Copyright (C) 2009-2015 GNUnet e.V.
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your option) any later version.
10 GNUnet is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Affero General Public License for more details.
15 You should have received a copy of the GNU Affero General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
20 * @author Christian Grothoff
23 * API for the ATS solvers.
25 * @defgroup ats-plugin ATS service plugin API
26 * Plugin API for the ATS service.
28 * Specifies the struct that is given to the plugin's entry method and the other
29 * struct that must be returned. Note that the destructors of ATS plugins will
30 * be given the value returned by the constructor and is expected to return a
38 #include "gnunet_ats_service.h"
39 #include "gnunet_statistics_service.h"
42 * Representation of an address the plugin can choose from.
47 * Change the preference for a peer
49 * @param handle the solver handle
50 * @param client the client sending this request
51 * @param peer the peer id
52 * @param kind the preference kind to change
53 * @param score the new preference score
54 * @param pref_rel the normalized preference value for this kind over all clients
57 (*GAS_solver_address_change_preference) (void *solver,
58 const struct GNUNET_PeerIdentity *peer,
59 enum GNUNET_ATS_PreferenceKind kind,
64 * Give feedback about the current assignment
66 * @param handle the solver handle
67 * @param application the application sending this request
68 * @param peer the peer id
69 * @param scope the time interval for this feedback: [now - scope .. now]
70 * @param kind the preference kind for this feedback
71 * @param score the feedback score
74 (*GAS_solver_address_feedback_preference) (void *solver,
75 struct GNUNET_SERVICE_Client *application,
76 const struct GNUNET_PeerIdentity *peer,
77 const struct GNUNET_TIME_Relative scope,
78 enum GNUNET_ATS_PreferenceKind kind,
82 * Notify the solver about a bulk operation changing possibly a lot of values
83 * Solver will not resolve until all bulk operations are marked as done
85 * @param solver the solver
88 (*GAS_solver_bulk_start) (void *solver);
92 * Mark a bulk operation as done
93 * Solver will resolve if values have changed
95 * @param solver the solver
98 (*GAS_solver_bulk_stop) (void *solver);
102 * Add a single address within a network to the solver
104 * @param solver the solver Handle
105 * @param address the address to add
106 * @param network network type of this address
109 (*GAS_solver_address_add) (void *solver,
110 struct ATS_Address *address,
115 * Delete an address or just the session from the solver
117 * @param solver the solver Handle
118 * @param address the address to delete
121 (*GAS_solver_address_delete) (void *solver,
122 struct ATS_Address *address);
126 * Transport properties for this address have changed
128 * @param solver solver handle
129 * @param address the address
132 (*GAS_solver_address_property_changed) (void *solver,
133 struct ATS_Address *address);
137 * Get the prefered address for a peer from solver
139 * @param solver the solver to use
140 * @param peer the peer
143 (*GAS_solver_get_preferred_address) (void *solver,
144 const struct GNUNET_PeerIdentity *peer);
148 * Stop getting the prefered address for a peer from solver
150 * @param solver the solver to use
151 * @param peer the peer
154 (*GAS_solver_stop_get_preferred_address) (void *solver,
155 const struct GNUNET_PeerIdentity *peer);
161 * Each solver is required to set up and return an instance
162 * of this struct during initialization.
164 struct GNUNET_ATS_SolverFunctions
168 * Closure to pass to all solver functions in this struct.
173 * Add a new address for a peer to the solver
175 * The address is already contained in the addresses hashmap!
177 GAS_solver_address_add s_add;
180 * Update the properties of an address in the solver
182 GAS_solver_address_property_changed s_address_update_property;
185 * Tell solver to notify ATS if the address to use changes for a specific
186 * peer using the bandwidth changed callback
188 * The solver must only notify about changes for peers with pending address
191 GAS_solver_get_preferred_address s_get;
194 * Tell solver stop notifying ATS about changes for this peers
196 * The solver must only notify about changes for peers with pending address
199 GAS_solver_stop_get_preferred_address s_get_stop;
202 * Delete an address in the solver
204 * The address is not contained in the address hashmap anymore!
206 GAS_solver_address_delete s_del;
209 * Change relative preference for quality in solver
211 GAS_solver_address_change_preference s_pref;
214 * Give feedback about the current assignment
216 GAS_solver_address_feedback_preference s_feedback;
219 * Start a bulk operation
221 * Used if many values have to be updated at the same time.
222 * When a bulk operation is pending the solver does not have to resolve
223 * the problem since more updates will follow anyway
225 * For each call to bulk_start, a call to bulk_stop is required!
227 GAS_solver_bulk_start s_bulk_start;
230 * Bulk operation done
232 * If no more bulk operations are pending, the solver can solve the problem
233 * with the updated values
235 GAS_solver_bulk_stop s_bulk_stop;
240 * Operation codes for solver information callback
242 * Order of calls is expected to be:
243 * #GAS_OP_SOLVE_START
245 * #GAS_OP_SOLVE_UPDATE_NOTIFICATION_START
246 * #GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP
249 enum GAS_Solver_Operation
252 * A solution iteration has been started
257 * A solution iteration has been finished
262 * The setup of the problem as a preparation to solve it was started
264 GAS_OP_SOLVE_SETUP_START,
267 * The setup of the problem as a preparation to solve is finished
269 GAS_OP_SOLVE_SETUP_STOP,
272 * Solving of the LP problem was started
275 GAS_OP_SOLVE_MLP_LP_START,
278 * Solving of the LP problem is done
281 GAS_OP_SOLVE_MLP_LP_STOP,
284 * Solving of the MLP problem was started
287 GAS_OP_SOLVE_MLP_MLP_START,
290 * Solving of the MLP problem is done
293 GAS_OP_SOLVE_MLP_MLP_STOP,
296 * After the problem was finished, start notifications about changes
299 GAS_OP_SOLVE_UPDATE_NOTIFICATION_START,
302 * After the problem was finished, notifications about changes to addresses
305 GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP
310 * Status of a GAS_Solver_Operation operation
312 enum GAS_Solver_Status
327 * Status of the operation
329 enum GAS_Solver_Additional_Information
332 * No more specific information
337 * A full solution process is performed
338 * Quite specific to the MLP solver
343 * An existing solution was reused
344 * Quite specific to the MLP solver
349 * The proportional solver had to recalculate for a single network
351 GAS_INFO_PROP_SINGLE,
354 * The proportional solver had to recalculate for all networks
361 * Callback to call with additional information
362 * Used for measurement
364 * @param cls the closure
365 * @param op the operation
368 (*GAS_solver_information_callback) (void *cls,
369 enum GAS_Solver_Operation op,
370 enum GAS_Solver_Status stat,
371 enum GAS_Solver_Additional_Information);
375 * Callback to call from solver when bandwidth for address has changed
377 * @param address the with changed bandwidth assigned
380 (*GAS_bandwidth_changed_cb) (void *cls,
381 struct ATS_Address *address);
385 * Callback to call from solver to obtain application preference
389 * @param id the peer id
390 * @return carry of double values containing the preferences with
391 * GNUNET_ATS_PreferenceCount elements
393 typedef const double *
394 (*GAS_get_preferences) (void *cls,
395 const struct GNUNET_PeerIdentity *id);
399 * Callback to call from solver to obtain application connectivity
400 * preferences for a peer.
403 * @param id the peer id
404 * @return 0 if connectivity is not desired, non-null if address
405 * suggestions are requested
408 (*GAS_get_connectivity) (void *cls,
409 const struct GNUNET_PeerIdentity *id);
413 * The ATS plugin will pass a pointer to a struct
414 * of this type as to the initialization function
415 * of the ATS plugins.
417 struct GNUNET_ATS_PluginEnvironment
420 * Configuration handle to be used by the solver
422 const struct GNUNET_CONFIGURATION_Handle *cfg;
425 * Statistics handle to be used by the solver
427 struct GNUNET_STATISTICS_Handle *stats;
430 * Closure to pass to all callbacks in this struct.
435 * Hashmap containing all addresses available
437 struct GNUNET_CONTAINER_MultiPeerMap *addresses;
440 * ATS addresses callback to be notified about bandwidth assignment changes
442 GAS_bandwidth_changed_cb bandwidth_changed_cb;
445 * ATS addresses function to obtain preference values
447 GAS_get_preferences get_preferences;
450 * ATS addresses function to obtain preference values
452 GAS_get_connectivity get_connectivity;
455 * Callback for solver to call with status information,
458 GAS_solver_information_callback info_cb;
461 * Number of networks available, size of the @e out_quota
462 * and @e in_quota arrays.
464 unsigned int network_count;
467 * Array of configured outbound quotas
468 * Order according to networks in network array
470 unsigned long long out_quota[GNUNET_ATS_NetworkTypeCount];
473 * Array of configured inbound quotas
474 * Order according to networks in network array
476 unsigned long long in_quota[GNUNET_ATS_NetworkTypeCount];
481 /** @} */ /* end of group */