2 This file is part of GNUnet
3 (C) 2009-2015 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,
57 enum GNUNET_ATS_PreferenceKind kind,
62 * Give feedback about the current assignment
64 * @param handle the solver handle
65 * @param application the application sending this request
66 * @param peer the peer id
67 * @param scope the time interval for this feedback: [now - scope .. now]
68 * @param kind the preference kind for this feedback
69 * @param score the feedback score
72 (*GAS_solver_address_feedback_preference) (void *solver,
73 struct GNUNET_SERVER_Client *application,
74 const struct GNUNET_PeerIdentity *peer,
75 const struct GNUNET_TIME_Relative scope,
76 enum GNUNET_ATS_PreferenceKind kind,
80 * Notify the solver about a bulk operation changing possibly a lot of values
81 * Solver will not resolve until all bulk operations are marked as done
83 * @param solver the solver
86 (*GAS_solver_bulk_start) (void *solver);
90 * Mark a bulk operation as done
91 * Solver will resolve if values have changed
93 * @param solver the solver
96 (*GAS_solver_bulk_stop) (void *solver);
100 * Add a single address within a network to the solver
102 * @param solver the solver Handle
103 * @param address the address to add
104 * @param network network type of this address
107 (*GAS_solver_address_add) (void *solver,
108 struct ATS_Address *address,
113 * Delete an address or just the session from the solver
115 * @param solver the solver Handle
116 * @param address the address to delete
117 * @param session_only remove address or just session
120 (*GAS_solver_address_delete) (void *solver,
121 struct ATS_Address *address,
126 * Transport properties for this address have changed
128 * @param solver solver handle
129 * @param address the address
130 * @param type the ATSI type in HBO
131 * @param abs_value the absolute value of the property
132 * @param rel_value the normalized value
135 (*GAS_solver_address_property_changed) (void *solver,
136 struct ATS_Address *address,
143 * Get the prefered address for a peer from solver
145 * @param solver the solver to use
146 * @param peer the peer
148 typedef const struct ATS_Address *
149 (*GAS_solver_get_preferred_address) (void *solver,
150 const struct GNUNET_PeerIdentity *peer);
154 * Stop getting the prefered address for a peer from solver
156 * @param solver the solver to use
157 * @param peer the peer
160 (*GAS_solver_stop_get_preferred_address) (void *solver,
161 const struct GNUNET_PeerIdentity *peer);
167 * Each solver is required to set up and return an instance
168 * of this struct during initialization.
170 struct GNUNET_ATS_SolverFunctions
174 * Closure to pass to all solver functions in this struct.
179 * Add a new address for a peer to the solver
181 * The address is already contained in the addresses hashmap!
183 GAS_solver_address_add s_add;
186 * Update the properties of an address in the solver
188 GAS_solver_address_property_changed s_address_update_property;
191 * Tell solver to notify ATS if the address to use changes for a specific
192 * peer using the bandwidth changed callback
194 * The solver must only notify about changes for peers with pending address
197 GAS_solver_get_preferred_address s_get;
200 * Tell solver stop notifying ATS about changes for this peers
202 * The solver must only notify about changes for peers with pending address
205 GAS_solver_stop_get_preferred_address s_get_stop;
208 * Delete an address in the solver
210 * The address is not contained in the address hashmap anymore!
212 GAS_solver_address_delete s_del;
215 * Change relative preference for quality in solver
217 GAS_solver_address_change_preference s_pref;
220 * Give feedback about the current assignment
222 GAS_solver_address_feedback_preference s_feedback;
225 * Start a bulk operation
227 * Used if many values have to be updated at the same time.
228 * When a bulk operation is pending the solver does not have to resolve
229 * the problem since more updates will follow anyway
231 * For each call to bulk_start, a call to bulk_stop is required!
233 GAS_solver_bulk_start s_bulk_start;
236 * Bulk operation done
238 * If no more bulk operations are pending, the solver can solve the problem
239 * with the updated values
241 GAS_solver_bulk_stop s_bulk_stop;
246 * Operation codes for solver information callback
248 * Order of calls is expected to be:
249 * #GAS_OP_SOLVE_START
251 * #GAS_OP_SOLVE_UPDATE_NOTIFICATION_START
252 * #GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP
255 enum GAS_Solver_Operation
258 * A solution iteration has been started
263 * A solution iteration has been finished
268 * The setup of the problem as a preparation to solve it was started
270 GAS_OP_SOLVE_SETUP_START,
273 * The setup of the problem as a preparation to solve is finished
275 GAS_OP_SOLVE_SETUP_STOP,
278 * Solving of the LP problem was started
281 GAS_OP_SOLVE_MLP_LP_START,
284 * Solving of the LP problem is done
287 GAS_OP_SOLVE_MLP_LP_STOP,
290 * Solving of the MLP problem was started
293 GAS_OP_SOLVE_MLP_MLP_START,
296 * Solving of the MLP problem is done
299 GAS_OP_SOLVE_MLP_MLP_STOP,
302 * After the problem was finished, start notifications about changes
305 GAS_OP_SOLVE_UPDATE_NOTIFICATION_START,
308 * After the problem was finished, notifications about changes to addresses
311 GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP
316 * Status of a GAS_Solver_Operation operation
318 enum GAS_Solver_Status
333 * Status of the operation
335 enum GAS_Solver_Additional_Information
338 * No more specific information
343 * A full solution process is performed
344 * Quite specific to the MLP solver
349 * An existing solution was reused
350 * Quite specific to the MLP solver
355 * The proportional solver had to recalculate for a single network
357 GAS_INFO_PROP_SINGLE,
360 * The proportional solver had to recalculate for all networks
367 * Callback to call with additional information
368 * Used for measurement
370 * @param cls the closure
371 * @param op the operation
374 (*GAS_solver_information_callback) (void *cls,
375 enum GAS_Solver_Operation op,
376 enum GAS_Solver_Status stat,
377 enum GAS_Solver_Additional_Information);
381 * Callback to call from solver when bandwidth for address has changed
383 * @param address the with changed bandwidth assigned
386 (*GAS_bandwidth_changed_cb) (void *cls,
387 struct ATS_Address *address);
391 * Callback to call from solver to obtain application preference values for a
395 * @param id the peer id
396 * @return carry of double values containing the preferences with
397 * GNUNET_ATS_PreferenceCount elements
399 typedef const double *
400 (*GAS_get_preferences) (void *cls,
401 const struct GNUNET_PeerIdentity *id);
405 * Callback to call from solver to obtain transport properties for an
409 * @param address the address
410 * @return carry of double values containing the preferences with
411 * GNUNET_ATS_PreferenceCount elements
413 typedef const double *
414 (*GAS_get_properties) (void *cls,
415 const struct ATS_Address *address);
419 * The ATS plugin will pass a pointer to a struct
420 * of this type as to the initialization function
421 * of the ATS plugins.
423 struct GNUNET_ATS_PluginEnvironment
426 * Configuration handle to be used by the solver
428 const struct GNUNET_CONFIGURATION_Handle *cfg;
431 * Statistics handle to be used by the solver
433 struct GNUNET_STATISTICS_Handle *stats;
436 * Closure to pass to all callbacks in this struct.
441 * Hashmap containing all addresses available
443 struct GNUNET_CONTAINER_MultiPeerMap *addresses;
446 * ATS addresses callback to be notified about bandwidth assignment changes
448 GAS_bandwidth_changed_cb bandwidth_changed_cb;
451 * ATS addresses function to obtain preference values
453 GAS_get_preferences get_preferences;
456 * ATS addresses function to obtain property values
458 GAS_get_properties get_property;
461 * Callback for solver to call with status information,
464 GAS_solver_information_callback info_cb;
467 * Number of networks available, size of the @e out_quota
468 * and @e in_quota arrays.
470 unsigned int network_count;
473 * Array of configured outbound quotas
474 * Order according to networks in network array
476 unsigned long long out_quota[GNUNET_ATS_NetworkTypeCount];
479 * Array of configured inbound quotas
480 * Order according to networks in network array
482 unsigned long long in_quota[GNUNET_ATS_NetworkTypeCount];