diff options
author | Christian Grothoff <christian@grothoff.org> | 2015-02-05 21:41:58 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2015-02-05 21:41:58 +0000 |
commit | b8d5c4c9220576e85b4eec4c7ffa0390ba887fb5 (patch) | |
tree | f93ff7c7d94c81f5182e1c4bc7fd829f4fc9a609 /src/include | |
parent | d4cb0035c1248e050d906e9018d36a9f5d19eb73 (diff) | |
download | gnunet-b8d5c4c9220576e85b4eec4c7ffa0390ba887fb5.tar.gz gnunet-b8d5c4c9220576e85b4eec4c7ffa0390ba887fb5.zip |
first pass at cleaning up ATS plugin API
Diffstat (limited to 'src/include')
-rw-r--r-- | src/include/gnunet_ats_plugin.h | 134 |
1 files changed, 68 insertions, 66 deletions
diff --git a/src/include/gnunet_ats_plugin.h b/src/include/gnunet_ats_plugin.h index e2272fdc8..36a49d252 100644 --- a/src/include/gnunet_ats_plugin.h +++ b/src/include/gnunet_ats_plugin.h | |||
@@ -1,6 +1,6 @@ | |||
1 | /* | 1 | /* |
2 | This file is part of GNUnet | 2 | This file is part of GNUnet |
3 | (C) 2009, 2010 Christian Grothoff (and other contributing authors) | 3 | (C) 2009-2015 Christian Grothoff (and other contributing authors) |
4 | 4 | ||
5 | GNUnet is free software; you can redistribute it and/or modify | 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 | 6 | it under the terms of the GNU General Public License as published |
@@ -53,8 +53,10 @@ struct ATS_Address; | |||
53 | */ | 53 | */ |
54 | typedef void | 54 | typedef void |
55 | (*GAS_solver_address_change_preference) (void *solver, | 55 | (*GAS_solver_address_change_preference) (void *solver, |
56 | const struct GNUNET_PeerIdentity *peer, enum GNUNET_ATS_PreferenceKind kind, | 56 | const struct GNUNET_PeerIdentity *peer, |
57 | double pref_rel); | 57 | enum GNUNET_ATS_PreferenceKind kind, |
58 | double pref_rel); | ||
59 | |||
58 | 60 | ||
59 | /** | 61 | /** |
60 | * Give feedback about the current assignment | 62 | * Give feedback about the current assignment |
@@ -67,10 +69,12 @@ typedef void | |||
67 | * @param score the feedback score | 69 | * @param score the feedback score |
68 | */ | 70 | */ |
69 | typedef void | 71 | typedef void |
70 | (*GAS_solver_address_feedback_preference) (void *solver, void *application, | 72 | (*GAS_solver_address_feedback_preference) (void *solver, |
71 | const struct GNUNET_PeerIdentity *peer, | 73 | struct GNUNET_SERVER_Client *application, |
72 | const struct GNUNET_TIME_Relative scope, | 74 | const struct GNUNET_PeerIdentity *peer, |
73 | enum GNUNET_ATS_PreferenceKind kind, double score); | 75 | const struct GNUNET_TIME_Relative scope, |
76 | enum GNUNET_ATS_PreferenceKind kind, | ||
77 | double score); | ||
74 | 78 | ||
75 | /** | 79 | /** |
76 | * Notify the solver about a bulk operation changing possibly a lot of values | 80 | * Notify the solver about a bulk operation changing possibly a lot of values |
@@ -81,6 +85,7 @@ typedef void | |||
81 | typedef void | 85 | typedef void |
82 | (*GAS_solver_bulk_start) (void *solver); | 86 | (*GAS_solver_bulk_start) (void *solver); |
83 | 87 | ||
88 | |||
84 | /** | 89 | /** |
85 | * Mark a bulk operation as done | 90 | * Mark a bulk operation as done |
86 | * Solver will resolve if values have changed | 91 | * Solver will resolve if values have changed |
@@ -90,29 +95,32 @@ typedef void | |||
90 | typedef void | 95 | typedef void |
91 | (*GAS_solver_bulk_stop) (void *solver); | 96 | (*GAS_solver_bulk_stop) (void *solver); |
92 | 97 | ||
98 | |||
93 | /** | 99 | /** |
94 | * Add a single address within a network to the solver | 100 | * Add a single address within a network to the solver |
95 | * | 101 | * |
96 | * @param solver the solver Handle | 102 | * @param solver the solver Handle |
97 | * @param addresses the address hashmap containing all addresses | ||
98 | * @param address the address to add | 103 | * @param address the address to add |
99 | * @param network network type of this address | 104 | * @param network network type of this address |
100 | */ | 105 | */ |
101 | typedef void | 106 | typedef void |
102 | (*GAS_solver_address_add) (void *solver, struct ATS_Address *address, | 107 | (*GAS_solver_address_add) (void *solver, |
103 | uint32_t network); | 108 | struct ATS_Address *address, |
109 | uint32_t network); | ||
110 | |||
104 | 111 | ||
105 | /** | 112 | /** |
106 | * Delete an address or just the session from the solver | 113 | * Delete an address or just the session from the solver |
107 | * | 114 | * |
108 | * @param solver the solver Handle | 115 | * @param solver the solver Handle |
109 | * @param addresses the address hashmap containing all addresses | ||
110 | * @param address the address to delete | 116 | * @param address the address to delete |
111 | * @param session_only remove address or just session | 117 | * @param session_only remove address or just session |
112 | */ | 118 | */ |
113 | typedef void | 119 | typedef void |
114 | (*GAS_solver_address_delete) (void *solver, struct ATS_Address *address, | 120 | (*GAS_solver_address_delete) (void *solver, |
115 | int session_only); | 121 | struct ATS_Address *address, |
122 | int session_only); | ||
123 | |||
116 | 124 | ||
117 | /** | 125 | /** |
118 | * Transport properties for this address have changed | 126 | * Transport properties for this address have changed |
@@ -125,42 +133,49 @@ typedef void | |||
125 | */ | 133 | */ |
126 | typedef void | 134 | typedef void |
127 | (*GAS_solver_address_property_changed) (void *solver, | 135 | (*GAS_solver_address_property_changed) (void *solver, |
128 | struct ATS_Address *address, uint32_t type, uint32_t abs_value, | 136 | struct ATS_Address *address, |
129 | double rel_value); | 137 | uint32_t type, |
138 | uint32_t abs_value, | ||
139 | double rel_value); | ||
130 | 140 | ||
131 | 141 | ||
132 | /** | 142 | /** |
133 | * Get the prefered address for a peer from solver | 143 | * Get the prefered address for a peer from solver |
134 | * | 144 | * |
135 | * @param solver the solver to use | 145 | * @param solver the solver to use |
136 | * @param addresses the address hashmap containing all addresses | ||
137 | * @param peer the peer | 146 | * @param peer the peer |
138 | */ | 147 | */ |
139 | typedef const struct ATS_Address * | 148 | typedef const struct ATS_Address * |
140 | (*GAS_solver_get_preferred_address) (void *solver, | 149 | (*GAS_solver_get_preferred_address) (void *solver, |
141 | const struct GNUNET_PeerIdentity *peer); | 150 | const struct GNUNET_PeerIdentity *peer); |
151 | |||
142 | 152 | ||
143 | /** | 153 | /** |
144 | * Stop getting the prefered address for a peer from solver | 154 | * Stop getting the prefered address for a peer from solver |
145 | * | 155 | * |
146 | * @param solver the solver to use | 156 | * @param solver the solver to use |
147 | * @param addresses the address hashmap containing all addresses | ||
148 | * @param peer the peer | 157 | * @param peer the peer |
149 | */ | 158 | */ |
150 | typedef void | 159 | typedef void |
151 | (*GAS_solver_stop_get_preferred_address) (void *solver, | 160 | (*GAS_solver_stop_get_preferred_address) (void *solver, |
152 | const struct GNUNET_PeerIdentity *peer); | 161 | const struct GNUNET_PeerIdentity *peer); |
162 | |||
153 | 163 | ||
154 | /** | 164 | /** |
155 | * Solver functions | 165 | * Solver functions. |
156 | * | 166 | * |
157 | * Each solver is required to set up this struct contained in the plugin | 167 | * Each solver is required to set up and return an instance |
158 | * environment struct in during startup | 168 | * of this struct during initialization. |
159 | */ | 169 | */ |
160 | struct GNUNET_ATS_SolverFunctions | 170 | struct GNUNET_ATS_SolverFunctions |
161 | { | 171 | { |
162 | 172 | ||
163 | /** | 173 | /** |
174 | * Closure to pass to all solver functions in this struct. | ||
175 | */ | ||
176 | void *cls; | ||
177 | |||
178 | /** | ||
164 | * Add a new address for a peer to the solver | 179 | * Add a new address for a peer to the solver |
165 | * | 180 | * |
166 | * The address is already contained in the addresses hashmap! | 181 | * The address is already contained in the addresses hashmap! |
@@ -226,15 +241,15 @@ struct GNUNET_ATS_SolverFunctions | |||
226 | GAS_solver_bulk_stop s_bulk_stop; | 241 | GAS_solver_bulk_stop s_bulk_stop; |
227 | }; | 242 | }; |
228 | 243 | ||
244 | |||
229 | /** | 245 | /** |
230 | * Operation codes for solver information callback | 246 | * Operation codes for solver information callback |
231 | * | 247 | * |
232 | * Order of calls is expected to be: | 248 | * Order of calls is expected to be: |
233 | * GAS_OP_SOLVE_START | 249 | * #GAS_OP_SOLVE_START |
234 | * | 250 | * #GAS_OP_SOLVE_STOP |
235 | * GAS_OP_SOLVE_STOP | 251 | * #GAS_OP_SOLVE_UPDATE_NOTIFICATION_START |
236 | * GAS_OP_SOLVE_UPDATE_NOTIFICATION_START | 252 | * #GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP |
237 | * GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP | ||
238 | * | 253 | * |
239 | */ | 254 | */ |
240 | enum GAS_Solver_Operation | 255 | enum GAS_Solver_Operation |
@@ -296,6 +311,7 @@ enum GAS_Solver_Operation | |||
296 | GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP | 311 | GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP |
297 | }; | 312 | }; |
298 | 313 | ||
314 | |||
299 | /** | 315 | /** |
300 | * Status of a GAS_Solver_Operation operation | 316 | * Status of a GAS_Solver_Operation operation |
301 | */ | 317 | */ |
@@ -312,6 +328,7 @@ enum GAS_Solver_Status | |||
312 | GAS_STAT_FAIL | 328 | GAS_STAT_FAIL |
313 | }; | 329 | }; |
314 | 330 | ||
331 | |||
315 | /** | 332 | /** |
316 | * Status of the operation | 333 | * Status of the operation |
317 | */ | 334 | */ |
@@ -345,20 +362,20 @@ enum GAS_Solver_Additional_Information | |||
345 | GAS_INFO_PROP_ALL | 362 | GAS_INFO_PROP_ALL |
346 | }; | 363 | }; |
347 | 364 | ||
365 | |||
348 | /** | 366 | /** |
349 | * Callback to call with additional information | 367 | * Callback to call with additional information |
350 | * Used for measurement | 368 | * Used for measurement |
351 | * | 369 | * |
352 | * @param cls the closure | 370 | * @param cls the closure |
353 | * @param op the operation | 371 | * @param op the operation |
354 | * @param peer the peer id | ||
355 | * @param kind the preference kind to change | ||
356 | * @param score the new preference score | ||
357 | * @param pref_rel the normalized preference value for this kind over all clients | ||
358 | */ | 372 | */ |
359 | typedef void | 373 | typedef void |
360 | (*GAS_solver_information_callback) (void *cls, enum GAS_Solver_Operation op, | 374 | (*GAS_solver_information_callback) (void *cls, |
361 | enum GAS_Solver_Status stat, enum GAS_Solver_Additional_Information); | 375 | enum GAS_Solver_Operation op, |
376 | enum GAS_Solver_Status stat, | ||
377 | enum GAS_Solver_Additional_Information); | ||
378 | |||
362 | 379 | ||
363 | /** | 380 | /** |
364 | * Callback to call from solver when bandwidth for address has changed | 381 | * Callback to call from solver when bandwidth for address has changed |
@@ -366,7 +383,9 @@ typedef void | |||
366 | * @param address the with changed bandwidth assigned | 383 | * @param address the with changed bandwidth assigned |
367 | */ | 384 | */ |
368 | typedef void | 385 | typedef void |
369 | (*GAS_bandwidth_changed_cb) (void *cls, struct ATS_Address *address); | 386 | (*GAS_bandwidth_changed_cb) (void *cls, |
387 | struct ATS_Address *address); | ||
388 | |||
370 | 389 | ||
371 | /** | 390 | /** |
372 | * Callback to call from solver to obtain application preference values for a | 391 | * Callback to call from solver to obtain application preference values for a |
@@ -378,7 +397,9 @@ typedef void | |||
378 | * GNUNET_ATS_PreferenceCount elements | 397 | * GNUNET_ATS_PreferenceCount elements |
379 | */ | 398 | */ |
380 | typedef const double * | 399 | typedef const double * |
381 | (*GAS_get_preferences) (void *cls, const struct GNUNET_PeerIdentity *id); | 400 | (*GAS_get_preferences) (void *cls, |
401 | const struct GNUNET_PeerIdentity *id); | ||
402 | |||
382 | 403 | ||
383 | /** | 404 | /** |
384 | * Callback to call from solver to obtain transport properties for an | 405 | * Callback to call from solver to obtain transport properties for an |
@@ -390,12 +411,14 @@ typedef const double * | |||
390 | * GNUNET_ATS_PreferenceCount elements | 411 | * GNUNET_ATS_PreferenceCount elements |
391 | */ | 412 | */ |
392 | typedef const double * | 413 | typedef const double * |
393 | (*GAS_get_properties) (void *cls, const struct ATS_Address *address); | 414 | (*GAS_get_properties) (void *cls, |
415 | const struct ATS_Address *address); | ||
416 | |||
394 | 417 | ||
395 | /** | 418 | /** |
396 | * The ATS service will pass a pointer to a struct | 419 | * The ATS plugin will pass a pointer to a struct |
397 | * of this type as the first and only argument to the | 420 | * of this type as to the initialization function |
398 | * entry point of each ATS solver. | 421 | * of the ATS plugins. |
399 | */ | 422 | */ |
400 | struct GNUNET_ATS_PluginEnvironment | 423 | struct GNUNET_ATS_PluginEnvironment |
401 | { | 424 | { |
@@ -407,7 +430,12 @@ struct GNUNET_ATS_PluginEnvironment | |||
407 | /** | 430 | /** |
408 | * Statistics handle to be used by the solver | 431 | * Statistics handle to be used by the solver |
409 | */ | 432 | */ |
410 | const struct GNUNET_STATISTICS_Handle *stats; | 433 | struct GNUNET_STATISTICS_Handle *stats; |
434 | |||
435 | /** | ||
436 | * Closure to pass to all callbacks in this struct. | ||
437 | */ | ||
438 | void *cls; | ||
411 | 439 | ||
412 | /** | 440 | /** |
413 | * Hashmap containing all addresses available | 441 | * Hashmap containing all addresses available |
@@ -420,48 +448,22 @@ struct GNUNET_ATS_PluginEnvironment | |||
420 | GAS_bandwidth_changed_cb bandwidth_changed_cb; | 448 | GAS_bandwidth_changed_cb bandwidth_changed_cb; |
421 | 449 | ||
422 | /** | 450 | /** |
423 | * ATS addresses closure to be notified about bandwidth assignment changes | ||
424 | */ | ||
425 | void *bw_changed_cb_cls; | ||
426 | |||
427 | /** | ||
428 | * ATS addresses function to obtain preference values | 451 | * ATS addresses function to obtain preference values |
429 | */ | 452 | */ |
430 | GAS_get_preferences get_preferences; | 453 | GAS_get_preferences get_preferences; |
431 | 454 | ||
432 | /** | 455 | /** |
433 | * ATS addresses function closure to obtain preference values | ||
434 | */ | ||
435 | void *get_preference_cls; | ||
436 | |||
437 | /** | ||
438 | * ATS addresses function to obtain property values | 456 | * ATS addresses function to obtain property values |
439 | */ | 457 | */ |
440 | GAS_get_properties get_property; | 458 | GAS_get_properties get_property; |
441 | 459 | ||
442 | /** | 460 | /** |
443 | * ATS addresses function closure to obtain property values | ||
444 | */ | ||
445 | void *get_property_cls; | ||
446 | |||
447 | /** | ||
448 | * Callback for solver to call with status information, | 461 | * Callback for solver to call with status information, |
449 | * can be NULL | 462 | * can be NULL |
450 | */ | 463 | */ |
451 | GAS_solver_information_callback info_cb; | 464 | GAS_solver_information_callback info_cb; |
452 | 465 | ||
453 | /** | 466 | /** |
454 | * Closure for information callback, | ||
455 | * can be NULL | ||
456 | */ | ||
457 | void *info_cb_cls; | ||
458 | |||
459 | /** | ||
460 | * The ATS solver plugin functions to call | ||
461 | */ | ||
462 | struct GNUNET_ATS_SolverFunctions sf; | ||
463 | |||
464 | /** | ||
465 | * Available networks | 467 | * Available networks |
466 | */ | 468 | */ |
467 | int networks[GNUNET_ATS_NetworkTypeCount]; | 469 | int networks[GNUNET_ATS_NetworkTypeCount]; |