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