1 /* 2 * Copyright (c) 2019 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 MODULES_PACING_PACING_CONTROLLER_H_ 12 #define MODULES_PACING_PACING_CONTROLLER_H_ 13 14 #include <stddef.h> 15 #include <stdint.h> 16 17 #include <array> 18 #include <atomic> 19 #include <memory> 20 #include <vector> 21 22 #include "absl/types/optional.h" 23 #include "api/field_trials_view.h" 24 #include "api/function_view.h" 25 #include "api/transport/field_trial_based_config.h" 26 #include "api/transport/network_types.h" 27 #include "modules/pacing/bitrate_prober.h" 28 #include "modules/pacing/interval_budget.h" 29 #include "modules/pacing/prioritized_packet_queue.h" 30 #include "modules/pacing/rtp_packet_pacer.h" 31 #include "modules/rtp_rtcp/include/rtp_packet_sender.h" 32 #include "modules/rtp_rtcp/include/rtp_rtcp_defines.h" 33 #include "modules/rtp_rtcp/source/rtp_packet_to_send.h" 34 #include "rtc_base/experiments/field_trial_parser.h" 35 #include "rtc_base/thread_annotations.h" 36 37 namespace webrtc { 38 39 // This class implements a leaky-bucket packet pacing algorithm. It handles the 40 // logic of determining which packets to send when, but the actual timing of 41 // the processing is done externally (e.g. RtpPacketPacer). Furthermore, the 42 // forwarding of packets when they are ready to be sent is also handled 43 // externally, via the PacingController::PacketSender interface. 44 class PacingController { 45 public: 46 class PacketSender { 47 public: 48 virtual ~PacketSender() = default; 49 virtual void SendPacket(std::unique_ptr<RtpPacketToSend> packet, 50 const PacedPacketInfo& cluster_info) = 0; 51 // Should be called after each call to SendPacket(). 52 virtual std::vector<std::unique_ptr<RtpPacketToSend>> FetchFec() = 0; 53 virtual std::vector<std::unique_ptr<RtpPacketToSend>> GeneratePadding( 54 DataSize size) = 0; 55 56 // TODO(bugs.webrtc.org/11340): Make pure virtual once downstream projects 57 // have been updated. OnAbortedRetransmissions(uint32_t ssrc,rtc::ArrayView<const uint16_t> sequence_numbers)58 virtual void OnAbortedRetransmissions( 59 uint32_t ssrc, 60 rtc::ArrayView<const uint16_t> sequence_numbers) {} GetRtxSsrcForMedia(uint32_t ssrc)61 virtual absl::optional<uint32_t> GetRtxSsrcForMedia(uint32_t ssrc) const { 62 return absl::nullopt; 63 } 64 }; 65 66 // Expected max pacer delay. If ExpectedQueueTime() is higher than 67 // this value, the packet producers should wait (eg drop frames rather than 68 // encoding them). Bitrate sent may temporarily exceed target set by 69 // UpdateBitrate() so that this limit will be upheld. 70 static const TimeDelta kMaxExpectedQueueLength; 71 // If no media or paused, wake up at least every `kPausedProcessIntervalMs` in 72 // order to send a keep-alive packet so we don't get stuck in a bad state due 73 // to lack of feedback. 74 static const TimeDelta kPausedProcessInterval; 75 // The default minimum time that should elapse calls to `ProcessPackets()`. 76 static const TimeDelta kMinSleepTime; 77 // When padding should be generated, add packets to the buffer with a size 78 // corresponding to this duration times the current padding rate. 79 static const TimeDelta kTargetPaddingDuration; 80 // The maximum time that the pacer can use when "replaying" passed time where 81 // padding should have been generated. 82 static const TimeDelta kMaxPaddingReplayDuration; 83 // Allow probes to be processed slightly ahead of inteded send time. Currently 84 // set to 1ms as this is intended to allow times be rounded down to the 85 // nearest millisecond. 86 static const TimeDelta kMaxEarlyProbeProcessing; 87 88 PacingController(Clock* clock, 89 PacketSender* packet_sender, 90 const FieldTrialsView& field_trials); 91 92 ~PacingController(); 93 94 // Adds the packet to the queue and calls PacketRouter::SendPacket() when 95 // it's time to send. 96 void EnqueuePacket(std::unique_ptr<RtpPacketToSend> packet); 97 98 // ABSL_DEPRECATED("Use CreateProbeClusters instead") 99 void CreateProbeCluster(DataRate bitrate, int cluster_id); 100 void CreateProbeClusters( 101 rtc::ArrayView<const ProbeClusterConfig> probe_cluster_configs); 102 103 void Pause(); // Temporarily pause all sending. 104 void Resume(); // Resume sending packets. 105 bool IsPaused() const; 106 107 void SetCongested(bool congested); 108 109 // Sets the pacing rates. Must be called once before packets can be sent. 110 void SetPacingRates(DataRate pacing_rate, DataRate padding_rate); pacing_rate()111 DataRate pacing_rate() const { return adjusted_media_rate_; } 112 113 // Currently audio traffic is not accounted by pacer and passed through. 114 // With the introduction of audio BWE audio traffic will be accounted for 115 // the pacer budget calculation. The audio traffic still will be injected 116 // at high priority. 117 void SetAccountForAudioPackets(bool account_for_audio); 118 void SetIncludeOverhead(); 119 120 void SetTransportOverhead(DataSize overhead_per_packet); 121 // The pacer is allowed to send enqued packets in bursts and can build up a 122 // packet "debt" that correspond to approximately the send rate during 123 // 'burst_interval'. 124 void SetSendBurstInterval(TimeDelta burst_interval); 125 126 // Returns the time when the oldest packet was queued. 127 Timestamp OldestPacketEnqueueTime() const; 128 129 // Number of packets in the pacer queue. 130 size_t QueueSizePackets() const; 131 // Number of packets in the pacer queue per media type (RtpPacketMediaType 132 // values are used as lookup index). 133 const std::array<int, kNumMediaTypes>& SizeInPacketsPerRtpPacketMediaType() 134 const; 135 // Totals size of packets in the pacer queue. 136 DataSize QueueSizeData() const; 137 138 // Current buffer level, i.e. max of media and padding debt. 139 DataSize CurrentBufferLevel() const; 140 141 // Returns the time when the first packet was sent. 142 absl::optional<Timestamp> FirstSentPacketTime() const; 143 144 // Returns the number of milliseconds it will take to send the current 145 // packets in the queue, given the current size and bitrate, ignoring prio. 146 TimeDelta ExpectedQueueTime() const; 147 148 void SetQueueTimeLimit(TimeDelta limit); 149 150 // Enable bitrate probing. Enabled by default, mostly here to simplify 151 // testing. Must be called before any packets are being sent to have an 152 // effect. 153 void SetProbingEnabled(bool enabled); 154 155 // Returns the next time we expect ProcessPackets() to be called. 156 Timestamp NextSendTime() const; 157 158 // Check queue of pending packets and send them or padding packets, if budget 159 // is available. 160 void ProcessPackets(); 161 162 bool IsProbing() const; 163 164 // Note: Intended for debugging purposes only, will be removed. 165 // Sets the number of iterations of the main loop in `ProcessPackets()` that 166 // is considered erroneous to exceed. 167 void SetCircuitBreakerThreshold(int num_iterations); 168 169 private: 170 TimeDelta UpdateTimeAndGetElapsed(Timestamp now); 171 bool ShouldSendKeepalive(Timestamp now) const; 172 173 // Updates the number of bytes that can be sent for the next time interval. 174 void UpdateBudgetWithElapsedTime(TimeDelta delta); 175 void UpdateBudgetWithSentData(DataSize size); 176 void UpdatePaddingBudgetWithSentData(DataSize size); 177 178 DataSize PaddingToAdd(DataSize recommended_probe_size, 179 DataSize data_sent) const; 180 181 std::unique_ptr<RtpPacketToSend> GetPendingPacket( 182 const PacedPacketInfo& pacing_info, 183 Timestamp target_send_time, 184 Timestamp now); 185 void OnPacketSent(RtpPacketMediaType packet_type, 186 DataSize packet_size, 187 Timestamp send_time); 188 void MaybeUpdateMediaRateDueToLongQueue(Timestamp now); 189 190 Timestamp CurrentTime() const; 191 192 // Helper methods for packet that may not be paced. Returns a finite Timestamp 193 // if a packet type is configured to not be paced and the packet queue has at 194 // least one packet of that type. Otherwise returns 195 // Timestamp::MinusInfinity(). 196 Timestamp NextUnpacedSendTime() const; 197 198 Clock* const clock_; 199 PacketSender* const packet_sender_; 200 const FieldTrialsView& field_trials_; 201 202 const bool drain_large_queues_; 203 const bool send_padding_if_silent_; 204 const bool pace_audio_; 205 const bool ignore_transport_overhead_; 206 const bool fast_retransmissions_; 207 208 TimeDelta min_packet_limit_; 209 DataSize transport_overhead_per_packet_; 210 TimeDelta send_burst_interval_; 211 212 // TODO(webrtc:9716): Remove this when we are certain clocks are monotonic. 213 // The last millisecond timestamp returned by `clock_`. 214 mutable Timestamp last_timestamp_; 215 bool paused_; 216 217 // Amount of outstanding data for media and padding. 218 DataSize media_debt_; 219 DataSize padding_debt_; 220 221 // The target pacing rate, signaled via SetPacingRates(). 222 DataRate pacing_rate_; 223 // The media send rate, which might adjusted from pacing_rate_, e.g. if the 224 // pacing queue is growing too long. 225 DataRate adjusted_media_rate_; 226 // The padding target rate. We aim to fill up to this rate with padding what 227 // is not already used by media. 228 DataRate padding_rate_; 229 230 BitrateProber prober_; 231 bool probing_send_failure_; 232 233 Timestamp last_process_time_; 234 Timestamp last_send_time_; 235 absl::optional<Timestamp> first_sent_packet_time_; 236 bool seen_first_packet_; 237 238 PrioritizedPacketQueue packet_queue_; 239 240 bool congested_; 241 242 TimeDelta queue_time_limit_; 243 bool account_for_audio_; 244 bool include_overhead_; 245 246 int circuit_breaker_threshold_; 247 }; 248 } // namespace webrtc 249 250 #endif // MODULES_PACING_PACING_CONTROLLER_H_ 251