1 /*
2  *  Copyright (c) 2014 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_BITRATE_PROBER_H_
12 #define MODULES_PACING_BITRATE_PROBER_H_
13 
14 #include <stddef.h>
15 #include <stdint.h>
16 
17 #include <queue>
18 
19 #include "api/transport/field_trial_based_config.h"
20 #include "api/transport/network_types.h"
21 #include "rtc_base/experiments/field_trial_parser.h"
22 
23 namespace webrtc {
24 class RtcEventLog;
25 
26 struct BitrateProberConfig {
27   explicit BitrateProberConfig(const WebRtcKeyValueConfig* key_value_config);
28   BitrateProberConfig(const BitrateProberConfig&) = default;
29   BitrateProberConfig& operator=(const BitrateProberConfig&) = default;
30   ~BitrateProberConfig() = default;
31 
32   // The minimum number probing packets used.
33   FieldTrialParameter<int> min_probe_packets_sent;
34   // A minimum interval between probes to allow scheduling to be feasible.
35   FieldTrialParameter<TimeDelta> min_probe_delta;
36   // The minimum probing duration.
37   FieldTrialParameter<TimeDelta> min_probe_duration;
38   // Maximum amount of time each probe can be delayed.
39   FieldTrialParameter<TimeDelta> max_probe_delay;
40   // If NextProbeTime() is called with a delay higher than specified by
41   // |max_probe_delay|, abort it.
42   FieldTrialParameter<bool> abort_delayed_probes;
43 };
44 
45 // Note that this class isn't thread-safe by itself and therefore relies
46 // on being protected by the caller.
47 class BitrateProber {
48  public:
49   explicit BitrateProber(const WebRtcKeyValueConfig& field_trials);
50   ~BitrateProber();
51 
52   void SetEnabled(bool enable);
53 
54   // Returns true if the prober is in a probing session, i.e., it currently
55   // wants packets to be sent out according to the time returned by
56   // TimeUntilNextProbe().
is_probing()57   bool is_probing() const { return probing_state_ == ProbingState::kActive; }
58 
59   // Initializes a new probing session if the prober is allowed to probe. Does
60   // not initialize the prober unless the packet size is large enough to probe
61   // with.
62   void OnIncomingPacket(DataSize packet_size);
63 
64   // Create a cluster used to probe for |bitrate_bps| with |num_probes| number
65   // of probes.
66   void CreateProbeCluster(DataRate bitrate, Timestamp now, int cluster_id);
67 
68   // Returns the time at which the next probe should be sent to get accurate
69   // probing. If probing is not desired at this time, Timestamp::PlusInfinity()
70   // will be returned.
71   // TODO(bugs.webrtc.org/11780): Remove |now| argument when old mode is gone.
72   Timestamp NextProbeTime(Timestamp now) const;
73 
74   // Information about the current probing cluster.
75   absl::optional<PacedPacketInfo> CurrentCluster(Timestamp now);
76 
77   // Returns the minimum number of bytes that the prober recommends for
78   // the next probe, or zero if not probing.
79   DataSize RecommendedMinProbeSize() const;
80 
81   // Called to report to the prober that a probe has been sent. In case of
82   // multiple packets per probe, this call would be made at the end of sending
83   // the last packet in probe. |size| is the total size of all packets in probe.
84   void ProbeSent(Timestamp now, DataSize size);
85 
86  private:
87   enum class ProbingState {
88     // Probing will not be triggered in this state at all times.
89     kDisabled,
90     // Probing is enabled and ready to trigger on the first packet arrival.
91     kInactive,
92     // Probe cluster is filled with the set of data rates to be probed and
93     // probes are being sent.
94     kActive,
95     // Probing is enabled, but currently suspended until an explicit trigger
96     // to start probing again.
97     kSuspended,
98   };
99 
100   // A probe cluster consists of a set of probes. Each probe in turn can be
101   // divided into a number of packets to accommodate the MTU on the network.
102   struct ProbeCluster {
103     PacedPacketInfo pace_info;
104 
105     int sent_probes = 0;
106     int sent_bytes = 0;
107     Timestamp created_at = Timestamp::MinusInfinity();
108     Timestamp started_at = Timestamp::MinusInfinity();
109     int retries = 0;
110   };
111 
112   Timestamp CalculateNextProbeTime(const ProbeCluster& cluster) const;
113 
114   ProbingState probing_state_;
115 
116   // Probe bitrate per packet. These are used to compute the delta relative to
117   // the previous probe packet based on the size and time when that packet was
118   // sent.
119   std::queue<ProbeCluster> clusters_;
120 
121   // Time the next probe should be sent when in kActive state.
122   Timestamp next_probe_time_;
123 
124   int total_probe_count_;
125   int total_failed_probe_count_;
126 
127   BitrateProberConfig config_;
128 };
129 
130 }  // namespace webrtc
131 
132 #endif  // MODULES_PACING_BITRATE_PROBER_H_
133