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"
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, 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, void *application,
73 const struct GNUNET_PeerIdentity *peer,
74 const struct GNUNET_TIME_Relative scope,
75 enum GNUNET_ATS_PreferenceKind kind, double score);
78 * Notify the solver about a bulk operation changing possibly a lot of values
79 * Solver will not resolve until all bulk operations are marked as done
81 * @param solver the solver
84 (*GAS_solver_bulk_start) (void *solver);
87 * Mark a bulk operation as done
88 * Solver will resolve if values have changed
90 * @param solver the solver
93 (*GAS_solver_bulk_stop) (void *solver);
96 * Add a single address within a network to the solver
98 * @param solver the solver Handle
99 * @param addresses the address hashmap containing all addresses
100 * @param address the address to add
101 * @param network network type of this address
104 (*GAS_solver_address_add) (void *solver, struct ATS_Address *address,
108 * Delete an address or just the session from the solver
110 * @param solver the solver Handle
111 * @param addresses the address hashmap containing all addresses
112 * @param address the address to delete
113 * @param session_only remove address or just session
116 (*GAS_solver_address_delete) (void *solver, struct ATS_Address *address,
120 * Transport properties for this address have changed
122 * @param solver solver handle
123 * @param address the address
124 * @param type the ATSI type in HBO
125 * @param abs_value the absolute value of the property
126 * @param rel_value the normalized value
129 (*GAS_solver_address_property_changed) (void *solver,
130 struct ATS_Address *address, uint32_t type, uint32_t abs_value,
134 * Transport session for this address has changed
136 * NOTE: values in addresses are already updated
138 * @param solver solver handle
139 * @param address the address
140 * @param cur_session the current session
141 * @param new_session the new session
144 (*GAS_solver_address_session_changed) (void *solver,
145 struct ATS_Address *address, uint32_t cur_session, uint32_t new_session);
148 * Transport session for this address has changed
150 * NOTE: values in addresses are already updated
152 * @param solver solver handle
153 * @param address the address
154 * @param in_use usage state
157 (*GAS_solver_address_inuse_changed) (void *solver, struct ATS_Address *address,
161 * Network scope for this address has changed
163 * NOTE: values in addresses are already updated
165 * @param solver solver handle
166 * @param address the address
167 * @param current_network the current network
168 * @param new_network the new network
171 (*GAS_solver_address_network_changed) (void *solver,
172 struct ATS_Address *address, uint32_t current_network, uint32_t new_network);
175 * Get the prefered address for a peer from solver
177 * @param solver the solver to use
178 * @param addresses the address hashmap containing all addresses
179 * @param peer the peer
181 typedef const struct ATS_Address *
182 (*GAS_solver_get_preferred_address) (void *solver,
183 const struct GNUNET_PeerIdentity *peer);
186 * Stop getting the prefered address for a peer from solver
188 * @param solver the solver to use
189 * @param addresses the address hashmap containing all addresses
190 * @param peer the peer
193 (*GAS_solver_stop_get_preferred_address) (void *solver,
194 const struct GNUNET_PeerIdentity *peer);
200 * Each solver is required to set up this struct contained in the plugin
201 * environment struct in during startup
203 struct GNUNET_ATS_SolverFunctions
207 * Add a new address for a peer to the solver
209 * The address is already contained in the addresses hashmap!
211 GAS_solver_address_add s_add;
215 * Update the properties of an address in the solver
217 GAS_solver_address_property_changed s_address_update_property;
221 * Update the session of an address in the solver
223 GAS_solver_address_session_changed s_address_update_session;
227 * Notify the solver that in address is (not) actively used by transport
228 * to communicate with a remote peer
230 GAS_solver_address_inuse_changed s_address_update_inuse;
234 * Notify solver that the network an address is located in has changed
236 GAS_solver_address_network_changed s_address_update_network;
239 * Tell solver to notify ATS if the address to use changes for a specific
240 * peer using the bandwidth changed callback
242 * The solver must only notify about changes for peers with pending address
245 GAS_solver_get_preferred_address s_get;
248 * Tell solver stop notifying ATS about changes for this peers
250 * The solver must only notify about changes for peers with pending address
253 GAS_solver_stop_get_preferred_address s_get_stop;
257 * Delete an address in the solver
259 * The address is not contained in the address hashmap anymore!
261 GAS_solver_address_delete s_del;
265 * Change relative preference for quality in solver
267 GAS_solver_address_change_preference s_pref;
271 * Give feedback about the current assignment
273 GAS_solver_address_feedback_preference s_feedback;
277 * Start a bulk operation
279 * Used if many values have to be updated at the same time.
280 * When a bulk operation is pending the solver does not have to resolve
281 * the problem since more updates will follow anyway
283 * For each call to bulk_start, a call to bulk_stop is required!
285 GAS_solver_bulk_start s_bulk_start;
289 * Bulk operation done
291 * If no more bulk operations are pending, the solver can solve the problem
292 * with the updated values
294 GAS_solver_bulk_stop s_bulk_stop;
299 * Callback to call from solver when bandwidth for address has changed
301 * @param address the with changed bandwidth assigned
304 (*GAS_bandwidth_changed_cb) (void *cls, struct ATS_Address *address);
307 * Callback to call from solver to obtain application preference values for a
311 * @param id the peer id
312 * @return carry of double values containing the preferences with
313 * GNUNET_ATS_PreferenceCount elements
315 typedef const double *
316 (*GAS_get_preferences) (void *cls, const struct GNUNET_PeerIdentity *id);
319 * Callback to call from solver to obtain transport properties for an
323 * @param address the address
324 * @return carry of double values containing the preferences with
325 * GNUNET_ATS_PreferenceCount elements
327 typedef const double *
328 (*GAS_get_properties) (void *cls, const struct ATS_Address *address);
332 * The ATS service will pass a pointer to a struct
333 * of this type as the first and only argument to the
334 * entry point of each ATS solver.
336 struct GNUNET_ATS_PluginEnvironment
339 * Configuration handle to be used by the solver
341 const struct GNUNET_CONFIGURATION_Handle *cfg;
345 * Statistics handle to be used by the solver
347 const struct GNUNET_STATISTICS_Handle *stats;
351 * Hashmap containing all addresses available
353 struct GNUNET_CONTAINER_MultiPeerMap *addresses;
357 * ATS addresses callback to be notified about bandwidth assignment changes
359 GAS_bandwidth_changed_cb bandwidth_changed_cb;
363 * ATS addresses closure to be notified about bandwidth assignment changes
365 void *bw_changed_cb_cls;
369 * ATS addresses function to obtain preference values
371 GAS_get_preferences get_preferences;
375 * ATS addresses function closure to obtain preference values
377 void *get_preference_cls;
381 * ATS addresses function to obtain property values
383 GAS_get_properties get_property;
387 * ATS addresses function closure to obtain property values
389 void *get_property_cls;
393 * The ATS solver plugin functions to call
395 struct GNUNET_ATS_SolverFunctions sf;
401 int networks[GNUNET_ATS_NetworkTypeCount];
405 * Number of networks available
411 * Array of configured outbound quotas
412 * Order according to networks in network array
414 unsigned long long out_quota[GNUNET_ATS_NetworkTypeCount];
418 * Array of configured inbound quotas
419 * Order according to networks in network array
421 unsigned long long in_quota[GNUNET_ATS_NetworkTypeCount];