aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_ats_plugin.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_ats_plugin.h')
-rw-r--r--src/include/gnunet_ats_plugin.h486
1 files changed, 0 insertions, 486 deletions
diff --git a/src/include/gnunet_ats_plugin.h b/src/include/gnunet_ats_plugin.h
deleted file mode 100644
index c0662673c..000000000
--- a/src/include/gnunet_ats_plugin.h
+++ /dev/null
@@ -1,486 +0,0 @@
1/*
2 This file is part of GNUnet
3 Copyright (C) 2009-2015 GNUnet e.V.
4
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your option) any later version.
9
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 Affero General Public License for more details.
14
15 You should have received a copy of the GNU Affero General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
17
18 SPDX-License-Identifier: AGPL3.0-or-later
19 */
20
21/**
22 * @author Christian Grothoff
23 *
24 * @file
25 * API for the ATS solvers.
26 *
27 * @defgroup ats-plugin ATS service plugin API
28 * Plugin API for the ATS service.
29 *
30 * Specifies the struct that is given to the plugin's entry method and the other
31 * struct that must be returned. Note that the destructors of ATS plugins will
32 * be given the value returned by the constructor and is expected to return a
33 * NULL pointer.
34 *
35 * @{
36 */
37#ifndef PLUGIN_ATS_H
38#define PLUGIN_ATS_H
39
40#include "gnunet_ats_service.h"
41#include "gnunet_statistics_service.h"
42
43/**
44 * Representation of an address the plugin can choose from.
45 */
46struct ATS_Address;
47
48/**
49 * Change the preference for a peer
50 *
51 * @param handle the solver handle
52 * @param client the client sending this request
53 * @param peer the peer id
54 * @param kind the preference kind to change
55 * @param score the new preference score
56 * @param pref_rel the normalized preference value for this kind over all clients
57 */
58typedef void
59(*GAS_solver_address_change_preference) (void *solver,
60 const struct GNUNET_PeerIdentity *peer,
61 enum GNUNET_ATS_PreferenceKind kind,
62 double pref_rel);
63
64
65/**
66 * Give feedback about the current assignment
67 *
68 * @param handle the solver handle
69 * @param application the application sending this request
70 * @param peer the peer id
71 * @param scope the time interval for this feedback: [now - scope .. now]
72 * @param kind the preference kind for this feedback
73 * @param score the feedback score
74 */
75typedef void
76(*GAS_solver_address_feedback_preference) (void *solver,
77 struct GNUNET_SERVICE_Client *
78 application,
79 const struct
80 GNUNET_PeerIdentity *peer,
81 const struct GNUNET_TIME_Relative
82 scope,
83 enum GNUNET_ATS_PreferenceKind kind,
84 double score);
85
86/**
87 * Notify the solver about a bulk operation changing possibly a lot of values
88 * Solver will not resolve until all bulk operations are marked as done
89 *
90 * @param solver the solver
91 */
92typedef void
93(*GAS_solver_bulk_start) (void *solver);
94
95
96/**
97 * Mark a bulk operation as done
98 * Solver will resolve if values have changed
99 *
100 * @param solver the solver
101 */
102typedef void
103(*GAS_solver_bulk_stop) (void *solver);
104
105
106/**
107 * Add a single address within a network to the solver
108 *
109 * @param solver the solver Handle
110 * @param address the address to add
111 * @param network network type of this address
112 */
113typedef void
114(*GAS_solver_address_add) (void *solver,
115 struct ATS_Address *address,
116 uint32_t network);
117
118
119/**
120 * Delete an address or just the session from the solver
121 *
122 * @param solver the solver Handle
123 * @param address the address to delete
124 */
125typedef void
126(*GAS_solver_address_delete) (void *solver,
127 struct ATS_Address *address);
128
129
130/**
131 * Transport properties for this address have changed
132 *
133 * @param solver solver handle
134 * @param address the address
135 */
136typedef void
137(*GAS_solver_address_property_changed) (void *solver,
138 struct ATS_Address *address);
139
140
141/**
142 * Get the preferred address for a peer from solver
143 *
144 * @param solver the solver to use
145 * @param peer the peer
146 */
147typedef void
148(*GAS_solver_get_preferred_address) (void *solver,
149 const struct GNUNET_PeerIdentity *peer);
150
151
152/**
153 * Stop getting the preferred address for a peer from solver
154 *
155 * @param solver the solver to use
156 * @param peer the peer
157 */
158typedef void
159(*GAS_solver_stop_get_preferred_address) (void *solver,
160 const struct
161 GNUNET_PeerIdentity *peer);
162
163
164/**
165 * Solver functions.
166 *
167 * Each solver is required to set up and return an instance
168 * of this struct during initialization.
169 */
170struct GNUNET_ATS_SolverFunctions
171{
172 /**
173 * Closure to pass to all solver functions in this struct.
174 */
175 void *cls;
176
177 /**
178 * Add a new address for a peer to the solver
179 *
180 * The address is already contained in the addresses hashmap!
181 */
182 GAS_solver_address_add s_add;
183
184 /**
185 * Update the properties of an address in the solver
186 */
187 GAS_solver_address_property_changed s_address_update_property;
188
189 /**
190 * Tell solver to notify ATS if the address to use changes for a specific
191 * peer using the bandwidth changed callback
192 *
193 * The solver must only notify about changes for peers with pending address
194 * requests!
195 */
196 GAS_solver_get_preferred_address s_get;
197
198 /**
199 * Tell solver stop notifying ATS about changes for this peers
200 *
201 * The solver must only notify about changes for peers with pending address
202 * requests!
203 */
204 GAS_solver_stop_get_preferred_address s_get_stop;
205
206 /**
207 * Delete an address in the solver
208 *
209 * The address is not contained in the address hashmap anymore!
210 */
211 GAS_solver_address_delete s_del;
212
213 /**
214 * Change relative preference for quality in solver
215 */
216 GAS_solver_address_change_preference s_pref;
217
218 /**
219 * Give feedback about the current assignment
220 */
221 GAS_solver_address_feedback_preference s_feedback;
222
223 /**
224 * Start a bulk operation
225 *
226 * Used if many values have to be updated at the same time.
227 * When a bulk operation is pending the solver does not have to resolve
228 * the problem since more updates will follow anyway
229 *
230 * For each call to bulk_start, a call to bulk_stop is required!
231 */
232 GAS_solver_bulk_start s_bulk_start;
233
234 /**
235 * Bulk operation done
236 *
237 * If no more bulk operations are pending, the solver can solve the problem
238 * with the updated values
239 */
240 GAS_solver_bulk_stop s_bulk_stop;
241};
242
243
244/**
245 * Operation codes for solver information callback
246 *
247 * Order of calls is expected to be:
248 * #GAS_OP_SOLVE_START
249 * #GAS_OP_SOLVE_STOP
250 * #GAS_OP_SOLVE_UPDATE_NOTIFICATION_START
251 * #GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP
252 *
253 */
254enum GAS_Solver_Operation
255{
256 /**
257 * A solution iteration has been started
258 */
259 GAS_OP_SOLVE_START,
260
261 /**
262 * A solution iteration has been finished
263 */
264 GAS_OP_SOLVE_STOP,
265
266 /**
267 * The setup of the problem as a preparation to solve it was started
268 */
269 GAS_OP_SOLVE_SETUP_START,
270
271 /**
272 * The setup of the problem as a preparation to solve is finished
273 */
274 GAS_OP_SOLVE_SETUP_STOP,
275
276 /**
277 * Solving of the LP problem was started
278 * MLP solver only
279 */
280 GAS_OP_SOLVE_MLP_LP_START,
281
282 /**
283 * Solving of the LP problem is done
284 * MLP solver only
285 */
286 GAS_OP_SOLVE_MLP_LP_STOP,
287
288 /**
289 * Solving of the MLP problem was started
290 * MLP solver only
291 */
292 GAS_OP_SOLVE_MLP_MLP_START,
293
294 /**
295 * Solving of the MLP problem is done
296 * MLP solver only
297 */
298 GAS_OP_SOLVE_MLP_MLP_STOP,
299
300 /**
301 * After the problem was finished, start notifications about changes
302 * to addresses
303 */
304 GAS_OP_SOLVE_UPDATE_NOTIFICATION_START,
305
306 /**
307 * After the problem was finished, notifications about changes to addresses
308 * are done
309 */
310 GAS_OP_SOLVE_UPDATE_NOTIFICATION_STOP
311};
312
313
314/**
315 * Status of a GAS_Solver_Operation operation
316 */
317enum GAS_Solver_Status
318{
319 /**
320 * Success
321 */
322 GAS_STAT_SUCCESS,
323
324 /**
325 * Failure
326 */
327 GAS_STAT_FAIL
328};
329
330
331/**
332 * Status of the operation
333 */
334enum GAS_Solver_Additional_Information
335{
336 /**
337 * No more specific information
338 */
339 GAS_INFO_NONE,
340
341 /**
342 * A full solution process is performed
343 * Quite specific to the MLP solver
344 */
345 GAS_INFO_FULL,
346
347 /**
348 * An existing solution was reused
349 * Quite specific to the MLP solver
350 */
351 GAS_INFO_UPDATED,
352
353 /**
354 * The proportional solver had to recalculate for a single network
355 */
356 GAS_INFO_PROP_SINGLE,
357
358 /**
359 * The proportional solver had to recalculate for all networks
360 */
361 GAS_INFO_PROP_ALL
362};
363
364
365/**
366 * Callback to call with additional information
367 * Used for measurement
368 *
369 * @param cls the closure
370 * @param op the operation
371 */
372typedef void
373(*GAS_solver_information_callback) (void *cls,
374 enum GAS_Solver_Operation op,
375 enum GAS_Solver_Status stat,
376 enum GAS_Solver_Additional_Information);
377
378
379/**
380 * Callback to call from solver when bandwidth for address has changed
381 *
382 * @param address the with changed bandwidth assigned
383 */
384typedef void
385(*GAS_bandwidth_changed_cb) (void *cls,
386 struct ATS_Address *address);
387
388
389/**
390 * Callback to call from solver to obtain application preference
391 * values for a peer.
392 *
393 * @param cls the cls
394 * @param id the peer id
395 * @return carry of double values containing the preferences with
396 * GNUNET_ATS_PreferenceCount elements
397 */
398typedef const double *
399(*GAS_get_preferences) (void *cls,
400 const struct GNUNET_PeerIdentity *id);
401
402
403/**
404 * Callback to call from solver to obtain application connectivity
405 * preferences for a peer.
406 *
407 * @param cls the cls
408 * @param id the peer id
409 * @return 0 if connectivity is not desired, non-null if address
410 * suggestions are requested
411 */
412typedef unsigned int
413(*GAS_get_connectivity) (void *cls,
414 const struct GNUNET_PeerIdentity *id);
415
416
417/**
418 * The ATS plugin will pass a pointer to a struct
419 * of this type as to the initialization function
420 * of the ATS plugins.
421 */
422struct GNUNET_ATS_PluginEnvironment
423{
424 /**
425 * Configuration handle to be used by the solver
426 */
427 const struct GNUNET_CONFIGURATION_Handle *cfg;
428
429 /**
430 * Statistics handle to be used by the solver
431 */
432 struct GNUNET_STATISTICS_Handle *stats;
433
434 /**
435 * Closure to pass to all callbacks in this struct.
436 */
437 void *cls;
438
439 /**
440 * Hashmap containing all addresses available
441 */
442 struct GNUNET_CONTAINER_MultiPeerMap *addresses;
443
444 /**
445 * ATS addresses callback to be notified about bandwidth assignment changes
446 */
447 GAS_bandwidth_changed_cb bandwidth_changed_cb;
448
449 /**
450 * ATS addresses function to obtain preference values
451 */
452 GAS_get_preferences get_preferences;
453
454 /**
455 * ATS addresses function to obtain preference values
456 */
457 GAS_get_connectivity get_connectivity;
458
459 /**
460 * Callback for solver to call with status information,
461 * can be NULL
462 */
463 GAS_solver_information_callback info_cb;
464
465 /**
466 * Number of networks available, size of the @e out_quota
467 * and @e in_quota arrays.
468 */
469 unsigned int network_count;
470
471 /**
472 * Array of configured outbound quotas
473 * Order according to networks in network array
474 */
475 unsigned long long out_quota[GNUNET_NT_COUNT];
476
477 /**
478 * Array of configured inbound quotas
479 * Order according to networks in network array
480 */
481 unsigned long long in_quota[GNUNET_NT_COUNT];
482};
483
484#endif
485
486/** @} */ /* end of group */
generated by cgit v1.2.3 (git 2.39.1) at 2024-04-20 06:24:22 +0000