diff options
author | Matthias Wachs <wachs@net.in.tum.de> | 2013-10-09 07:48:25 +0000 |
---|---|---|
committer | Matthias Wachs <wachs@net.in.tum.de> | 2013-10-09 07:48:25 +0000 |
commit | 4d37bf113ef8e56aa9b50d6b140b0488a5ae6717 (patch) | |
tree | f8364a4f440a5111d0f231f877646852bc22400b /src/include | |
parent | 69a0cb2c32f87d324b6a33eba00765b024befef4 (diff) | |
download | gnunet-4d37bf113ef8e56aa9b50d6b140b0488a5ae6717.tar.gz gnunet-4d37bf113ef8e56aa9b50d6b140b0488a5ae6717.zip |
documentation for solver api
Diffstat (limited to 'src/include')
-rw-r--r-- | src/include/gnunet_ats_plugin.h | 71 |
1 files changed, 52 insertions, 19 deletions
diff --git a/src/include/gnunet_ats_plugin.h b/src/include/gnunet_ats_plugin.h index c9dfd8e39..fe333399b 100644 --- a/src/include/gnunet_ats_plugin.h +++ b/src/include/gnunet_ats_plugin.h | |||
@@ -195,65 +195,103 @@ typedef void | |||
195 | 195 | ||
196 | 196 | ||
197 | /** | 197 | /** |
198 | * Each plugin is required to return a pointer to a struct of this | 198 | * Solver functions |
199 | * type as the return value from its entry point. | 199 | * |
200 | * Each solver is required to set up this struct contained in the plugin | ||
201 | * environment struct in during startup | ||
200 | */ | 202 | */ |
201 | struct GNUNET_ATS_SolverFunctions | 203 | struct GNUNET_ATS_SolverFunctions |
202 | { | 204 | { |
203 | 205 | ||
204 | /** | 206 | /** |
205 | * Closure for all of the callbacks. | 207 | * Add a new address for a peer to the solver |
208 | * | ||
209 | * The address is already contained in the addresses hashmap! | ||
206 | */ | 210 | */ |
207 | void *cls; | 211 | GAS_solver_address_add s_add; |
212 | |||
208 | 213 | ||
209 | /** | 214 | /** |
210 | * Add an address to the solver | 215 | * Update the properties of an address in the solver |
211 | */ | 216 | */ |
212 | GAS_solver_address_add s_add; | ||
213 | |||
214 | GAS_solver_address_property_changed s_address_update_property; | 217 | GAS_solver_address_property_changed s_address_update_property; |
215 | 218 | ||
219 | |||
220 | /** | ||
221 | * Update the session of an address in the solver | ||
222 | */ | ||
216 | GAS_solver_address_session_changed s_address_update_session; | 223 | GAS_solver_address_session_changed s_address_update_session; |
217 | 224 | ||
225 | |||
226 | /** | ||
227 | * Notify the solver that in address is (not) actively used by transport | ||
228 | * to communicate with a remote peer | ||
229 | */ | ||
218 | GAS_solver_address_inuse_changed s_address_update_inuse; | 230 | GAS_solver_address_inuse_changed s_address_update_inuse; |
219 | 231 | ||
232 | |||
233 | /** | ||
234 | * Notify solver that the network an address is located in has changed | ||
235 | */ | ||
220 | GAS_solver_address_network_changed s_address_update_network; | 236 | GAS_solver_address_network_changed s_address_update_network; |
221 | 237 | ||
222 | /** | 238 | /** |
223 | * Get address from solver | 239 | * Tell solver to notify ATS if the address to use changes for a specific |
240 | * peer using the bandwidth changed callback | ||
241 | * | ||
242 | * The solver must only notify about changes for peers with pending address | ||
243 | * requests! | ||
224 | */ | 244 | */ |
225 | GAS_solver_get_preferred_address s_get; | 245 | GAS_solver_get_preferred_address s_get; |
226 | 246 | ||
227 | /** | 247 | /** |
228 | * Get address from solver | 248 | * Tell solver stop notifying ATS about changes for this peers |
229 | */ | 249 | * |
250 | * The solver must only notify about changes for peers with pending address | ||
251 | * requests! | ||
252 | */ | ||
230 | GAS_solver_stop_get_preferred_address s_get_stop; | 253 | GAS_solver_stop_get_preferred_address s_get_stop; |
231 | 254 | ||
255 | |||
232 | /** | 256 | /** |
233 | * Delete address in solver | 257 | * Delete an address in the solver |
258 | * | ||
259 | * The address is not contained in the address hashmap anymore! | ||
234 | */ | 260 | */ |
235 | GAS_solver_address_delete s_del; | 261 | GAS_solver_address_delete s_del; |
236 | 262 | ||
263 | |||
237 | /** | 264 | /** |
238 | * Change relative preference for quality in solver | 265 | * Change relative preference for quality in solver |
239 | */ | 266 | */ |
240 | GAS_solver_address_change_preference s_pref; | 267 | GAS_solver_address_change_preference s_pref; |
241 | 268 | ||
269 | |||
242 | /** | 270 | /** |
243 | * Give feedback about the current assignment | 271 | * Give feedback about the current assignment |
244 | */ | 272 | */ |
245 | GAS_solver_address_feedback_preference s_feedback; | 273 | GAS_solver_address_feedback_preference s_feedback; |
246 | 274 | ||
275 | |||
247 | /** | 276 | /** |
248 | * Start a bulk operation | 277 | * Start a bulk operation |
278 | * | ||
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 | ||
282 | * | ||
283 | * For each call to bulk_start, a call to bulk_stop is required! | ||
249 | */ | 284 | */ |
250 | GAS_solver_bulk_start s_bulk_start; | 285 | GAS_solver_bulk_start s_bulk_start; |
251 | 286 | ||
287 | |||
252 | /** | 288 | /** |
253 | * Bulk operation done | 289 | * Bulk operation done |
290 | * | ||
291 | * If no more bulk operations are pending, the solver can solve the problem | ||
292 | * with the updated values | ||
254 | */ | 293 | */ |
255 | GAS_solver_bulk_stop s_bulk_stop; | 294 | GAS_solver_bulk_stop s_bulk_stop; |
256 | |||
257 | }; | 295 | }; |
258 | 296 | ||
259 | 297 | ||
@@ -298,12 +336,6 @@ typedef const double * | |||
298 | struct GNUNET_ATS_PluginEnvironment | 336 | struct GNUNET_ATS_PluginEnvironment |
299 | { | 337 | { |
300 | /** | 338 | /** |
301 | * Closure for the various callbacks. | ||
302 | */ | ||
303 | void *cls; | ||
304 | |||
305 | |||
306 | /** | ||
307 | * Configuration handle to be used by the solver | 339 | * Configuration handle to be used by the solver |
308 | */ | 340 | */ |
309 | const struct GNUNET_CONFIGURATION_Handle *cfg; | 341 | const struct GNUNET_CONFIGURATION_Handle *cfg; |
@@ -344,10 +376,11 @@ struct GNUNET_ATS_PluginEnvironment | |||
344 | */ | 376 | */ |
345 | void *get_preference_cls; | 377 | void *get_preference_cls; |
346 | 378 | ||
379 | |||
347 | /** | 380 | /** |
348 | * ATS addresses function to obtain property values | 381 | * ATS addresses function to obtain property values |
349 | */ | 382 | */ |
350 | GAS_get_properties get_property_cb; | 383 | GAS_get_properties get_property; |
351 | 384 | ||
352 | 385 | ||
353 | /** | 386 | /** |