1 // Copyright 2020 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef CAST_STREAMING_SENDER_PACKET_ROUTER_H_ 6 #define CAST_STREAMING_SENDER_PACKET_ROUTER_H_ 7 8 #include <stdint.h> 9 10 #include <chrono> 11 #include <memory> 12 #include <vector> 13 14 #include "absl/types/span.h" 15 #include "cast/streaming/bandwidth_estimator.h" 16 #include "cast/streaming/environment.h" 17 #include "cast/streaming/ssrc.h" 18 #include "platform/api/time.h" 19 #include "util/alarm.h" 20 21 namespace openscreen { 22 namespace cast { 23 24 // Manages network packet transmission for one or more Senders, directing each 25 // inbound packet to a specific Sender instance, pacing the transmission of 26 // outbound packets, and employing network bandwidth/availability monitoring and 27 // congestion control. 28 // 29 // Instead of just sending packets whenever they want, Senders must request 30 // transmission from the SenderPacketRouter. The router then calls-back to each 31 // Sender, in the near future, when it has allocated an available time slice for 32 // transmission. The Sender is allowed to decide, at that exact moment, which 33 // packet most needs to be sent. 34 // 35 // Pacing strategy: Packets are sent in bursts. This allows the platform 36 // (operating system) to collect many small packets into a short-term buffer, 37 // which allows for optimizations at the link layer. For example, multiple 38 // packets can be sent together as one larger transmission unit, and this can be 39 // critical for good performance over shared-medium networks (such as 802.11 40 // WiFi). https://en.wikipedia.org/wiki/Frame-bursting 41 class SenderPacketRouter : public BandwidthEstimator, 42 public Environment::PacketConsumer { 43 public: 44 class Sender { 45 public: 46 // Called to provide the Sender with what looks like a RTCP packet meant for 47 // it specifically (among other Senders) to process. |arrival_time| 48 // indicates when the packet arrived (i.e., when it was received from the 49 // platform). 50 virtual void OnReceivedRtcpPacket(Clock::time_point arrival_time, 51 absl::Span<const uint8_t> packet) = 0; 52 53 // Populates the given |buffer| with a RTCP/RTP packet that will be sent 54 // immediately. Returns the portion of |buffer| contaning the packet, or an 55 // empty Span if nothing is ready to send. 56 virtual absl::Span<uint8_t> GetRtcpPacketForImmediateSend( 57 Clock::time_point send_time, 58 absl::Span<uint8_t> buffer) = 0; 59 virtual absl::Span<uint8_t> GetRtpPacketForImmediateSend( 60 Clock::time_point send_time, 61 absl::Span<uint8_t> buffer) = 0; 62 63 // Returns the point-in-time at which RTP sending should resume, or kNever 64 // if it should be suspended until an explicit call to RequestRtpSend(). The 65 // implementation may return a value on or before "now" to indicate an 66 // immediate resume is desired. 67 virtual Clock::time_point GetRtpResumeTime() = 0; 68 69 protected: 70 virtual ~Sender(); 71 }; 72 73 // Constructs an instance with default burst parameters appropriate for the 74 // given |max_burst_bitrate|. 75 explicit SenderPacketRouter(Environment* environment, 76 int max_burst_bitrate = kDefaultMaxBurstBitrate); 77 78 // Constructs an instance with specific burst parameters. The maximum bitrate 79 // will be computed based on these (and Environment::GetMaxPacketSize()). 80 SenderPacketRouter(Environment* environment, 81 int max_packets_per_burst, 82 std::chrono::milliseconds burst_interval); 83 84 ~SenderPacketRouter(); 85 max_packet_size()86 int max_packet_size() const { return packet_buffer_size_; } max_burst_bitrate()87 int max_burst_bitrate() const { return max_burst_bitrate_; } 88 89 // Called from a Sender constructor/destructor to register/deregister a Sender 90 // instance that processes RTP/RTCP packets from a Receiver having the given 91 // SSRC. 92 void OnSenderCreated(Ssrc receiver_ssrc, Sender* client); 93 void OnSenderDestroyed(Ssrc receiver_ssrc); 94 95 // Requests an immediate send of a RTCP packet, and then RTCP sending will 96 // repeat at regular intervals (see kRtcpSendInterval) until the Sender is 97 // de-registered. 98 void RequestRtcpSend(Ssrc receiver_ssrc); 99 100 // Requests an immediate send of a RTP packet. RTP sending will continue until 101 // the Sender stops providing packet data. 102 // 103 // See also: Sender::GetRtpResumeTime(). 104 void RequestRtpSend(Ssrc receiver_ssrc); 105 106 // A reasonable default maximum bitrate for bursting. Congestion control 107 // should always be employed to limit the Senders' sustained/average outbound 108 // data volume for "fair" use of the network. 109 static constexpr int kDefaultMaxBurstBitrate = 24 << 20; // 24 megabits/sec 110 111 // The minimum amount of time between burst-sends. The methodology by which 112 // this value was determined is lost knowledge, but is likely the result of 113 // experimentation with various network and operating system configurations. 114 // This value came from the original Chrome Cast Streaming implementation. 115 static constexpr std::chrono::milliseconds kDefaultBurstInterval{10}; 116 117 // A special time_point value representing "never." 118 static constexpr Clock::time_point kNever = Clock::time_point::max(); 119 120 private: 121 struct SenderEntry { 122 Ssrc receiver_ssrc; 123 Sender* sender; 124 Clock::time_point next_rtcp_send_time; 125 Clock::time_point next_rtp_send_time; 126 127 // Entries are ordered by the transmission priority (high→low), as implied 128 // by their SSRC. See ssrc.h for details. 129 bool operator<(const SenderEntry& other) const { 130 return ComparePriority(receiver_ssrc, other.receiver_ssrc) < 0; 131 } 132 }; 133 134 using SenderEntries = std::vector<SenderEntry>; 135 136 // Environment::PacketConsumer implementation. 137 void OnReceivedPacket(const IPEndpoint& source, 138 Clock::time_point arrival_time, 139 std::vector<uint8_t> packet) final; 140 141 // Helper to return an iterator pointing to the entry corresponding to the 142 // given |receiver_ssrc|, or "end" if not found. 143 SenderEntries::iterator FindEntry(Ssrc receiver_ssrc); 144 145 // Examine the next send time for all Senders, and decide whether to schedule 146 // a burst-send. 147 void ScheduleNextBurst(); 148 149 // Performs a burst-send of packets. This is called whenever the Alarm fires. 150 void SendBurstOfPackets(); 151 152 // Send an RTCP packet from each Sender that has one ready, and return the 153 // number of packets sent. 154 int SendJustTheRtcpPackets(Clock::time_point send_time); 155 156 // Send zero or more RTP packets from each Sender, up to a maximum of 157 // |num_packets_to_send|, and return the number of packets sent. 158 int SendJustTheRtpPackets(Clock::time_point send_time, 159 int num_packets_to_send); 160 161 // Returns the maximum number of packets to send in one burst, based on the 162 // given parameters. 163 static int ComputeMaxPacketsPerBurst( 164 int max_burst_bitrate, 165 int packet_size, 166 std::chrono::milliseconds burst_interval); 167 168 // Returns the maximum bitrate inferred by the given parameters. 169 static int ComputeMaxBurstBitrate(int packet_size, 170 int max_packets_per_burst, 171 std::chrono::milliseconds burst_interval); 172 173 Environment* const environment_; 174 const int packet_buffer_size_; 175 const std::unique_ptr<uint8_t[]> packet_buffer_; 176 const int max_packets_per_burst_; 177 const std::chrono::milliseconds burst_interval_; 178 const int max_burst_bitrate_; 179 180 // Schedules the task that calls back into this SenderPacketRouter at a later 181 // time to send the next burst of packets. 182 Alarm alarm_; 183 184 // The current list of Senders and their timing information. This is 185 // maintained in order of the priority implied by the Sender SSRC's. 186 SenderEntries senders_; 187 188 // The last time a burst of packets was sent. This is used to determine the 189 // next burst time. 190 Clock::time_point last_burst_time_ = Clock::time_point::min(); 191 }; 192 193 } // namespace cast 194 } // namespace openscreen 195 196 #endif // CAST_STREAMING_SENDER_PACKET_ROUTER_H_ 197