1 /*
2  *  Copyright (c) 2018 The WebRTC project authors. All Rights Reserved.
3  *
4  *  Use of this source code is governed by a BSD-style license
5  *  that can be found in the LICENSE file in the root of the source
6  *  tree. An additional intellectual property rights grant can be found
7  *  in the file PATENTS.  All contributing project authors may
8  *  be found in the AUTHORS file in the root of the source tree.
9  */
10 
11 #ifndef API_TRANSPORT_NETWORK_TYPES_H_
12 #define API_TRANSPORT_NETWORK_TYPES_H_
13 #include <stdint.h>
14 
15 #include <vector>
16 
17 #include "absl/types/optional.h"
18 #include "api/units/data_rate.h"
19 #include "api/units/data_size.h"
20 #include "api/units/time_delta.h"
21 #include "api/units/timestamp.h"
22 #include "rtc_base/deprecation.h"
23 
24 namespace webrtc {
25 
26 // Configuration
27 
28 // Represents constraints and rates related to the currently enabled streams.
29 // This is used as input to the congestion controller via the StreamsConfig
30 // struct.
31 struct BitrateAllocationLimits {
32   // The total minimum send bitrate required by all sending streams.
33   DataRate min_allocatable_rate = DataRate::Zero();
34   // The total maximum allocatable bitrate for all currently available streams.
35   DataRate max_allocatable_rate = DataRate::Zero();
36   // The max bitrate to use for padding. The sum of the per-stream max padding
37   // rate.
38   DataRate max_padding_rate = DataRate::Zero();
39 };
40 
41 // Use StreamsConfig for information about streams that is required for specific
42 // adjustments to the algorithms in network controllers. Especially useful
43 // for experiments.
44 struct StreamsConfig {
45   StreamsConfig();
46   StreamsConfig(const StreamsConfig&);
47   ~StreamsConfig();
48   Timestamp at_time = Timestamp::PlusInfinity();
49   absl::optional<bool> requests_alr_probing;
50   absl::optional<double> pacing_factor;
51 
52   // TODO(srte): Use BitrateAllocationLimits here.
53   absl::optional<DataRate> min_total_allocated_bitrate;
54   absl::optional<DataRate> max_padding_rate;
55   absl::optional<DataRate> max_total_allocated_bitrate;
56 };
57 
58 struct TargetRateConstraints {
59   TargetRateConstraints();
60   TargetRateConstraints(const TargetRateConstraints&);
61   ~TargetRateConstraints();
62   Timestamp at_time = Timestamp::PlusInfinity();
63   absl::optional<DataRate> min_data_rate;
64   absl::optional<DataRate> max_data_rate;
65   // The initial bandwidth estimate to base target rate on. This should be used
66   // as the basis for initial OnTargetTransferRate and OnPacerConfig callbacks.
67   absl::optional<DataRate> starting_rate;
68 };
69 
70 // Send side information
71 
72 struct NetworkAvailability {
73   Timestamp at_time = Timestamp::PlusInfinity();
74   bool network_available = false;
75 };
76 
77 struct NetworkRouteChange {
78   NetworkRouteChange();
79   NetworkRouteChange(const NetworkRouteChange&);
80   ~NetworkRouteChange();
81   Timestamp at_time = Timestamp::PlusInfinity();
82   // The TargetRateConstraints are set here so they can be changed synchronously
83   // when network route changes.
84   TargetRateConstraints constraints;
85 };
86 
87 struct PacedPacketInfo {
88   PacedPacketInfo();
89   PacedPacketInfo(int probe_cluster_id,
90                   int probe_cluster_min_probes,
91                   int probe_cluster_min_bytes);
92 
93   bool operator==(const PacedPacketInfo& rhs) const;
94 
95   // TODO(srte): Move probing info to a separate, optional struct.
96   static constexpr int kNotAProbe = -1;
97   int send_bitrate_bps = -1;
98   int probe_cluster_id = kNotAProbe;
99   int probe_cluster_min_probes = -1;
100   int probe_cluster_min_bytes = -1;
101   int probe_cluster_bytes_sent = 0;
102 };
103 
104 struct SentPacket {
105   Timestamp send_time = Timestamp::PlusInfinity();
106   // Size of packet with overhead up to IP layer.
107   DataSize size = DataSize::Zero();
108   // Size of preceeding packets that are not part of feedback.
109   DataSize prior_unacked_data = DataSize::Zero();
110   // Probe cluster id and parameters including bitrate, number of packets and
111   // number of bytes.
112   PacedPacketInfo pacing_info;
113   // True if the packet is an audio packet, false for video, padding, RTX etc.
114   bool audio = false;
115   // Transport independent sequence number, any tracked packet should have a
116   // sequence number that is unique over the whole call and increasing by 1 for
117   // each packet.
118   int64_t sequence_number;
119   // Tracked data in flight when the packet was sent, excluding unacked data.
120   DataSize data_in_flight = DataSize::Zero();
121 };
122 
123 struct ReceivedPacket {
124   Timestamp send_time = Timestamp::MinusInfinity();
125   Timestamp receive_time = Timestamp::PlusInfinity();
126   DataSize size = DataSize::Zero();
127 };
128 
129 // Transport level feedback
130 
131 struct RemoteBitrateReport {
132   Timestamp receive_time = Timestamp::PlusInfinity();
133   DataRate bandwidth = DataRate::Infinity();
134 };
135 
136 struct RoundTripTimeUpdate {
137   Timestamp receive_time = Timestamp::PlusInfinity();
138   TimeDelta round_trip_time = TimeDelta::PlusInfinity();
139   bool smoothed = false;
140 };
141 
142 struct TransportLossReport {
143   Timestamp receive_time = Timestamp::PlusInfinity();
144   Timestamp start_time = Timestamp::PlusInfinity();
145   Timestamp end_time = Timestamp::PlusInfinity();
146   uint64_t packets_lost_delta = 0;
147   uint64_t packets_received_delta = 0;
148 };
149 
150 // Packet level feedback
151 
152 struct PacketResult {
153   class ReceiveTimeOrder {
154    public:
155     bool operator()(const PacketResult& lhs, const PacketResult& rhs);
156   };
157 
158   PacketResult();
159   PacketResult(const PacketResult&);
160   ~PacketResult();
161 
162   SentPacket sent_packet;
163   Timestamp receive_time = Timestamp::PlusInfinity();
164 };
165 
166 struct TransportPacketsFeedback {
167   TransportPacketsFeedback();
168   TransportPacketsFeedback(const TransportPacketsFeedback& other);
169   ~TransportPacketsFeedback();
170 
171   Timestamp feedback_time = Timestamp::PlusInfinity();
172   Timestamp first_unacked_send_time = Timestamp::PlusInfinity();
173   DataSize data_in_flight = DataSize::Zero();
174   DataSize prior_in_flight = DataSize::Zero();
175   std::vector<PacketResult> packet_feedbacks;
176 
177   // Arrival times for messages without send time information.
178   std::vector<Timestamp> sendless_arrival_times;
179 
180   std::vector<PacketResult> ReceivedWithSendInfo() const;
181   std::vector<PacketResult> LostWithSendInfo() const;
182   std::vector<PacketResult> PacketsWithFeedback() const;
183   std::vector<PacketResult> SortedByReceiveTime() const;
184 };
185 
186 // Network estimation
187 
188 struct NetworkEstimate {
189   Timestamp at_time = Timestamp::PlusInfinity();
190   // Deprecated, use TargetTransferRate::target_rate instead.
191   DataRate bandwidth = DataRate::Infinity();
192   TimeDelta round_trip_time = TimeDelta::PlusInfinity();
193   TimeDelta bwe_period = TimeDelta::PlusInfinity();
194 
195   float loss_rate_ratio = 0;
196 };
197 
198 // Network control
199 
200 struct PacerConfig {
201   Timestamp at_time = Timestamp::PlusInfinity();
202   // Pacer should send at most data_window data over time_window duration.
203   DataSize data_window = DataSize::Infinity();
204   TimeDelta time_window = TimeDelta::PlusInfinity();
205   // Pacer should send at least pad_window data over time_window duration.
206   DataSize pad_window = DataSize::Zero();
data_ratePacerConfig207   DataRate data_rate() const { return data_window / time_window; }
pad_ratePacerConfig208   DataRate pad_rate() const { return pad_window / time_window; }
209 };
210 
211 struct ProbeClusterConfig {
212   Timestamp at_time = Timestamp::PlusInfinity();
213   DataRate target_data_rate = DataRate::Zero();
214   TimeDelta target_duration = TimeDelta::Zero();
215   int32_t target_probe_count = 0;
216   int32_t id = 0;
217 };
218 
219 struct TargetTransferRate {
220   Timestamp at_time = Timestamp::PlusInfinity();
221   // The estimate on which the target rate is based on.
222   NetworkEstimate network_estimate;
223   DataRate target_rate = DataRate::Zero();
224   DataRate stable_target_rate = DataRate::Zero();
225   double cwnd_reduce_ratio = 0;
226 };
227 
228 // Contains updates of network controller comand state. Using optionals to
229 // indicate whether a member has been updated. The array of probe clusters
230 // should be used to send out probes if not empty.
231 struct NetworkControlUpdate {
232   NetworkControlUpdate();
233   NetworkControlUpdate(const NetworkControlUpdate&);
234   ~NetworkControlUpdate();
235   absl::optional<DataSize> congestion_window;
236   absl::optional<PacerConfig> pacer_config;
237   std::vector<ProbeClusterConfig> probe_cluster_configs;
238   absl::optional<TargetTransferRate> target_rate;
239 };
240 
241 // Process control
242 struct ProcessInterval {
243   ProcessInterval();
244   ProcessInterval(const ProcessInterval&);
245   ~ProcessInterval();
246   Timestamp at_time = Timestamp::PlusInfinity();
247   absl::optional<DataSize> pacer_queue;
248 };
249 
250 // Under development, subject to change without notice.
251 struct NetworkStateEstimate {
252   double confidence = NAN;
253   // The time the estimate was received/calculated.
254   Timestamp update_time = Timestamp::MinusInfinity();
255   Timestamp last_receive_time = Timestamp::MinusInfinity();
256   Timestamp last_send_time = Timestamp::MinusInfinity();
257 
258   // Total estimated link capacity.
259   DataRate link_capacity = DataRate::MinusInfinity();
260   // Used as a safe measure of available capacity.
261   DataRate link_capacity_lower = DataRate::MinusInfinity();
262   // Used as limit for increasing bitrate.
263   DataRate link_capacity_upper = DataRate::MinusInfinity();
264 
265   TimeDelta pre_link_buffer_delay = TimeDelta::MinusInfinity();
266   TimeDelta post_link_buffer_delay = TimeDelta::MinusInfinity();
267   TimeDelta propagation_delay = TimeDelta::MinusInfinity();
268 
269   // Only for debugging
270   TimeDelta time_delta = TimeDelta::MinusInfinity();
271   Timestamp last_feed_time = Timestamp::MinusInfinity();
272   double cross_delay_rate = NAN;
273   double spike_delay_rate = NAN;
274   DataRate link_capacity_std_dev = DataRate::MinusInfinity();
275   DataRate link_capacity_min = DataRate::MinusInfinity();
276   double cross_traffic_ratio = NAN;
277 };
278 }  // namespace webrtc
279 
280 #endif  // API_TRANSPORT_NETWORK_TYPES_H_
281