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
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 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 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
22 * @author Christian Grothoff
25 * API for the ATS solvers.
27 * @defgroup ats-plugin ATS service plugin API
28 * Plugin API for the ATS service.
30 * Specifies the struct that is given to the plugin's entry method and the other
31 * struct that must be returned. Note that the destructors of ATS plugins will
32 * be given the value returned by the constructor and is expected to return a
40 #include "gnunet_ats_service.h"
41 #include "gnunet_statistics_service.h"
44 * Representation of an address the plugin can choose from.
49 * Change the preference for a peer
51 * @param handle the solver handle
52 * @param client the client sending this request
53 * @param peer the peer id
54 * @param kind the preference kind to change
55 * @param score the new preference score
56 * @param pref_rel the normalized preference value for this kind over all clients
59 (*GAS_solver_address_change_preference) (void *solver,
60 const struct GNUNET_PeerIdentity *peer,
61 enum GNUNET_ATS_PreferenceKind kind,
66 * Give feedback about the current assignment
68 * @param handle the solver handle
69 * @param application the application sending this request
70 * @param peer the peer id
71 * @param scope the time interval for this feedback: [now - scope .. now]
72 * @param kind the preference kind for this feedback
73 * @param score the feedback score
76 (*GAS_solver_address_feedback_preference) (void *solver,
77 struct GNUNET_SERVICE_Client *application,
78 const struct GNUNET_PeerIdentity *peer,
79 const struct GNUNET_TIME_Relative scope,
80 enum GNUNET_ATS_PreferenceKind kind,
84 * Notify the solver about a bulk operation changing possibly a lot of values
85 * Solver will not resolve until all bulk operations are marked as done
87 * @param solver the solver
90 (*GAS_solver_bulk_start) (void *solver);
94 * Mark a bulk operation as done
95 * Solver will resolve if values have changed
97 * @param solver the solver
100 (*GAS_solver_bulk_stop) (void *solver);
104 * Add a single address within a network to the solver
106 * @param solver the solver Handle
107 * @param address the address to add
108 * @param network network type of this address
111 (*GAS_solver_address_add) (void *solver,
112 struct ATS_Address *address,
117 * Delete an address or just the session from the solver
119 * @param solver the solver Handle
120 * @param address the address to delete
123 (*GAS_solver_address_delete) (void *solver,
124 struct ATS_Address *address);
128 * Transport properties for this address have changed
130 * @param solver solver handle
131 * @param address the address
134 (*GAS_solver_address_property_changed) (void *solver,
135 struct ATS_Address *address);
139 * Get the prefered address for a peer from solver
141 * @param solver the solver to use
142 * @param peer the peer
145 (*GAS_solver_get_preferred_address) (void *solver,
146 const struct GNUNET_PeerIdentity *peer);
150 * Stop getting the prefered address for a peer from solver
152 * @param solver the solver to use
153 * @param peer the peer
156 (*GAS_solver_stop_get_preferred_address) (void *solver,
157 const struct GNUNET_PeerIdentity *peer);
163 * Each solver is required to set up and return an instance
164 * of this struct during initialization.
166 struct GNUNET_ATS_SolverFunctions
170 * Closure to pass to all solver functions in this struct.
175 * Add a new address for a peer to the solver
177 * The address is already contained in the addresses hashmap!
179 GAS_solver_address_add s_add;
182 * Update the properties of an address in the solver
184 GAS_solver_address_property_changed s_address_update_property;
187 * Tell solver to notify ATS if the address to use changes for a specific
188 * peer using the bandwidth changed callback
190 * The solver must only notify about changes for peers with pending address
193 GAS_solver_get_preferred_address s_get;
196 * Tell solver stop notifying ATS about changes for this peers
198 * The solver must only notify about changes for peers with pending address
201 GAS_solver_stop_get_preferred_address s_get_stop;
204 * Delete an address in the solver
206 * The address is not contained in the address hashmap anymore!
208 GAS_solver_address_delete s_del;
211 * Change relative preference for quality in solver
213 GAS_solver_address_change_preference s_pref;
216 * Give feedback about the current assignment
218 GAS_solver_address_feedback_preference s_feedback;
221 * Start a bulk operation
223 * Used if many values have to be updated at the same time.
224 * When a bulk operation is pending the solver does not have to resolve
225 * the problem since more updates will follow anyway
227 * For each call to bulk_start, a call to bulk_stop is required!
229 GAS_solver_bulk_start s_bulk_start;
232 * Bulk operation done
234 * If no more bulk operations are pending, the solver can solve the problem
235 * with the updated values
237 GAS_solver_bulk_stop s_bulk_stop;
242 * Operation codes for solver information callback
244 * Order of calls is expected to be:
245 * #GAS_OP_SOLVE_START
247 * #GAS_OP_SOLVE_UPDATE_NOTIFICATION_START
248 * #GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP
251 enum GAS_Solver_Operation
254 * A solution iteration has been started
259 * A solution iteration has been finished
264 * The setup of the problem as a preparation to solve it was started
266 GAS_OP_SOLVE_SETUP_START,
269 * The setup of the problem as a preparation to solve is finished
271 GAS_OP_SOLVE_SETUP_STOP,
274 * Solving of the LP problem was started
277 GAS_OP_SOLVE_MLP_LP_START,
280 * Solving of the LP problem is done
283 GAS_OP_SOLVE_MLP_LP_STOP,
286 * Solving of the MLP problem was started
289 GAS_OP_SOLVE_MLP_MLP_START,
292 * Solving of the MLP problem is done
295 GAS_OP_SOLVE_MLP_MLP_STOP,
298 * After the problem was finished, start notifications about changes
301 GAS_OP_SOLVE_UPDATE_NOTIFICATION_START,
304 * After the problem was finished, notifications about changes to addresses
307 GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP
312 * Status of a GAS_Solver_Operation operation
314 enum GAS_Solver_Status
329 * Status of the operation
331 enum GAS_Solver_Additional_Information
334 * No more specific information
339 * A full solution process is performed
340 * Quite specific to the MLP solver
345 * An existing solution was reused
346 * Quite specific to the MLP solver
351 * The proportional solver had to recalculate for a single network
353 GAS_INFO_PROP_SINGLE,
356 * The proportional solver had to recalculate for all networks
363 * Callback to call with additional information
364 * Used for measurement
366 * @param cls the closure
367 * @param op the operation
370 (*GAS_solver_information_callback) (void *cls,
371 enum GAS_Solver_Operation op,
372 enum GAS_Solver_Status stat,
373 enum GAS_Solver_Additional_Information);
377 * Callback to call from solver when bandwidth for address has changed
379 * @param address the with changed bandwidth assigned
382 (*GAS_bandwidth_changed_cb) (void *cls,
383 struct ATS_Address *address);
387 * Callback to call from solver to obtain application preference
391 * @param id the peer id
392 * @return carry of double values containing the preferences with
393 * GNUNET_ATS_PreferenceCount elements
395 typedef const double *
396 (*GAS_get_preferences) (void *cls,
397 const struct GNUNET_PeerIdentity *id);
401 * Callback to call from solver to obtain application connectivity
402 * preferences for a peer.
405 * @param id the peer id
406 * @return 0 if connectivity is not desired, non-null if address
407 * suggestions are requested
410 (*GAS_get_connectivity) (void *cls,
411 const struct GNUNET_PeerIdentity *id);
415 * The ATS plugin will pass a pointer to a struct
416 * of this type as to the initialization function
417 * of the ATS plugins.
419 struct GNUNET_ATS_PluginEnvironment
422 * Configuration handle to be used by the solver
424 const struct GNUNET_CONFIGURATION_Handle *cfg;
427 * Statistics handle to be used by the solver
429 struct GNUNET_STATISTICS_Handle *stats;
432 * Closure to pass to all callbacks in this struct.
437 * Hashmap containing all addresses available
439 struct GNUNET_CONTAINER_MultiPeerMap *addresses;
442 * ATS addresses callback to be notified about bandwidth assignment changes
444 GAS_bandwidth_changed_cb bandwidth_changed_cb;
447 * ATS addresses function to obtain preference values
449 GAS_get_preferences get_preferences;
452 * ATS addresses function to obtain preference values
454 GAS_get_connectivity get_connectivity;
457 * Callback for solver to call with status information,
460 GAS_solver_information_callback info_cb;
463 * Number of networks available, size of the @e out_quota
464 * and @e in_quota arrays.
466 unsigned int network_count;
469 * Array of configured outbound quotas
470 * Order according to networks in network array
472 unsigned long long out_quota[GNUNET_ATS_NetworkTypeCount];
475 * Array of configured inbound quotas
476 * Order according to networks in network array
478 unsigned long long in_quota[GNUNET_ATS_NetworkTypeCount];
483 /** @} */ /* end of group */