mediasoup 3.27.0 → 3.28.0

package/worker/include/RTC/BWE/InterArrival.hpp

@@ -0,0 +1,117 @@
+#ifndef MS_RTC_BWE_INTER_ARRIVAL_HPP
+#define MS_RTC_BWE_INTER_ARRIVAL_HPP
+
+#include "common.hpp"
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Groups received packets into send bursts and computes the deltas between
+		 * two consecutive bursts.
+		 *
+		 * It does the same job as `InterArrivalDelta` but on the receiving side,
+		 * where the instant a packet was sent is not known: all there is is a
+		 * timestamp of the sender's own, carried by the packet, which wraps around
+		 * and whose tick is whatever the sender decided. So groups are formed by
+		 * that timestamp instead of by a real instant, and telling which of two
+		 * timestamps is the later one has to account for the wrap.
+		 *
+		 * The computed deltas are the input of the overuse estimator: if the arrival
+		 * delta grows faster than the send delta then queues are building up
+		 * somewhere in the network.
+		 */
+		class InterArrival
+		{
+		public:
+			/**
+			 * Deltas between two consecutive groups of packets sent in a burst.
+			 */
+			struct Deltas
+			{
+				/**
+				 * Ticks elapsed between the send timestamps of both groups.
+				 */
+				uint32_t timestampDelta;
+
+				/**
+				 * Time elapsed between the arrival times of both groups (us).
+				 */
+				int64_t arrivalDeltaUs;
+
+				/**
+				 * Difference of size between both groups (bytes).
+				 */
+				int64_t sizeDelta;
+			};
+
+		private:
+			struct TimestampGroup
+			{
+				bool IsFirstPacket() const
+				{
+					return !this->completeTimeUs.has_value();
+				}
+
+				size_t size{ 0 };
+				uint32_t firstTimestamp{ 0 };
+				uint32_t timestamp{ 0 };
+				int64_t firstArrivalTimeUs{ 0 };
+				std::optional<int64_t> completeTimeUs;
+				int64_t lastSystemTimeUs{ 0 };
+			};
+
+		public:
+			/**
+			 * @param timestampGroupLengthTicks - Every packet whose timestamp is
+			 *   within this many ticks of the first packet of a group belongs to that
+			 *   group.
+			 * @param timestampToUsCoeff - Microseconds a single tick of those
+			 *   timestamps is worth.
+			 */
+			InterArrival(uint32_t timestampGroupLengthTicks, double timestampToUsCoeff);
+
+			/**
+			 * Feed a received packet.
+			 *
+			 * @param timestamp - Timestamp the packet carries, in the sender's own
+			 *   units, which wraps around.
+			 * @param arrivalTimeUs - Time at which the packet arrived.
+			 * @param systemTimeUs - Time, in our own clock reference, at which the
+			 *   packet is being fed. It's used to detect that the timestamps have
+			 *   jumped by comparing how much they advanced against how much our clock
+			 *   did.
+			 * @param packetSize - Size of the packet (bytes).
+			 *
+			 * @returns The deltas between the two latest complete groups, or no value
+			 *   if they cannot be computed yet.
+			 */
+			std::optional<Deltas> ComputeDeltas(
+			  uint32_t timestamp, int64_t arrivalTimeUs, int64_t systemTimeUs, size_t packetSize);
+
+		private:
+			/**
+			 * Whether the given timestamp is not older than the first one of the
+			 * current group, so that a packet that got reordered on its way here
+			 * doesn't close a group it doesn't belong to.
+			 */
+			bool IsPacketInOrder(uint32_t timestamp) const;
+
+			bool IsNewTimestampGroup(int64_t arrivalTimeUs, uint32_t timestamp) const;
+
+			bool BelongsToBurst(int64_t arrivalTimeUs, uint32_t timestamp) const;
+
+			void Reset();
+
+		private:
+			const uint32_t timestampGroupLengthTicks;
+			const double timestampToUsCoeff;
+			TimestampGroup currentGroup;
+			TimestampGroup prevGroup;
+			size_t numConsecutiveReorderedGroups{ 0 };
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif

package/worker/include/RTC/BWE/IntervalBudget.hpp

@@ -0,0 +1,81 @@
+#ifndef MS_RTC_BWE_INTERVAL_BUDGET_HPP
+#define MS_RTC_BWE_INTERVAL_BUDGET_HPP
+
+#include "common.hpp"
+
+namespace RTC
+{
+	namespace BWE
+	{
+		/**
+		 * Tracks how much of a bitrate is being used over a sliding span of time.
+		 *
+		 * The budget is a number of bytes that refills at a given bitrate and is
+		 * spent as bytes are sent, bounded in both directions by what that bitrate
+		 * delivers over a fixed window. Its level relative to that bound is the
+		 * answer to whether the sender is keeping up with the bitrate it was given:
+		 * a full budget means nothing has been sent for a while, and an empty one
+		 * means the bitrate is being used whole.
+		 *
+		 * The bound in the negative direction is what keeps a long burst from
+		 * building a debt that would take an unbounded time to pay back.
+		 */
+		class IntervalBudget
+		{
+		public:
+			explicit IntervalBudget(int64_t initialTargetBitrate);
+
+			/**
+			 * @param canBuildUpUnderuse - Whether what an interval leaves unspent is
+			 *   available to the next one. When false, an interval that spent nothing
+			 *   leaves the budget at just what that one interval refills, instead of
+			 *   adding to what was already there.
+			 */
+			IntervalBudget(int64_t initialTargetBitrate, bool canBuildUpUnderuse);
+
+			/**
+			 * Set the bitrate the budget refills at (bps).
+			 */
+			void SetTargetBitrate(int64_t targetBitrate);
+
+			int64_t GetTargetBitrate() const
+			{
+				return this->targetBitrate;
+			}
+
+			/**
+			 * Refill the budget with what the target bitrate delivers over the given
+			 * span of time.
+			 */
+			void IncreaseBudget(int64_t deltaTimeUs);
+
+			/**
+			 * Spend the given number of bytes.
+			 */
+			void UseBudget(int64_t bytes);
+
+			/**
+			 * Bytes still available, which is zero while the budget is in debt.
+			 */
+			int64_t GetBytesRemaining() const;
+
+			/**
+			 * Level of the budget as a fraction of what the window holds, from -1
+			 * when the debt is at its bound to 1 when the budget is full.
+			 */
+			double GetBudgetRatio() const;
+
+		private:
+			// Passed by argument.
+			const bool canBuildUpUnderuse;
+			// Others.
+			int64_t targetBitrate{ 0 };
+			// Bytes the target bitrate delivers over the window, which is what bounds
+			// the budget in both directions.
+			int64_t maxBytesInBudget{ 0 };
+			int64_t bytesRemaining{ 0 };
+		};
+	} // namespace BWE
+} // namespace RTC
+
+#endif