diff options
author | Christian Grothoff <christian@grothoff.org> | 2018-11-22 22:46:43 +0100 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2018-11-22 22:46:43 +0100 |
commit | fbc5f3876a2ed52f18e2a2810e3cdda497cc99ea (patch) | |
tree | d01a9a8f202dd53a6ff6901c190d4d7031da1baa /src/include/gnunet_ats_transport_service.h | |
parent | c87f73a07df468eccedbe1fdfa82bdd5b633a0d5 (diff) | |
download | gnunet-fbc5f3876a2ed52f18e2a2810e3cdda497cc99ea.tar.gz gnunet-fbc5f3876a2ed52f18e2a2810e3cdda497cc99ea.zip |
add design sketch for new ATS API
Diffstat (limited to 'src/include/gnunet_ats_transport_service.h')
-rw-r--r-- | src/include/gnunet_ats_transport_service.h | 238 |
1 files changed, 238 insertions, 0 deletions
diff --git a/src/include/gnunet_ats_transport_service.h b/src/include/gnunet_ats_transport_service.h new file mode 100644 index 000000000..b069f8b24 --- /dev/null +++ b/src/include/gnunet_ats_transport_service.h | |||
@@ -0,0 +1,238 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | Copyright (C) 2010-2015, 2018 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 | /** | ||
19 | * @file | ||
20 | * Bandwidth allocation API for the transport service | ||
21 | * | ||
22 | * @author Christian Grothoff | ||
23 | * @author Matthias Wachs | ||
24 | * | ||
25 | * @defgroup ats ATS service | ||
26 | * Bandwidth allocation for transport service | ||
27 | * | ||
28 | * @see [Documentation](https://gnunet.org/ats-subsystem) | ||
29 | * | ||
30 | * @{ | ||
31 | */ | ||
32 | #ifndef GNUNET_ATS_TRANSPORT_SERVICE_H | ||
33 | #define GNUNET_ATS_TRANSPORT_SERVICE_H | ||
34 | |||
35 | #include "gnunet_constants.h" | ||
36 | #include "gnunet_util_lib.h" | ||
37 | #include "gnunet_nt_lib.h" | ||
38 | #include "gnunet_transport_communication_service.h" | ||
39 | |||
40 | |||
41 | /** | ||
42 | * ATS performance characteristics for an address. | ||
43 | */ | ||
44 | struct GNUNET_ATS_Properties | ||
45 | { | ||
46 | |||
47 | /** | ||
48 | * Delay. Time between when the time packet is sent and the packet | ||
49 | * arrives. FOREVER if we did not (successfully) measure yet. | ||
50 | */ | ||
51 | struct GNUNET_TIME_Relative delay; | ||
52 | |||
53 | /** | ||
54 | * Confirmed successful payload on this connection from this peer to | ||
55 | * the other peer. | ||
56 | * | ||
57 | * Unit: [bytes/second] | ||
58 | */ | ||
59 | uint32_t goodput_out; | ||
60 | |||
61 | /** | ||
62 | * Confirmed useful payload on this connection to this peer from | ||
63 | * the other peer. | ||
64 | * | ||
65 | * Unit: [bytes/second] | ||
66 | */ | ||
67 | uint32_t goodput_in; | ||
68 | |||
69 | /** | ||
70 | * Actual traffic on this connection from this peer to the other peer. | ||
71 | * Includes transport overhead. | ||
72 | * | ||
73 | * Unit: [bytes/second] | ||
74 | */ | ||
75 | uint32_t utilization_out; | ||
76 | |||
77 | /** | ||
78 | * Actual traffic on this connection from the other peer to this peer. | ||
79 | * Includes transport overhead. | ||
80 | * | ||
81 | * Unit: [bytes/second] | ||
82 | */ | ||
83 | uint32_t utilization_in; | ||
84 | |||
85 | /** | ||
86 | * Distance on network layer (required for distance-vector routing) | ||
87 | * in hops. Zero for direct connections (i.e. plain TCP/UDP). | ||
88 | */ | ||
89 | uint32_t distance; | ||
90 | |||
91 | /** | ||
92 | * MTU of the network layer, UINT32_MAX for no MTU (stream). | ||
93 | * | ||
94 | * Unit: [bytes] | ||
95 | */ | ||
96 | uint32_t mtu; | ||
97 | |||
98 | /** | ||
99 | * Which network scope does the respective address belong to? | ||
100 | */ | ||
101 | enum GNUNET_NetworkType nt; | ||
102 | |||
103 | /** | ||
104 | * What characteristics does this communicator have? | ||
105 | */ | ||
106 | enum GNUNET_TRANSPORT_CommunicatorCharacteristics cc; | ||
107 | |||
108 | }; | ||
109 | |||
110 | |||
111 | /* ******************************** Scheduling API ***************************** */ | ||
112 | |||
113 | /** | ||
114 | * Handle to the ATS subsystem for bandwidth/transport scheduling information. | ||
115 | */ | ||
116 | struct GNUNET_ATS_SchedulingHandle; | ||
117 | |||
118 | /** | ||
119 | * Opaque session handle, to be defined by transport. Contents not known to ATS. | ||
120 | */ | ||
121 | struct GNUNET_ATS_Session; | ||
122 | |||
123 | |||
124 | /** | ||
125 | * Signature of a function called by ATS with the current bandwidth | ||
126 | * allocation to be used as determined by ATS. | ||
127 | * | ||
128 | * @param cls closure | ||
129 | * @param session session this is about | ||
130 | * @param bandwidth_out assigned outbound bandwidth for the connection, | ||
131 | * 0 to signal disconnect | ||
132 | * @param bandwidth_in assigned inbound bandwidth for the connection, | ||
133 | * 0 to signal disconnect | ||
134 | */ | ||
135 | typedef void | ||
136 | (*GNUNET_ATS_AllocationCallback) (void *cls, | ||
137 | struct GNUNET_ATS_Session *session, | ||
138 | struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out, | ||
139 | struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in); | ||
140 | |||
141 | |||
142 | /** | ||
143 | * Signature of a function called by ATS suggesting transport to | ||
144 | * try connecting with a particular address. | ||
145 | * | ||
146 | * @param cls closure | ||
147 | * @param pid target peer | ||
148 | * @param address the address to try | ||
149 | */ | ||
150 | typedef void | ||
151 | (*GNUNET_ATS_SuggestionCallback) (void *cls, | ||
152 | const struct GNUNET_PeerIdentity *pid, | ||
153 | const char *address); | ||
154 | |||
155 | |||
156 | /** | ||
157 | * Initialize the ATS scheduling subsystem. | ||
158 | * | ||
159 | * @param cfg configuration to use | ||
160 | * @param alloc_cb notification to call whenever the allocation changed | ||
161 | * @param alloc_cb_cls closure for @a alloc_cb | ||
162 | * @param suggest_cb notification to call whenever the suggestation is made | ||
163 | * @param suggest_cb_cls closure for @a suggest_cb | ||
164 | * @return ats context | ||
165 | */ | ||
166 | struct GNUNET_ATS_SchedulingHandle * | ||
167 | GNUNET_ATS_scheduling_init (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
168 | GNUNET_ATS_AllocationCallback alloc_cb, | ||
169 | void *alloc_cb_cls); | ||
170 | GNUNET_ATS_SuggestionCallback suggest_cb, | ||
171 | void *suggest_cb_cls); | ||
172 | |||
173 | |||
174 | /** | ||
175 | * Client is done with ATS scheduling, release resources. | ||
176 | * | ||
177 | * @param sh handle to release | ||
178 | */ | ||
179 | void | ||
180 | GNUNET_ATS_scheduling_done (struct GNUNET_ATS_SchedulingHandle *sh); | ||
181 | |||
182 | |||
183 | /** | ||
184 | * Handle used within ATS to track an address. | ||
185 | */ | ||
186 | struct GNUNET_ATS_AddressRecord; | ||
187 | |||
188 | |||
189 | /** | ||
190 | * We have a new address ATS should know. Addresses have to be added with this | ||
191 | * function before they can be: updated, set in use and destroyed | ||
192 | * | ||
193 | * @param sh handle | ||
194 | * @param pid peer we connected to | ||
195 | * @param address the address (human readable version), NULL if | ||
196 | * the session is inbound-only | ||
197 | * @param session transport-internal handle for the address/queue | ||
198 | * @param prop performance data for the address | ||
199 | * @return handle to the address representation inside ATS, NULL | ||
200 | * on error (i.e. ATS knows this exact address already, or | ||
201 | * address is invalid) | ||
202 | */ | ||
203 | struct GNUNET_ATS_AddressRecord * | ||
204 | GNUNET_ATS_address_add (struct GNUNET_ATS_SchedulingHandle *sh, | ||
205 | const struct GNUNET_PeerIdentity *pid, | ||
206 | const char *address, | ||
207 | struct GNUNET_ATS_Session *session, | ||
208 | const struct GNUNET_ATS_Properties *prop); | ||
209 | |||
210 | |||
211 | /** | ||
212 | * We have updated performance statistics for a given address. Based | ||
213 | * on the information provided, ATS may update bandwidth assignments. | ||
214 | * | ||
215 | * @param ar address record to update information for | ||
216 | * @param prop performance data for the address | ||
217 | */ | ||
218 | void | ||
219 | GNUNET_ATS_address_update (struct GNUNET_ATS_AddressRecord *ar, | ||
220 | const struct GNUNET_ATS_Properties *prop); | ||
221 | |||
222 | |||
223 | /** | ||
224 | * A session was destroyed, ATS should now schedule and | ||
225 | * allocate under the assumption that this @a ar is no | ||
226 | * longer in use. | ||
227 | * | ||
228 | * @param ar address record to drop | ||
229 | */ | ||
230 | void | ||
231 | GNUNET_ATS_address_del (struct GNUNET_ATS_AddressRecord *ar); | ||
232 | |||
233 | |||
234 | #endif | ||
235 | |||
236 | /** @} */ /* end of group */ | ||
237 | |||
238 | /* end of file gnunet-service-transport_ats.h */ | ||