diff options
author | Matthias Wachs <wachs@net.in.tum.de> | 2013-04-02 09:02:07 +0000 |
---|---|---|
committer | Matthias Wachs <wachs@net.in.tum.de> | 2013-04-02 09:02:07 +0000 |
commit | bc943e8ca08fb36ecfb51f2efd362838b2e3d7ae (patch) | |
tree | ac356326194e48d2c317a17e92041762f57b28d7 /src | |
parent | cc9cba8ae326936e3f4679d0c518592f23579658 (diff) | |
download | gnunet-bc943e8ca08fb36ecfb51f2efd362838b2e3d7ae.tar.gz gnunet-bc943e8ca08fb36ecfb51f2efd362838b2e3d7ae.zip |
some documentation
Diffstat (limited to 'src')
-rw-r--r-- | src/ats/gnunet-service-ats_addresses.h | 271 |
1 files changed, 256 insertions, 15 deletions
diff --git a/src/ats/gnunet-service-ats_addresses.h b/src/ats/gnunet-service-ats_addresses.h index ddb011fce..82d42a6b1 100644 --- a/src/ats/gnunet-service-ats_addresses.h +++ b/src/ats/gnunet-service-ats_addresses.h | |||
@@ -32,6 +32,198 @@ | |||
32 | #include "gnunet_statistics_service.h" | 32 | #include "gnunet_statistics_service.h" |
33 | #include "ats.h" | 33 | #include "ats.h" |
34 | 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 addtional helper varaibles are defined in | ||
61 | * gnunet_ats_service.h. At the moment 5 networks are defined: | ||
62 | * * GNUNET_ATS_NET_UNSPECIFIED | ||
63 | * * GNUNET_ATS_NET_LOOPBACK | ||
64 | * * GNUNET_ATS_NET_LAN | ||
65 | * * GNUNET_ATS_NET_WAN | ||
66 | * * GNUNET_ATS_NET_WLAN | ||
67 | * | ||
68 | * The total number of networks defined is stored in | ||
69 | * GNUNET_ATS_NetworkTypeCount 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_SIMPLISTIC, 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 prefered 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 | * him. | ||
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 choosen 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 Marking address in use | ||
199 | * | ||
200 | * The client can notify addresses that it successfully uses an address and | ||
201 | * wants this address to be kept by calling GSA_address_in_use. Adresses will | ||
202 | * mark the address as used an notify the solver about the use. | ||
203 | * | ||
204 | * 1.7.8 Address lifecycle | ||
205 | * | ||
206 | * * (add address) | ||
207 | * * (updated address) || (address in use) | ||
208 | * * (delete address) | ||
209 | * | ||
210 | * 1.8 Bandwidth assignment | ||
211 | * | ||
212 | * The addresses are used to perform resource allocation operations. ATS | ||
213 | * addresses takes care of instantiating the solver configured and notifies | ||
214 | * the respective solver about address changes and receives changes to the | ||
215 | * bandwidth assignment from the solver. The current bandwidth assignment is | ||
216 | * sent to transport. The specific solvers will be described in the specific | ||
217 | * section. | ||
218 | * | ||
219 | * 1.9 Changing peer preferences | ||
220 | * | ||
221 | * The bandwidth assigned to a peer can be influenced by setting a preference | ||
222 | * for a peer. The prefernce will be given to to the solver with s_pref which | ||
223 | * has to take care of the preference value | ||
224 | |||
225 | */ | ||
226 | |||
35 | #define ATS_BLOCKING_DELTA GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_MILLISECONDS, 100) | 227 | #define ATS_BLOCKING_DELTA GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_MILLISECONDS, 100) |
36 | 228 | ||
37 | struct GAS_Addresses_Handle; | 229 | struct GAS_Addresses_Handle; |
@@ -233,10 +425,14 @@ typedef void | |||
233 | 425 | ||
234 | 426 | ||
235 | /** | 427 | /** |
236 | * Initialize address subsystem. | 428 | * Initialize address subsystem. The addresses subsystem manages the addresses |
429 | * known and current performance information. It has a solver component | ||
430 | * responsible for the resource allocation. It tells the solver about changes | ||
431 | * and receives updates when the solver changes the ressource allocation. | ||
237 | * | 432 | * |
238 | * @param cfg configuration to use | 433 | * @param cfg configuration to use |
239 | * @param stats the statistics handle to use | 434 | * @param stats the statistics handle to use |
435 | * @return an address handle | ||
240 | */ | 436 | */ |
241 | struct GAS_Addresses_Handle * | 437 | struct GAS_Addresses_Handle * |
242 | GAS_addresses_init (const struct GNUNET_CONFIGURATION_Handle *cfg, | 438 | GAS_addresses_init (const struct GNUNET_CONFIGURATION_Handle *cfg, |
@@ -244,22 +440,63 @@ GAS_addresses_init (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
244 | 440 | ||
245 | /** | 441 | /** |
246 | * Shutdown address subsystem. | 442 | * Shutdown address subsystem. |
443 | * | ||
444 | * @param the address handle to shutdown | ||
247 | */ | 445 | */ |
248 | void | 446 | void |
249 | GAS_addresses_done (struct GAS_Addresses_Handle *handle); | 447 | GAS_addresses_done (struct GAS_Addresses_Handle *handle); |
250 | 448 | ||
449 | |||
450 | /** | ||
451 | * Add a new address for a peer. | ||
452 | * | ||
453 | * @param handle the address handle to use | ||
454 | * @param peer peer | ||
455 | * @param plugin_name transport plugin name | ||
456 | * @param plugin_addr plugin address | ||
457 | * @param plugin_addr_len length of the plugin address | ||
458 | * @param session_id session id, can be 0 | ||
459 | * @param atsi performance information for this address | ||
460 | * @param atsi_count number of performance information contained | ||
461 | */ | ||
251 | void | 462 | void |
252 | GAS_addresses_handle_backoff_reset (struct GAS_Addresses_Handle *handle, | 463 | GAS_addresses_add (struct GAS_Addresses_Handle *handle, |
253 | const struct GNUNET_PeerIdentity *peer); | 464 | const struct GNUNET_PeerIdentity *peer, |
465 | const char *plugin_name, | ||
466 | const void *plugin_addr, | ||
467 | size_t plugin_addr_len, | ||
468 | uint32_t session_id, | ||
469 | const struct GNUNET_ATS_Information *atsi, | ||
470 | uint32_t atsi_count); | ||
471 | |||
254 | 472 | ||
255 | /** | 473 | /** |
256 | * This address is now used or not used anymore | 474 | * Notification about active use of an address. |
475 | * in_use == GNUNET_YES: | ||
476 | * This address is used to maintain an active connection with a peer. | ||
477 | * in_use == GNUNET_NO: | ||
478 | * This address is no longer used to maintain an active connection with a peer. | ||
479 | * | ||
480 | * Note: can only be called with in_use == GNUNET_NO if called with GNUNET_YES | ||
481 | * before | ||
482 | * | ||
483 | * @param handle the address handle to use | ||
484 | * @param peer peer | ||
485 | * @param plugin_name transport plugin name | ||
486 | * @param plugin_addr plugin address | ||
487 | * @param plugin_addr_len length of the plugin address | ||
488 | * @param session_id session id, can be 0 | ||
489 | * @param in_use GNUNET_YES if GNUNET_NO | ||
490 | * @return GNUNET_SYSERR on failure (address unknown ...) | ||
257 | */ | 491 | */ |
258 | int | 492 | int |
259 | GAS_addresses_in_use (struct GAS_Addresses_Handle *handle, | 493 | GAS_addresses_in_use (struct GAS_Addresses_Handle *handle, |
260 | const struct GNUNET_PeerIdentity *peer, | 494 | const struct GNUNET_PeerIdentity *peer, |
261 | const char *plugin_name, const void *plugin_addr, | 495 | const char *plugin_name, |
262 | size_t plugin_addr_len, uint32_t session_id, int in_use); | 496 | const void *plugin_addr, |
497 | size_t plugin_addr_len, | ||
498 | uint32_t session_id, | ||
499 | int in_use); | ||
263 | 500 | ||
264 | void | 501 | void |
265 | GAS_addresses_update (struct GAS_Addresses_Handle *handle, | 502 | GAS_addresses_update (struct GAS_Addresses_Handle *handle, |
@@ -281,6 +518,10 @@ void | |||
281 | GAS_addresses_destroy_all (struct GAS_Addresses_Handle *handle); | 518 | GAS_addresses_destroy_all (struct GAS_Addresses_Handle *handle); |
282 | 519 | ||
283 | 520 | ||
521 | void | ||
522 | GAS_addresses_request_address (struct GAS_Addresses_Handle *handle, | ||
523 | const struct GNUNET_PeerIdentity *peer); | ||
524 | |||
284 | /** | 525 | /** |
285 | * Cancel address suggestions for a peer | 526 | * Cancel address suggestions for a peer |
286 | * | 527 | * |
@@ -290,9 +531,16 @@ void | |||
290 | GAS_addresses_request_address_cancel (struct GAS_Addresses_Handle *handle, | 531 | GAS_addresses_request_address_cancel (struct GAS_Addresses_Handle *handle, |
291 | const struct GNUNET_PeerIdentity *peer); | 532 | const struct GNUNET_PeerIdentity *peer); |
292 | 533 | ||
534 | |||
535 | |||
536 | |||
537 | /** | ||
538 | * | ||
539 | */ | ||
293 | void | 540 | void |
294 | GAS_addresses_request_address (struct GAS_Addresses_Handle *handle, | 541 | GAS_addresses_handle_backoff_reset (struct GAS_Addresses_Handle *handle, |
295 | const struct GNUNET_PeerIdentity *peer); | 542 | const struct GNUNET_PeerIdentity *peer); |
543 | |||
296 | 544 | ||
297 | void | 545 | void |
298 | GAS_addresses_change_preference (struct GAS_Addresses_Handle *handle, | 546 | GAS_addresses_change_preference (struct GAS_Addresses_Handle *handle, |
@@ -301,13 +549,6 @@ GAS_addresses_change_preference (struct GAS_Addresses_Handle *handle, | |||
301 | enum GNUNET_ATS_PreferenceKind kind, | 549 | enum GNUNET_ATS_PreferenceKind kind, |
302 | float score); | 550 | float score); |
303 | 551 | ||
304 | void | ||
305 | GAS_addresses_add (struct GAS_Addresses_Handle *handle, | ||
306 | const struct GNUNET_PeerIdentity *peer, | ||
307 | const char *plugin_name, const void *plugin_addr, | ||
308 | size_t plugin_addr_len, uint32_t session_id, | ||
309 | const struct GNUNET_ATS_Information *atsi, | ||
310 | uint32_t atsi_count); | ||
311 | 552 | ||
312 | 553 | ||
313 | typedef void (*GNUNET_ATS_Peer_Iterator) (void *p_it_cls, | 554 | typedef void (*GNUNET_ATS_Peer_Iterator) (void *p_it_cls, |