2 This file is part of GNUnet
3 (C) 2009, 2010 Christian Grothoff (and other contributing authors)
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., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
22 * @file include/gnunet_ats_plugin.h
23 * @brief API for the ATS solvers. This header
24 * specifies the struct that is given to the plugin's entry
25 * method and the other struct that must be returned.
26 * Note that the destructors of ATS plugins will
27 * be given the value returned by the constructor
28 * and is expected to return a NULL pointer.
29 * @author Christian Grothoff
34 #include "gnunet_ats_service.h"
35 #include "gnunet_statistics_service.h"
45 * Change the preference for a peer
47 * @param handle the solver handle
48 * @param client the client sending this request
49 * @param peer the peer id
50 * @param kind the preference kind to change
51 * @param score the new preference score
52 * @param pref_rel the normalized preference value for this kind over all clients
55 (*GAS_solver_address_change_preference) (void *solver,
56 const struct GNUNET_PeerIdentity *peer, enum GNUNET_ATS_PreferenceKind kind,
60 * Give feedback about the current assignment
62 * @param handle the solver handle
63 * @param application the application sending this request
64 * @param peer the peer id
65 * @param scope the time interval for this feedback: [now - scope .. now]
66 * @param kind the preference kind for this feedback
67 * @param score the feedback score
70 (*GAS_solver_address_feedback_preference) (void *solver, void *application,
71 const struct GNUNET_PeerIdentity *peer,
72 const struct GNUNET_TIME_Relative scope,
73 enum GNUNET_ATS_PreferenceKind kind, double score);
76 * Notify the solver about a bulk operation changing possibly a lot of values
77 * Solver will not resolve until all bulk operations are marked as done
79 * @param solver the solver
82 (*GAS_solver_bulk_start) (void *solver);
85 * Mark a bulk operation as done
86 * Solver will resolve if values have changed
88 * @param solver the solver
91 (*GAS_solver_bulk_stop) (void *solver);
94 * Add a single address within a network to the solver
96 * @param solver the solver Handle
97 * @param addresses the address hashmap containing all addresses
98 * @param address the address to add
99 * @param network network type of this address
102 (*GAS_solver_address_add) (void *solver, struct ATS_Address *address,
106 * Delete an address or just the session from the solver
108 * @param solver the solver Handle
109 * @param addresses the address hashmap containing all addresses
110 * @param address the address to delete
111 * @param session_only remove address or just session
114 (*GAS_solver_address_delete) (void *solver, struct ATS_Address *address,
118 * Transport properties for this address have changed
120 * @param solver solver handle
121 * @param address the address
122 * @param type the ATSI type in HBO
123 * @param abs_value the absolute value of the property
124 * @param rel_value the normalized value
127 (*GAS_solver_address_property_changed) (void *solver,
128 struct ATS_Address *address, uint32_t type, uint32_t abs_value,
132 * Transport session for this address has changed
134 * NOTE: values in addresses are already updated
136 * @param solver solver handle
137 * @param address the address
138 * @param cur_session the current session
139 * @param new_session the new session
142 (*GAS_solver_address_session_changed) (void *solver,
143 struct ATS_Address *address, uint32_t cur_session, uint32_t new_session);
146 * Transport session for this address has changed
148 * NOTE: values in addresses are already updated
150 * @param solver solver handle
151 * @param address the address
152 * @param in_use usage state
155 (*GAS_solver_address_inuse_changed) (void *solver, struct ATS_Address *address,
159 * Network scope for this address has changed
161 * NOTE: values in addresses are already updated
163 * @param solver solver handle
164 * @param address the address
165 * @param current_network the current network
166 * @param new_network the new network
169 (*GAS_solver_address_network_changed) (void *solver,
170 struct ATS_Address *address, uint32_t current_network, uint32_t new_network);
173 * Get the prefered address for a peer from solver
175 * @param solver the solver to use
176 * @param addresses the address hashmap containing all addresses
177 * @param peer the peer
179 typedef const struct ATS_Address *
180 (*GAS_solver_get_preferred_address) (void *solver,
181 const struct GNUNET_PeerIdentity *peer);
184 * Stop getting the prefered address for a peer from solver
186 * @param solver the solver to use
187 * @param addresses the address hashmap containing all addresses
188 * @param peer the peer
191 (*GAS_solver_stop_get_preferred_address) (void *solver,
192 const struct GNUNET_PeerIdentity *peer);
197 * Each solver is required to set up this struct contained in the plugin
198 * environment struct in during startup
200 struct GNUNET_ATS_SolverFunctions
204 * Add a new address for a peer to the solver
206 * The address is already contained in the addresses hashmap!
208 GAS_solver_address_add s_add;
211 * Update the properties of an address in the solver
213 GAS_solver_address_property_changed s_address_update_property;
216 * Update the session of an address in the solver
218 GAS_solver_address_session_changed s_address_update_session;
221 * Notify the solver that in address is (not) actively used by transport
222 * to communicate with a remote peer
224 GAS_solver_address_inuse_changed s_address_update_inuse;
227 * Notify solver that the network an address is located in has changed
229 GAS_solver_address_network_changed s_address_update_network;
232 * Tell solver to notify ATS if the address to use changes for a specific
233 * peer using the bandwidth changed callback
235 * The solver must only notify about changes for peers with pending address
238 GAS_solver_get_preferred_address s_get;
241 * Tell solver stop notifying ATS about changes for this peers
243 * The solver must only notify about changes for peers with pending address
246 GAS_solver_stop_get_preferred_address s_get_stop;
249 * Delete an address in the solver
251 * The address is not contained in the address hashmap anymore!
253 GAS_solver_address_delete s_del;
256 * Change relative preference for quality in solver
258 GAS_solver_address_change_preference s_pref;
261 * Give feedback about the current assignment
263 GAS_solver_address_feedback_preference s_feedback;
266 * Start a bulk operation
268 * Used if many values have to be updated at the same time.
269 * When a bulk operation is pending the solver does not have to resolve
270 * the problem since more updates will follow anyway
272 * For each call to bulk_start, a call to bulk_stop is required!
274 GAS_solver_bulk_start s_bulk_start;
277 * Bulk operation done
279 * If no more bulk operations are pending, the solver can solve the problem
280 * with the updated values
282 GAS_solver_bulk_stop s_bulk_stop;
286 * Operation codes for solver information callback
288 * Order of calls is expected to be:
292 * GAS_OP_SOLVE_UPDATE_NOTIFICATION_START
293 * GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP
296 enum GAS_Solver_Operation
299 * A solution iteration has been started
304 * A solution iteration has been finished
309 * The setup of the problem as a preparation to solve it was started
311 GAS_OP_SOLVE_SETUP_START,
314 * The setup of the problem as a preparation to solve is finished
316 GAS_OP_SOLVE_SETUP_STOP,
319 * Solving of the LP problem was started
322 GAS_OP_SOLVE_MLP_LP_START,
325 * Solving of the LP problem is done
328 GAS_OP_SOLVE_MLP_LP_STOP,
331 * Solving of the MLP problem was started
334 GAS_OP_SOLVE_MLP_MLP_START,
337 * Solving of the MLP problem is done
340 GAS_OP_SOLVE_MLP_MLP_STOP,
343 * After the problem was finished, start notifications about changes
346 GAS_OP_SOLVE_UPDATE_NOTIFICATION_START,
349 * After the problem was finished, notifications about changes to addresses
352 GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP
356 * Status of a GAS_Solver_Operation operation
358 enum GAS_Solver_Status
372 * Status of the operation
374 enum GAS_Solver_Additional_Information
377 * No more specific information
382 * A full solution process is performed
383 * Quite specific to the MLP solver
388 * An existing solution was reused
389 * Quite specific to the MLP solver
394 * The proportional solver had to recalculate for a single network
396 GAS_INFO_PROP_SINGLE,
399 * The proportional solver had to recalculate for all networks
405 * Callback to call with additional information
406 * Used for measurement
408 * @param cls the closure
409 * @param op the operation
410 * @param peer the peer id
411 * @param kind the preference kind to change
412 * @param score the new preference score
413 * @param pref_rel the normalized preference value for this kind over all clients
416 (*GAS_solver_information_callback) (void *cls, enum GAS_Solver_Operation op,
417 enum GAS_Solver_Status stat, enum GAS_Solver_Additional_Information);
420 * Callback to call from solver when bandwidth for address has changed
422 * @param address the with changed bandwidth assigned
425 (*GAS_bandwidth_changed_cb) (void *cls, struct ATS_Address *address);
428 * Callback to call from solver to obtain application preference values for a
432 * @param id the peer id
433 * @return carry of double values containing the preferences with
434 * GNUNET_ATS_PreferenceCount elements
436 typedef const double *
437 (*GAS_get_preferences) (void *cls, const struct GNUNET_PeerIdentity *id);
440 * Callback to call from solver to obtain transport properties for an
444 * @param address the address
445 * @return carry of double values containing the preferences with
446 * GNUNET_ATS_PreferenceCount elements
448 typedef const double *
449 (*GAS_get_properties) (void *cls, const struct ATS_Address *address);
452 * The ATS service will pass a pointer to a struct
453 * of this type as the first and only argument to the
454 * entry point of each ATS solver.
456 struct GNUNET_ATS_PluginEnvironment
459 * Configuration handle to be used by the solver
461 const struct GNUNET_CONFIGURATION_Handle *cfg;
464 * Statistics handle to be used by the solver
466 const struct GNUNET_STATISTICS_Handle *stats;
469 * Hashmap containing all addresses available
471 struct GNUNET_CONTAINER_MultiPeerMap *addresses;
474 * ATS addresses callback to be notified about bandwidth assignment changes
476 GAS_bandwidth_changed_cb bandwidth_changed_cb;
479 * ATS addresses closure to be notified about bandwidth assignment changes
481 void *bw_changed_cb_cls;
484 * ATS addresses function to obtain preference values
486 GAS_get_preferences get_preferences;
489 * ATS addresses function closure to obtain preference values
491 void *get_preference_cls;
494 * ATS addresses function to obtain property values
496 GAS_get_properties get_property;
499 * ATS addresses function closure to obtain property values
501 void *get_property_cls;
504 * Callback for solver to call with status information,
507 GAS_solver_information_callback info_cb;
510 * Closure for information callback,
516 * The ATS solver plugin functions to call
518 struct GNUNET_ATS_SolverFunctions sf;
523 int networks[GNUNET_ATS_NetworkTypeCount];
526 * Number of networks available
531 * Array of configured outbound quotas
532 * Order according to networks in network array
534 unsigned long long out_quota[GNUNET_ATS_NetworkTypeCount];
537 * Array of configured inbound quotas
538 * Order according to networks in network array
540 unsigned long long in_quota[GNUNET_ATS_NetworkTypeCount];