aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_ats_transport_service.h
blob: b5848a36abd67db7378414036cacd592a0ec2b14 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
/*
   This file is part of GNUnet.
   Copyright (C) 2010-2015, 2018 GNUnet e.V.

   GNUnet is free software: you can redistribute it and/or modify it
   under the terms of the GNU Affero General Public License as published
   by the Free Software Foundation, either version 3 of the License,
   or (at your option) any later version.

   GNUnet is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Affero General Public License for more details.

   You should have received a copy of the GNU Affero General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.

     SPDX-License-Identifier: AGPL3.0-or-later
 */
/**
 * @file
 * Bandwidth allocation API for the transport service
 *
 * @author Christian Grothoff
 * @author Matthias Wachs
 *
 * @defgroup ats  ATS service
 * Bandwidth allocation for transport service
 *
 * @see [Documentation](https://gnunet.org/ats-subsystem)
 *
 * @{
 */
#ifndef GNUNET_ATS_TRANSPORT_SERVICE_H
#define GNUNET_ATS_TRANSPORT_SERVICE_H

#include "gnunet_constants.h"
#include "gnunet_util_lib.h"
#include "gnunet_nt_lib.h"
#include "gnunet_transport_communication_service.h"


/**
 * ATS performance characteristics for a session.
 */
struct GNUNET_ATS_Properties
{
  /**
   * Delay.  Time between when the time packet is sent and the packet
   * arrives.  FOREVER if we did not (successfully) measure yet.
   */
  struct GNUNET_TIME_Relative delay;

  /**
   * Confirmed successful payload on this connection from this peer to
   * the other peer.
   *
   * Unit: [bytes/second]
   */
  uint32_t goodput_out;

  /**
   * Confirmed useful payload on this connection to this peer from
   * the other peer.
   *
   * Unit: [bytes/second]
   */
  uint32_t goodput_in;

  /**
   * Actual traffic on this connection from this peer to the other peer.
   * Includes transport overhead.
   *
   * Unit: [bytes/second]
   */
  uint32_t utilization_out;

  /**
   * Actual traffic on this connection from the other peer to this peer.
   * Includes transport overhead.
   *
   * Unit: [bytes/second]
   */
  uint32_t utilization_in;

  /**
   * Distance on network layer (required for distance-vector routing)
   * in hops.  Zero for direct connections (i.e. plain TCP/UDP).
   */
  uint32_t distance;

  /**
   * MTU of the network layer, UINT32_MAX for no MTU (stream).
   *
   * Unit: [bytes]
   */
  uint32_t mtu;

  /**
   * Which network scope does the respective address belong to?
   */
  enum GNUNET_NetworkType nt;

  /**
   * What characteristics does this communicator have?
   */
  enum GNUNET_TRANSPORT_CommunicatorCharacteristics cc;
};


/* ******************************** Transport API ***************************** */

/**
 * Handle to the ATS subsystem for bandwidth/transport transport information.
 */
struct GNUNET_ATS_TransportHandle;

/**
 * Opaque session handle, to be defined by transport.  Contents not known to ATS.
 */
struct GNUNET_ATS_Session;


/**
 * Signature of a function called by ATS with the current bandwidth
 * allocation to be used as determined by ATS.
 *
 * @param cls closure
 * @param session session this is about
 * @param bandwidth_out assigned outbound bandwidth for the connection,
 *        0 to signal disconnect
 * @param bandwidth_in assigned inbound bandwidth for the connection,
 *        0 to signal disconnect
 */
typedef void
(*GNUNET_ATS_AllocationCallback) (void *cls,
                                  struct GNUNET_ATS_Session *session,
                                  struct GNUNET_BANDWIDTH_Value32NBO
                                  bandwidth_out,
                                  struct GNUNET_BANDWIDTH_Value32NBO
                                  bandwidth_in);


/**
 * Signature of a function called by ATS suggesting transport to
 * try connecting with a particular address.
 *
 * @param cls closure
 * @param pid target peer
 * @param address the address to try
 */
typedef void
(*GNUNET_ATS_SuggestionCallback) (void *cls,
                                  const struct GNUNET_PeerIdentity *pid,
                                  const char *address);


/**
 * Initialize the ATS transport subsystem.
 *
 * @param cfg configuration to use
 * @param alloc_cb notification to call whenever the allocation changed
 * @param alloc_cb_cls closure for @a alloc_cb
 * @param suggest_cb notification to call whenever the suggestation is made
 * @param suggest_cb_cls closure for @a suggest_cb
 * @return ats context
 */
struct GNUNET_ATS_TransportHandle *
GNUNET_ATS_transport_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
                           GNUNET_ATS_AllocationCallback alloc_cb,
                           void *alloc_cb_cls,
                           GNUNET_ATS_SuggestionCallback suggest_cb,
                           void *suggest_cb_cls);


/**
 * Client is done with ATS transport, release resources.
 *
 * @param ath handle to release
 */
void
GNUNET_ATS_transport_done (struct GNUNET_ATS_TransportHandle *ath);


/**
 * Handle used within ATS to track an session.
 */
struct GNUNET_ATS_SessionRecord;


/**
 * We have a new session ATS should know. Sessiones have to be added with this
 * function before they can be: updated, set in use and destroyed
 *
 * @param ath handle
 * @param pid peer we connected to
 * @param address the address (human readable version),
 * @param session transport-internal handle for the session/queue, NULL if
 *        the session is inbound-only
 * @param prop performance data for the session
 * @return handle to the session representation inside ATS, NULL
 *         on error (i.e. ATS knows this exact session already, or
 *         session is invalid)
 */
struct GNUNET_ATS_SessionRecord *
GNUNET_ATS_session_add (struct GNUNET_ATS_TransportHandle *ath,
                        const struct GNUNET_PeerIdentity *pid,
                        const char *address,
                        struct GNUNET_ATS_Session *session,
                        const struct GNUNET_ATS_Properties *prop);


/**
 * We have updated performance statistics for a given session.  Based
 * on the information provided, ATS may update bandwidth assignments.
 *
 * @param ar session record to update information for
 * @param prop performance data for the session
 */
void
GNUNET_ATS_session_update (struct GNUNET_ATS_SessionRecord *ar,
                           const struct GNUNET_ATS_Properties *prop);


/**
 * A session was destroyed, ATS should now schedule and
 * allocate under the assumption that this @a ar is no
 * longer in use.
 *
 * @param ar session record to drop
 */
void
GNUNET_ATS_session_del (struct GNUNET_ATS_SessionRecord *ar);


#endif

/** @} */  /* end of group */

/* end of file gnunet-service-transport_ats.h */