diff options
Diffstat (limited to 'src/ats/gnunet-service-ats_addresses.h')
-rw-r--r-- | src/ats/gnunet-service-ats_addresses.h | 490 |
1 files changed, 0 insertions, 490 deletions
diff --git a/src/ats/gnunet-service-ats_addresses.h b/src/ats/gnunet-service-ats_addresses.h deleted file mode 100644 index b39484f59..000000000 --- a/src/ats/gnunet-service-ats_addresses.h +++ /dev/null | |||
@@ -1,490 +0,0 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | Copyright (C) 2011-2014 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 | * @file ats/gnunet-service-ats_addresses.h | ||
23 | * @brief ats service address management | ||
24 | * @author Matthias Wachs | ||
25 | * @author Christian Grothoff | ||
26 | */ | ||
27 | #ifndef GNUNET_SERVICE_ATS_ADDRESSES_H | ||
28 | #define GNUNET_SERVICE_ATS_ADDRESSES_H | ||
29 | |||
30 | #include "gnunet_util_lib.h" | ||
31 | #include "gnunet_ats_service.h" | ||
32 | #include "gnunet-service-ats.h" | ||
33 | #include "ats.h" | ||
34 | |||
35 | /** | ||
36 | * NOTE: Do not change this documentation. This documentation is based on | ||
37 | * gnunet.org:/vcs/fsnsg/ats-paper.git/tech-doku/ats-tech-guide.tex | ||
38 | * use build_txt.sh to generate plaintext output | ||
39 | * | ||
40 | * 1 ATS addresses : ATS address management | ||
41 | * | ||
42 | * This ATS addresses ("addresses") component manages the addresses known to | ||
43 | * ATS service and suggests addresses to transport service when it is | ||
44 | * interested in address suggestion for a peer. ATS addresses also | ||
45 | * instantiates the bandwidth assignment mechanism (solver), notifies it | ||
46 | * about changes to addresses and forwards changes to bandwidth assignments | ||
47 | * to transport, depending if transport is interested in this change. | ||
48 | * | ||
49 | * 1.1 Input data | ||
50 | * | ||
51 | * 1.1.1 Addresses | ||
52 | * | ||
53 | * Addresses are added by specifying peer ID, plugin, address, address length | ||
54 | * and session, if available. ATS information can be specified if available. | ||
55 | * | ||
56 | * 1.1.2 Networks | ||
57 | * | ||
58 | * ATS specifies a fix set of networks an address can belong to. For each | ||
59 | * network an inbound and outbound quota will be specified. The available | ||
60 | * networks and additional helper variables are defined in | ||
61 | * gnunet_ats_service.h. At the moment 5 networks are defined: | ||
62 | * * GNUNET_NT_UNSPECIFIED | ||
63 | * * GNUNET_NT_LOOPBACK | ||
64 | * * GNUNET_NT_LAN | ||
65 | * * GNUNET_NT_WAN | ||
66 | * * GNUNET_NT_WLAN | ||
67 | * | ||
68 | * The total number of networks defined is stored in | ||
69 | * GNUNET_NT_COUNT GNUNET_ATS_NetworkType can be used array | ||
70 | * initializer for an int array, while GNUNET_ATS_NetworkType is an | ||
71 | * initializer for a char array containing a string description of all | ||
72 | * networks | ||
73 | * | ||
74 | * 1.1.3 Quotas | ||
75 | * | ||
76 | * An inbound and outbound quota for each of the networks mentioned in 1.1.2 | ||
77 | * is loaded from ats configuration during initialization. This quota defines | ||
78 | * to total amount of inbound and outbound traffic allowed for a specific | ||
79 | * network. The configuration values used are in section ats: | ||
80 | * * "NETWORK"_QUOTA_IN = <value> | ||
81 | * * "NETWORK"_QUOTA_IN = <value> | ||
82 | * | ||
83 | * You can specify quotas by setting the <value> to a: | ||
84 | * * unrestricted: unlimited | ||
85 | * * number of bytes: e.g. 10240 | ||
86 | * * fancy value: e.g. 64 Kib | ||
87 | * | ||
88 | * unlimited is defined as GNUNET_ATS_MaxBandwidthString and equivalent to | ||
89 | * the value GNUNET_ATS_MaxBandwidth Important predefined values for quotas | ||
90 | * are: | ||
91 | * * GNUNET_ATS_DefaultBandwidth: 65536 | ||
92 | * * GNUNET_ATS_MaxBandwidth: UINT32_MAX | ||
93 | * * GNUNET_CONSTANTS_DEFAULT_BW_IN_OUT: 1024 | ||
94 | * | ||
95 | * Details of loading quotas and default values will be described on | ||
96 | * | ||
97 | * 1.1.4 Preference values | ||
98 | * | ||
99 | * 1.2 Data structures used | ||
100 | * | ||
101 | * Addresse uses struct ATS_Address for each address. The structs are stored | ||
102 | * in a linked list and provides a pointer void *solver_information for the | ||
103 | * solver to store address specific information. It provides the int values | ||
104 | * active which is set to GNUNET_YES if the address is select for transport | ||
105 | * use and used, representing that transport service is actively using this | ||
106 | * address. Address information are stored in peer, addr, addr_len, plugin. | ||
107 | * | ||
108 | * 1.3 Initialization | ||
109 | * | ||
110 | * During initialization a hashmap to store addresses is created. The quotas | ||
111 | * for all networks defined for ATS are loaded from configuration. For each | ||
112 | * network first the logic will check if the string | ||
113 | * GNUNET_ATS_MaxBandwidthString is configured, if not it will try to convert | ||
114 | * the configured value as a fancy size and if this fails it will try to use | ||
115 | * it as a value_number. If no configuration value is found it will assign | ||
116 | * GNUNET_ATS_DefaultBandwidth. The most important step is to load the | ||
117 | * configured solver using configuration "[ats]:MODE". Current solvers are | ||
118 | * MODE_PROPORTIONAL, MODE_MLP. Interaction is done using a solver API | ||
119 | * | ||
120 | * 1.4 Solver API | ||
121 | * | ||
122 | * Solver functions: | ||
123 | * * s_init: init the solver with required information | ||
124 | * * s_add: add a new address | ||
125 | * * s_update: update ATS values or session for an address | ||
126 | * * s_get: get preferred address for a peer | ||
127 | * * s_del: delete an address | ||
128 | * * s_pref: change preference value for a peer | ||
129 | * * s_done: shutdown solver | ||
130 | * | ||
131 | * Callbacks: addresses provides a bandwidth_changed_cb callback to the | ||
132 | * solver which is called when bandwidth assigned to peer has changed | ||
133 | * | ||
134 | * 1.5 Shutdown | ||
135 | * | ||
136 | * During shutdown all addresses are freed and the solver told to shutdown | ||
137 | * | ||
138 | * 1.6 Addresses and sessions | ||
139 | * | ||
140 | * Addresses consist of the address itself and a numerical session. When a | ||
141 | * new address without a session is added it has no session, so it gets | ||
142 | * session 0 assigned. When an address with a session is added and an address | ||
143 | * object with session 0 is found, this object is updated with the session | ||
144 | * otherwise a new address object with this session assigned is created. | ||
145 | * | ||
146 | * 1.6.1 Terminology | ||
147 | * | ||
148 | * Addresses a1,a2 with session s1, s2 are "exact" if: | ||
149 | * (a1 == a2)&&(s1 == s2) | ||
150 | * Addresses a1,a2 with session s1, s2 are "equivalent" if: | ||
151 | * (a1 == a2)&&((s1 == s2)||(s1 == 0)||(s2 == 0) | ||
152 | * | ||
153 | * 1.7 Address management | ||
154 | * | ||
155 | * Transport service notifies ATS about changes to the addresses known to | ||
156 | * it. | ||
157 | * | ||
158 | * 1.7.1 Adding an address | ||
159 | * | ||
160 | * When transport learns a new address it tells ATS and ATS is telling | ||
161 | * addresses about it using GAS_address_add. If not known to addresses it | ||
162 | * creates a new address object and calls solver's s_add. ATS information are | ||
163 | * deserialized and solver is notified about the session and ATS information | ||
164 | * using s_update. | ||
165 | * | ||
166 | * 1.7.2 Updating an address | ||
167 | * | ||
168 | * Addresses does an lookup up for the existing address with the given | ||
169 | * session. If disassembles included ATS information and notifies the solver | ||
170 | * using s_update about the update. | ||
171 | * | ||
172 | * 1.7.3 Deleting an address | ||
173 | * | ||
174 | * Addresses does an lookup for the exact address and session and if removes | ||
175 | * this address. If session != 0 the session is set to 0 and the address is | ||
176 | * kept. If session == 0, the addresses is removed. | ||
177 | * | ||
178 | * 1.7.4 Requesting an address suggestion | ||
179 | * | ||
180 | * The address client issues a request address message to be notified about | ||
181 | * address suggestions for a specific peer. Addresses asks the solver with | ||
182 | * s_get. If no address is available, it will not send a response, otherwise | ||
183 | * it will respond with the chosen address. | ||
184 | * | ||
185 | * 1.7.5 Address suggestions | ||
186 | * | ||
187 | * Addresses will notify the client automatically on any bandwidth_changed_cb | ||
188 | * by the solver if a address suggestion request is pending. If no address is | ||
189 | * available it will not respond at all If the client is not interested | ||
190 | * anymore, it has to cancel the address suggestion request. | ||
191 | * | ||
192 | * 1.7.6 Suggestions blocks and reset | ||
193 | * | ||
194 | * After suggesting an address it is blocked for ATS_BLOCKING_DELTA sec. to | ||
195 | * prevent the client from being thrashed. If the client requires immediately | ||
196 | * it can reset this block using GAS_addresses_handle_backoff_reset. | ||
197 | * | ||
198 | * 1.7.7 Address lifecycle | ||
199 | * | ||
200 | * * (add address) | ||
201 | * * (updated address) | ||
202 | * * (delete address) | ||
203 | * | ||
204 | * 1.8 Bandwidth assignment | ||
205 | * | ||
206 | * The addresses are used to perform resource allocation operations. ATS | ||
207 | * addresses takes care of instantiating the solver configured and notifies | ||
208 | * the respective solver about address changes and receives changes to the | ||
209 | * bandwidth assignment from the solver. The current bandwidth assignment is | ||
210 | * sent to transport. The specific solvers will be described in the specific | ||
211 | * section. | ||
212 | * | ||
213 | * 1.9 Changing peer preferences | ||
214 | * | ||
215 | * The bandwidth assigned to a peer can be influenced by setting a preference | ||
216 | * for a peer. The preference will be given to to the solver with s_pref which | ||
217 | * has to take care of the preference value | ||
218 | */ | ||
219 | |||
220 | |||
221 | /* | ||
222 | * How long will address suggestions blocked after a suggestion | ||
223 | */ | ||
224 | #define ATS_BLOCKING_DELTA GNUNET_TIME_relative_multiply ( \ | ||
225 | GNUNET_TIME_UNIT_MILLISECONDS, 100) | ||
226 | |||
227 | /** | ||
228 | * Information provided by ATS normalization | ||
229 | */ | ||
230 | struct GAS_NormalizationInfo | ||
231 | { | ||
232 | /** | ||
233 | * Next index to use in averaging queue | ||
234 | */ | ||
235 | unsigned int avg_queue_index; | ||
236 | |||
237 | /** | ||
238 | * Averaging queue | ||
239 | */ | ||
240 | uint64_t atsi_abs[GAS_normalization_queue_length]; | ||
241 | |||
242 | /** | ||
243 | * Averaged ATSI values from queue | ||
244 | */ | ||
245 | uint64_t avg; | ||
246 | |||
247 | /** | ||
248 | * Normalized values from queue to a range of values [1.0...2.0] | ||
249 | */ | ||
250 | double norm; | ||
251 | }; | ||
252 | |||
253 | |||
254 | /** | ||
255 | * Address with additional information | ||
256 | */ | ||
257 | struct ATS_Address | ||
258 | { | ||
259 | /** | ||
260 | * Peer ID this address is for. | ||
261 | */ | ||
262 | struct GNUNET_PeerIdentity peer; | ||
263 | |||
264 | /** | ||
265 | * Address (in plugin-specific binary format). | ||
266 | */ | ||
267 | const void *addr; | ||
268 | |||
269 | /** | ||
270 | * Plugin name | ||
271 | */ | ||
272 | char *plugin; | ||
273 | |||
274 | /** | ||
275 | * Solver-specific information for this address | ||
276 | */ | ||
277 | void *solver_information; | ||
278 | |||
279 | /** | ||
280 | * ATS performance information for this address | ||
281 | */ | ||
282 | struct GNUNET_ATS_Properties properties; | ||
283 | |||
284 | /** | ||
285 | * Time when address had last activity (update, in uses) | ||
286 | */ | ||
287 | struct GNUNET_TIME_Absolute t_last_activity; | ||
288 | |||
289 | /** | ||
290 | * Time when address was added | ||
291 | */ | ||
292 | struct GNUNET_TIME_Absolute t_added; | ||
293 | |||
294 | /** | ||
295 | * Address length, number of bytes in @e addr. | ||
296 | */ | ||
297 | size_t addr_len; | ||
298 | |||
299 | /** | ||
300 | * Session ID, can never be 0. | ||
301 | */ | ||
302 | uint32_t session_id; | ||
303 | |||
304 | /** | ||
305 | * Field to store local flags. | ||
306 | */ | ||
307 | enum GNUNET_HELLO_AddressInfo local_address_info; | ||
308 | |||
309 | /** | ||
310 | * ATS performance information for this address, size of the @e atsi array. | ||
311 | */ | ||
312 | uint32_t atsi_count; | ||
313 | |||
314 | /** | ||
315 | * Inbound bandwidth assigned by solver | ||
316 | */ | ||
317 | uint32_t assigned_bw_in; | ||
318 | |||
319 | /** | ||
320 | * Outbound bandwidth assigned by solver | ||
321 | */ | ||
322 | uint32_t assigned_bw_out; | ||
323 | |||
324 | /** | ||
325 | * Inbound bandwidth assigned by solver in NBO | ||
326 | */ | ||
327 | uint32_t last_notified_bw_in; | ||
328 | |||
329 | /** | ||
330 | * Outbound bandwidth assigned by solver in NBO | ||
331 | */ | ||
332 | uint32_t last_notified_bw_out; | ||
333 | |||
334 | /** | ||
335 | * Is this the active address for this peer? | ||
336 | */ | ||
337 | int active; | ||
338 | |||
339 | /** | ||
340 | * Normalized delay information for this address. | ||
341 | */ | ||
342 | struct GAS_NormalizationInfo norm_delay; | ||
343 | |||
344 | /** | ||
345 | * Normalized distance information for this address. | ||
346 | */ | ||
347 | struct GAS_NormalizationInfo norm_distance; | ||
348 | |||
349 | /** | ||
350 | * Normalized utilization inbound for this address. | ||
351 | */ | ||
352 | struct GAS_NormalizationInfo norm_utilization_in; | ||
353 | |||
354 | /** | ||
355 | * Normalized utilization outbound for this address. | ||
356 | */ | ||
357 | struct GAS_NormalizationInfo norm_utilization_out; | ||
358 | }; | ||
359 | |||
360 | |||
361 | /** | ||
362 | * A multipeermap mapping peer identities to `struct ATS_Address`. | ||
363 | */ | ||
364 | extern struct GNUNET_CONTAINER_MultiPeerMap *GSA_addresses; | ||
365 | |||
366 | |||
367 | /** | ||
368 | * Initialize address subsystem. The addresses subsystem manages the addresses | ||
369 | * known and current performance information. | ||
370 | */ | ||
371 | void | ||
372 | GAS_addresses_init (void); | ||
373 | |||
374 | |||
375 | /** | ||
376 | * Shutdown address subsystem. | ||
377 | */ | ||
378 | void | ||
379 | GAS_addresses_done (void); | ||
380 | |||
381 | |||
382 | /** | ||
383 | * Add a new address for a peer. | ||
384 | * | ||
385 | * @param peer peer | ||
386 | * @param plugin_name transport plugin name | ||
387 | * @param plugin_addr plugin address | ||
388 | * @param plugin_addr_len length of the @a plugin_addr | ||
389 | * @param local_address_info the local address for the address | ||
390 | * @param session_id session id, can never be 0. | ||
391 | * @param prop performance information for this address | ||
392 | */ | ||
393 | void | ||
394 | GAS_addresses_add (const struct GNUNET_PeerIdentity *peer, | ||
395 | const char *plugin_name, | ||
396 | const void *plugin_addr, | ||
397 | size_t plugin_addr_len, | ||
398 | uint32_t local_address_info, | ||
399 | uint32_t session_id, | ||
400 | const struct GNUNET_ATS_Properties *prop); | ||
401 | |||
402 | |||
403 | /** | ||
404 | * Update an address with new performance information for a peer. | ||
405 | * | ||
406 | * @param peer peer | ||
407 | * @param session_id session id, can never be 0 | ||
408 | * @param prop performance information for this address | ||
409 | */ | ||
410 | void | ||
411 | GAS_addresses_update (const struct GNUNET_PeerIdentity *peer, | ||
412 | uint32_t session_id, | ||
413 | const struct GNUNET_ATS_Properties *prop); | ||
414 | |||
415 | |||
416 | /** | ||
417 | * Remove an address for a peer. | ||
418 | * | ||
419 | * @param peer peer | ||
420 | * @param session_id session id, can never be 0 | ||
421 | */ | ||
422 | void | ||
423 | GAS_addresses_destroy (const struct GNUNET_PeerIdentity *peer, | ||
424 | uint32_t session_id); | ||
425 | |||
426 | |||
427 | /** | ||
428 | * Remove all addresses. | ||
429 | */ | ||
430 | void | ||
431 | GAS_addresses_destroy_all (void); | ||
432 | |||
433 | |||
434 | /** | ||
435 | * Iterator for #GAS_addresses_get_peer_info() | ||
436 | * | ||
437 | * @param cls closure | ||
438 | * @param id the peer id | ||
439 | * @param plugin_name plugin name | ||
440 | * @param plugin_addr address | ||
441 | * @param plugin_addr_len length of @a plugin_addr | ||
442 | * @param address_active is address actively used | ||
443 | * @param atsi ats performance information | ||
444 | * @param local_address_info flags for the address | ||
445 | * @param bandwidth_out current outbound bandwidth assigned to address | ||
446 | * @param bandwidth_in current inbound bandwidth assigned to address | ||
447 | */ | ||
448 | typedef void | ||
449 | (*GNUNET_ATS_PeerInfo_Iterator) (void *cls, | ||
450 | const struct GNUNET_PeerIdentity *id, | ||
451 | const char *plugin_name, | ||
452 | const void *plugin_addr, | ||
453 | size_t plugin_addr_len, | ||
454 | const int address_active, | ||
455 | const struct GNUNET_ATS_Properties *prop, | ||
456 | enum GNUNET_HELLO_AddressInfo | ||
457 | local_address_info, | ||
458 | struct GNUNET_BANDWIDTH_Value32NBO | ||
459 | bandwidth_out, | ||
460 | struct GNUNET_BANDWIDTH_Value32NBO | ||
461 | bandwidth_in); | ||
462 | |||
463 | |||
464 | /** | ||
465 | * Return information all peers currently known to ATS | ||
466 | * | ||
467 | * @param peer the respective peer | ||
468 | * @param pi_it the iterator to call for every peer | ||
469 | * @param pi_it_cls the closure for @a pi_it | ||
470 | */ | ||
471 | void | ||
472 | GAS_addresses_get_peer_info (const struct GNUNET_PeerIdentity *peer, | ||
473 | GNUNET_ATS_PeerInfo_Iterator pi_it, | ||
474 | void *pi_it_cls); | ||
475 | |||
476 | |||
477 | /** | ||
478 | * Handle 'address list request' messages from clients. | ||
479 | * | ||
480 | * @param client client that sent the request | ||
481 | * @param alrm the request message | ||
482 | */ | ||
483 | void | ||
484 | GAS_handle_request_address_list (struct GNUNET_SERVICE_Client *client, | ||
485 | const struct AddressListRequestMessage *alrm); | ||
486 | |||
487 | |||
488 | #endif | ||
489 | |||
490 | /* end of gnunet-service-ats_addresses.h */ | ||