aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_ats_service.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_ats_service.h')
-rw-r--r--src/include/gnunet_ats_service.h652
1 files changed, 0 insertions, 652 deletions
diff --git a/src/include/gnunet_ats_service.h b/src/include/gnunet_ats_service.h
deleted file mode 100644
index 1bf5d40b0..000000000
--- a/src/include/gnunet_ats_service.h
+++ /dev/null
@@ -1,652 +0,0 @@
1/*
2 This file is part of GNUnet.
3 Copyright (C) 2010-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 * @addtogroup Backbone
22 * @{
23 *
24 * @file
25 * Automatic transport selection and outbound bandwidth determination
26 *
27 * @author Christian Grothoff
28 * @author Matthias Wachs
29 *
30 * @defgroup ats ATS service
31 * Automatic Transport Selection and outbound bandwidth determination
32 *
33 * @see [Documentation](https://gnunet.org/ats-subsystem)
34 *
35 * @{
36 */
37#ifndef GNUNET_ATS_SERVICE_H
38#define GNUNET_ATS_SERVICE_H
39
40
41#include "gnunet_constants.h"
42#include "gnunet_util_lib.h"
43#include "gnunet_hello_lib.h"
44
45
46/**
47 * Default bandwidth assigned to a network : 64 KB/s
48 */
49#define GNUNET_ATS_DefaultBandwidth 65536
50
51/**
52 * Undefined value for an `enum GNUNET_ATS_Property`
53 */
54#define GNUNET_ATS_VALUE_UNDEFINED UINT32_MAX
55
56/**
57 * String representation for GNUNET_ATS_VALUE_UNDEFINED
58 */
59#define GNUNET_ATS_VALUE_UNDEFINED_STR "undefined"
60
61/**
62 * Maximum bandwidth assigned to a network : 4095 MB/s
63 */
64#define GNUNET_ATS_MaxBandwidth UINT32_MAX
65
66/**
67 * Textual equivalent for GNUNET_ATS_MaxBandwidth
68 */
69#define GNUNET_ATS_MaxBandwidthString "unlimited"
70
71
72/**
73 * ATS performance characteristics for an address.
74 */
75struct GNUNET_ATS_Properties
76{
77 /**
78 * Delay. Time between when the time packet is sent and the packet
79 * arrives. FOREVER if we did not measure yet.
80 */
81 struct GNUNET_TIME_Relative delay;
82
83 /**
84 * Actual traffic on this connection from this peer to the other peer.
85 * Includes transport overhead.
86 *
87 * Unit: [bytes/second]
88 */
89 uint32_t utilization_out;
90
91 /**
92 * Actual traffic on this connection from the other peer to this peer.
93 * Includes transport overhead.
94 *
95 * Unit: [bytes/second]
96 */
97 uint32_t utilization_in;
98
99 /**
100 * Distance on network layer (required for distance-vector routing)
101 * in hops. Zero for direct connections (e.g. plain TCP/UDP).
102 */
103 unsigned int distance;
104
105 /**
106 * Which network scope does the respective address belong to?
107 * This property does not change.
108 */
109 enum GNUNET_NetworkType scope;
110};
111
112
113/**
114 * ATS performance characteristics for an address in
115 * network byte order (for IPC).
116 */
117struct GNUNET_ATS_PropertiesNBO
118{
119 /**
120 * Actual traffic on this connection from this peer to the other peer.
121 * Includes transport overhead.
122 *
123 * Unit: [bytes/second]
124 */
125 uint32_t utilization_out GNUNET_PACKED;
126
127 /**
128 * Actual traffic on this connection from the other peer to this peer.
129 * Includes transport overhead.
130 *
131 * Unit: [bytes/second]
132 */
133 uint32_t utilization_in GNUNET_PACKED;
134
135 /**
136 * Which network scope does the respective address belong to?
137 * This property does not change.
138 */
139 uint32_t scope GNUNET_PACKED;
140
141 /**
142 * Distance on network layer (required for distance-vector routing)
143 * in hops. Zero for direct connections (e.g. plain TCP/UDP).
144 */
145 uint32_t distance GNUNET_PACKED;
146
147 /**
148 * Delay. Time between when the time packet is sent and the packet
149 * arrives. FOREVER if we did not measure yet.
150 */
151 struct GNUNET_TIME_RelativeNBO delay;
152};
153
154
155/* ********************* LAN Characterization library ************************ */
156/* Note: these functions do not really communicate with the ATS service */
157
158
159/**
160 * Convert ATS properties from host to network byte order.
161 *
162 * @param nbo[out] value written
163 * @param hbo value read
164 */
165void
166GNUNET_ATS_properties_hton (struct GNUNET_ATS_PropertiesNBO *nbo,
167 const struct GNUNET_ATS_Properties *hbo);
168
169
170/**
171 * Convert ATS properties from network to host byte order.
172 *
173 * @param hbo[out] value written
174 * @param nbo value read
175 */
176void
177GNUNET_ATS_properties_ntoh (struct GNUNET_ATS_Properties *hbo,
178 const struct GNUNET_ATS_PropertiesNBO *nbo);
179
180
181/* ********************Connection Suggestion API ***************************** */
182
183/**
184 * Handle to the ATS subsystem for making suggestions about
185 * connections the peer would like to have.
186 */
187struct GNUNET_ATS_ConnectivityHandle;
188
189/**
190 * Handle for address suggestion requests.
191 */
192struct GNUNET_ATS_ConnectivitySuggestHandle;
193
194
195/**
196 * Initialize the ATS connectivity suggestion client handle.
197 *
198 * @param cfg configuration to use
199 * @return ats connectivity handle, NULL on error
200 */
201struct GNUNET_ATS_ConnectivityHandle *
202GNUNET_ATS_connectivity_init (const struct
203 GNUNET_CONFIGURATION_Handle *cfg) __attribute__(
204 (deprecated));
205
206
207/**
208 * Shutdown ATS connectivity suggestion client.
209 *
210 * @param ch handle to destroy
211 */
212void
213GNUNET_ATS_connectivity_done (struct
214 GNUNET_ATS_ConnectivityHandle *ch) __attribute__(
215 (deprecated));
216
217
218/**
219 * We would like to establish a new connection with a peer. ATS
220 * should suggest a good address to begin with.
221 *
222 * @param ch handle
223 * @param peer identity of the peer we need an address for
224 * @param strength how urgent is the need for such a suggestion
225 * @return suggestion handle, NULL if request is already pending
226 */
227struct GNUNET_ATS_ConnectivitySuggestHandle *
228GNUNET_ATS_connectivity_suggest (struct GNUNET_ATS_ConnectivityHandle *ch,
229 const struct GNUNET_PeerIdentity *peer,
230 uint32_t strength) __attribute__((deprecated));
231
232
233/**
234 * We no longer care about being connected to a peer.
235 *
236 * @param sh handle to stop
237 */
238void
239GNUNET_ATS_connectivity_suggest_cancel (struct
240 GNUNET_ATS_ConnectivitySuggestHandle *sh)
241__attribute__((deprecated));
242
243
244/* ******************************** Scheduling API ***************************** */
245
246/**
247 * Handle to the ATS subsystem for bandwidth/transport scheduling information.
248 */
249struct GNUNET_ATS_SchedulingHandle;
250
251/**
252 * Opaque session handle, defined by plugins. Contents not known to ATS.
253 */
254struct GNUNET_ATS_Session;
255
256
257/**
258 * Signature of a function called by ATS with the current bandwidth
259 * and address preferences as determined by ATS. If our connection
260 * to ATS dies and thus all suggestions become invalid, this function
261 * is called ONCE with all arguments (except @a cls) being NULL/0.
262 *
263 * @param cls closure
264 * @param peer for which we suggest an address, NULL if ATS connection died
265 * @param address suggested address (including peer identity of the peer),
266 * may be NULL to signal disconnect from peer
267 * @param session session to use, NULL to establish a new outgoing session
268 * @param bandwidth_out assigned outbound bandwidth for the connection,
269 * 0 to signal disconnect
270 * @param bandwidth_in assigned inbound bandwidth for the connection,
271 * 0 to signal disconnect
272 */
273typedef void
274(*GNUNET_ATS_AddressSuggestionCallback) (void *cls,
275 const struct GNUNET_PeerIdentity *peer,
276 const struct
277 GNUNET_HELLO_Address *address,
278 struct GNUNET_ATS_Session *session,
279 struct GNUNET_BANDWIDTH_Value32NBO
280 bandwidth_out,
281 struct GNUNET_BANDWIDTH_Value32NBO
282 bandwidth_in);
283
284
285/**
286 * Initialize the ATS scheduling subsystem.
287 *
288 * @param cfg configuration to use
289 * @param suggest_cb notification to call whenever the suggestation changed
290 * @param suggest_cb_cls closure for @a suggest_cb
291 * @return ats context
292 */
293struct GNUNET_ATS_SchedulingHandle *
294GNUNET_ATS_scheduling_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
295 GNUNET_ATS_AddressSuggestionCallback suggest_cb,
296 void *suggest_cb_cls) __attribute__((deprecated));
297
298
299/**
300 * Client is done with ATS scheduling, release resources.
301 *
302 * @param sh handle to release
303 */
304void
305GNUNET_ATS_scheduling_done (struct
306 GNUNET_ATS_SchedulingHandle *sh) __attribute__(
307 (deprecated));
308
309
310/**
311 * Handle used within ATS to track an address.
312 */
313struct GNUNET_ATS_AddressRecord;
314
315
316/**
317 * We have a new address ATS should know. Addresses have to be added with this
318 * function before they can be: updated, set in use and destroyed
319 *
320 * @param sh handle
321 * @param address the address
322 * @param session session handle (if available, e.g for incoming connections)
323 * @param prop performance data for the address
324 * @return handle to the address representation inside ATS, NULL
325 * on error (i.e. ATS knows this exact address already, or
326 * address is invalid)
327 */
328struct GNUNET_ATS_AddressRecord *
329GNUNET_ATS_address_add (struct GNUNET_ATS_SchedulingHandle *sh,
330 const struct GNUNET_HELLO_Address *address,
331 struct GNUNET_ATS_Session *session,
332 const struct GNUNET_ATS_Properties *prop) __attribute__(
333 (deprecated));
334
335
336/**
337 * An address was used to initiate a session.
338 *
339 * @param ar address record to update information for
340 * @param session session handle
341 */
342void
343GNUNET_ATS_address_add_session (struct GNUNET_ATS_AddressRecord *ar,
344 struct GNUNET_ATS_Session *session)
345__attribute__((deprecated));
346
347
348/**
349 * A @a session was destroyed, disassociate it from the given address
350 * record. If this was an incoming address, destroys the address as
351 * well.
352 *
353 * @param ar address record to update information for
354 * @param session session handle
355 * @return #GNUNET_YES if the @a ar was destroyed because
356 * it was an incoming address,
357 * #GNUNET_NO if the @a ar was kept because we can
358 * use it still to establish a new session
359 */
360int
361GNUNET_ATS_address_del_session (struct GNUNET_ATS_AddressRecord *ar,
362 struct GNUNET_ATS_Session *session)
363__attribute__((deprecated));
364
365
366/**
367 * We have updated performance statistics for a given address. Note
368 * that this function can be called for addresses that are currently
369 * in use as well as addresses that are valid but not actively in use.
370 * Furthermore, the peer may not even be connected to us right now (@a
371 * session value of NULL used to signal disconnect, or somehow we
372 * otherwise got updated on @a ats information). Based on the
373 * information provided, ATS may update bandwidth assignments and
374 * suggest to switch addresses.
375 *
376 * @param ar address record to update information for
377 * @param prop performance data for the address
378 */
379void
380GNUNET_ATS_address_update (struct GNUNET_ATS_AddressRecord *ar,
381 const struct
382 GNUNET_ATS_Properties *prop) __attribute__(
383 (deprecated));
384
385
386/**
387 * An address got destroyed, stop using it as a valid address.
388 *
389 * @param ar address record to destroy, its validation has
390 * expired and ATS may no longer use it
391 */
392void
393GNUNET_ATS_address_destroy (struct GNUNET_ATS_AddressRecord *ar) __attribute__(
394 (deprecated));
395
396
397/* ******************************** Performance API ***************************** */
398
399/**
400 * ATS Handle to obtain and/or modify performance information.
401 */
402struct GNUNET_ATS_PerformanceHandle;
403
404/**
405 * Signature of a function that is called with QoS information about an address.
406 *
407 * @param cls closure
408 * @param address the address, NULL if ATS service was disconnected or
409 * when the iteration is completed in the case of
410 * #GNUNET_ATS_performance_list_addresses()
411 * @param address_active #GNUNET_YES if this address is actively used
412 * to maintain a connection to a peer;
413 * #GNUNET_NO if the address is not actively used;
414 * #GNUNET_SYSERR if this address is no longer available for ATS
415 * @param bandwidth_out assigned outbound bandwidth for the connection
416 * @param bandwidth_in assigned inbound bandwidth for the connection
417 * @param prop performance data for the address
418 */
419typedef void
420(*GNUNET_ATS_AddressInformationCallback) (void *cls,
421 const struct
422 GNUNET_HELLO_Address *address,
423 int address_active,
424 struct GNUNET_BANDWIDTH_Value32NBO
425 bandwidth_out,
426 struct GNUNET_BANDWIDTH_Value32NBO
427 bandwidth_in,
428 const struct
429 GNUNET_ATS_Properties *prop);
430
431
432/**
433 * Handle for an address listing operation
434 */
435struct GNUNET_ATS_AddressListHandle;
436
437
438/**
439 * Get handle to access performance API of the ATS subsystem.
440 *
441 * @param cfg configuration to use
442 * @param addr_info_cb callback called when performance characteristics for
443 * an address change
444 * @param addr_info_cb_cls closure for @a addr_info_cb
445 * @return ats performance context
446 */
447struct GNUNET_ATS_PerformanceHandle *
448GNUNET_ATS_performance_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
449 GNUNET_ATS_AddressInformationCallback addr_info_cb,
450 void *addr_info_cb_cls) __attribute__(
451 (deprecated));
452
453
454/**
455 * Get information about addresses known to the ATS subsystem.
456 *
457 * @param ph the performance handle to use
458 * @param peer peer idm can be NULL for all peers
459 * @param all #GNUNET_YES to get information about all addresses or #GNUNET_NO to
460 * get only address currently used
461 * @param infocb callback to call with the addresses,
462 * will callback with address == NULL when done
463 * @param infocb_cls closure for @a infocb
464 * @return handle to abort the operation
465 */
466struct GNUNET_ATS_AddressListHandle *
467GNUNET_ATS_performance_list_addresses (struct GNUNET_ATS_PerformanceHandle *ph,
468 const struct GNUNET_PeerIdentity *peer,
469 int all,
470 GNUNET_ATS_AddressInformationCallback
471 infocb,
472 void *infocb_cls) __attribute__(
473 (deprecated));
474
475
476/**
477 * Cancel a pending address listing operation
478 *
479 * @param alh the `struct GNUNET_ATS_AddressListHandle` handle to cancel
480 */
481void
482GNUNET_ATS_performance_list_addresses_cancel (struct
483 GNUNET_ATS_AddressListHandle *alh)
484__attribute__((deprecated));
485
486
487/**
488 * Client is done using the ATS performance subsystem, release resources.
489 *
490 * @param ph handle
491 */
492void
493GNUNET_ATS_performance_done (struct
494 GNUNET_ATS_PerformanceHandle *ph) __attribute__(
495 (deprecated));
496
497
498/**
499 * Function called with reservation result.
500 *
501 * @param cls closure
502 * @param peer identifies the peer
503 * @param amount set to the amount that was actually reserved or unreserved;
504 * either the full requested amount or zero (no partial reservations)
505 * @param res_delay if the reservation could not be satisfied (amount was 0), how
506 * long should the client wait until re-trying?
507 */
508typedef void
509(*GNUNET_ATS_ReservationCallback) (void *cls,
510 const struct GNUNET_PeerIdentity *peer,
511 int32_t amount,
512 struct GNUNET_TIME_Relative res_delay);
513
514
515/**
516 * Context that can be used to cancel a peer information request.
517 */
518struct GNUNET_ATS_ReservationContext;
519
520
521/**
522 * Reserve inbound bandwidth from the given peer. ATS will look at
523 * the current amount of traffic we receive from the peer and ensure
524 * that the peer could add 'amount' of data to its stream.
525 *
526 * @param ph performance handle
527 * @param peer identifies the peer
528 * @param amount reserve N bytes for receiving, negative
529 * amounts can be used to undo a (recent) reservation;
530 * @param rcb function to call with the resulting reservation information
531 * @param rcb_cls closure for @a rcb
532 * @return NULL on error
533 * @deprecated will be replaced soon
534 */
535struct GNUNET_ATS_ReservationContext *
536GNUNET_ATS_reserve_bandwidth (struct GNUNET_ATS_PerformanceHandle *ph,
537 const struct GNUNET_PeerIdentity *peer,
538 int32_t amount,
539 GNUNET_ATS_ReservationCallback rcb,
540 void *rcb_cls) __attribute__((deprecated));
541
542
543/**
544 * Cancel request for reserving bandwidth.
545 *
546 * @param rc context returned by the original #GNUNET_ATS_reserve_bandwidth() call
547 */
548void
549GNUNET_ATS_reserve_bandwidth_cancel (struct
550 GNUNET_ATS_ReservationContext *rc)
551__attribute__((deprecated));
552
553
554/**
555 * ATS preference types as array initializer
556 */
557#define GNUNET_ATS_PreferenceType { GNUNET_ATS_PREFERENCE_BANDWIDTH, \
558 GNUNET_ATS_PREFERENCE_LATENCY, \
559 GNUNET_ATS_PREFERENCE_END }
560
561/**
562 * ATS preference types as string array initializer
563 */
564#define GNUNET_ATS_PreferenceTypeString { "BANDWIDTH", "LATENCY", "END" }
565
566/**
567 * Enum defining all known preference categories.
568 */
569enum GNUNET_ATS_PreferenceKind
570{
571 /**
572 * Change the peer's bandwidth value (value per byte of bandwidth in
573 * the goal function) to the given amount. The argument is followed
574 * by a double value giving the desired value (can be negative).
575 * Preference changes are forgotten if peers disconnect.
576 */
577 GNUNET_ATS_PREFERENCE_BANDWIDTH = 0,
578
579 /**
580 * Change the peer's latency value to the given amount. The
581 * argument is followed by a double value giving the desired value
582 * (can be negative). The absolute score in the goal function is
583 * the inverse of the latency in microseconds (minimum: 1
584 * microsecond) multiplied by the latency preferences.
585 */
586 GNUNET_ATS_PREFERENCE_LATENCY = 1,
587
588 /**
589 * End of preference list.
590 */
591 GNUNET_ATS_PREFERENCE_END = 2
592};
593
594
595/**
596 * Convert an `enum GNUNET_ATS_PreferenceType` to a string
597 *
598 * @param type the preference type
599 * @return a string or NULL if invalid
600 */
601const char *
602GNUNET_ATS_print_preference_type (enum GNUNET_ATS_PreferenceKind
603 type) __attribute__((deprecated));
604
605
606/**
607 * Change preferences for the given peer. Preference changes are
608 * forgotten if peers disconnect.
609 *
610 * @param ph performance handle
611 * @param peer identifies the peer
612 * @param ... #GNUNET_ATS_PREFERENCE_END-terminated specification of the
613 * desired changes
614 */
615void
616GNUNET_ATS_performance_change_preference (struct
617 GNUNET_ATS_PerformanceHandle *ph,
618 const struct
619 GNUNET_PeerIdentity *peer,
620 ...) __attribute__((deprecated));
621
622
623/**
624 * Application feedback on how good preference requirements are fulfilled
625 * for the preferences included in the given time scope [now - scope .. now]
626 *
627 * An application notifies ATS if (and only if) it has feedback information
628 * for specific properties. This values are valid until the feedback scores are
629 * updated by the application.
630 *
631 * If the application has no feedback for this preference kind the application
632 * will not explicitly call for this property and will not include it in this
633 * function call.
634 *
635 * @param ph performance handle
636 * @param scope the time interval this valid for: [now - scope .. now]
637 * @param peer identifies the peer
638 * @param ... #GNUNET_ATS_PREFERENCE_END-terminated specification of the desired changes
639 */
640void
641GNUNET_ATS_performance_give_feedback (struct GNUNET_ATS_PerformanceHandle *ph,
642 const struct GNUNET_PeerIdentity *peer,
643 const struct GNUNET_TIME_Relative scope,
644 ...) __attribute__((deprecated));
645
646#endif
647
648/** @} */ /* end of group */
649
650/** @} */ /* end of Backbone addition */
651
652/* end of file gnunet-service-transport_ats.h */
generated by cgit v1.2.3 (git 2.39.1) at 2024-05-17 02:57:25 +0000