Expose packet loss counts from QUIC to NetworkQualityEstimator

net/base/network_quality_estimator.h

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef NET_BASE_NETWORK_QUALITY_ESTIMATOR_H_
 #define NET_BASE_NETWORK_QUALITY_ESTIMATOR_H_
 
 #include <stddef.h>
 #include <stdint.h>
 
 #include <deque>
 #include <map>
 #include <string>
 #include <tuple>
 
+#include "base/compiler_specific.h"
 #include "base/gtest_prod_util.h"
 #include "base/macros.h"
 #include "base/memory/ref_counted.h"
 #include "base/memory/scoped_ptr.h"
 #include "base/observer_list.h"
 #include "base/threading/thread_checker.h"
 #include "base/time/time.h"
 #include "net/base/external_estimate_provider.h"
 #include "net/base/net_export.h"
 #include "net/base/network_change_notifier.h"
@@ skipping 36 matching lines @@
     // by the platform. For example, typical RTT and throughput values are used
     // for a given type of network connection.
     DEFAULT_FROM_PLATFORM,
     // The observation came from a Chromium-external source.
     EXTERNAL_ESTIMATE
   };
 
   // Observes measurements of round trip time.
   class NET_EXPORT_PRIVATE RTTObserver {
    public:
-    // Will be called when a new RTT observation is available. The round trip
-    // time is specified in milliseconds. The time when the observation was
-    // taken and the source of the observation are provided.
+    // OnRTTObservation will be called when a new RTT observation is available.
+    // The round trip time is specified in milliseconds. The time when the
+    // observation was taken and the source of the observation are provided.
     virtual void OnRTTObservation(int32_t rtt_ms,
                                   const base::TimeTicks& timestamp,
                                   ObservationSource source) = 0;
 
    protected:
     RTTObserver() {}
     virtual ~RTTObserver() {}
 
    private:
     DISALLOW_COPY_AND_ASSIGN(RTTObserver);
   };
 
   // Observes measurements of throughput.
   class NET_EXPORT_PRIVATE ThroughputObserver {
    public:
     // Will be called when a new throughput observation is available.
     // Throughput is specified in kilobits per second.
     virtual void OnThroughputObservation(int32_t throughput_kbps,
                                          const base::TimeTicks& timestamp,
                                          ObservationSource source) = 0;
 
    protected:
     ThroughputObserver() {}
     virtual ~ThroughputObserver() {}
 
    private:
     DISALLOW_COPY_AND_ASSIGN(ThroughputObserver);
   };
 
+  // Observes measurements of packet counts.
+  class NET_EXPORT_PRIVATE PacketCountObserver {
+   public:
+    // OnIncrementalPacketCountObservation will be called when incremental
+    // packet counts are available. |packets_missing| is the number of packets
+    // newly missing, but they may be received later and will be counted as out
+    // of order. |packets_received_in_order| is the number of packets received
+    // in order. |packets_received_out_of_order| is the number of packets
+    // received out of order.
+
+    // An example:
+    // Last observation after packet #1. Packets #5 and #6 are received:
+    //   missing = 3, in_order = 2, out_of_order = 0.

[Jana, 2016/03/12 03:11:28]

Inferring missing packets is something that QUIC/TCP's loss detection mechanisms
do, and simply inferring 2, 3, and 4 as missing here would be aggressive, and
may not be in line with what the transport underneath is doing. For instance,
what if immediately after 6 is received, 2, 3, 4 are received?

+
+    // Last observation after packet #6. Packet #3 received:
+    //   missing = 0, in_order = 0, out_of_order = 1.
+    virtual void OnIncrementalPacketCountObservation(
+        size_t packets_missing,
+        size_t packets_received_in_order,
+        size_t packets_received_out_of_order,
+        const base::TimeTicks& timestamp,
+        ObservationSource source) = 0;
+
+   protected:
+    PacketCountObserver() {}
+    virtual ~PacketCountObserver() {}
+
+   private:
+    DISALLOW_COPY_AND_ASSIGN(PacketCountObserver);
+  };
+
   // Creates a new NetworkQualityEstimator.
   // |variation_params| is the map containing all field trial parameters
   // related to NetworkQualityEstimator field trial.
   // |external_estimates_provider| may be NULL.
   NetworkQualityEstimator(
       scoped_ptr<ExternalEstimateProvider> external_estimates_provider,
       const std::map<std::string, std::string>& variation_params);
 
   // Construct a NetworkQualityEstimator instance allowing for test
   // configuration. Registers for network type change notifications so estimates
@@ skipping 10 matching lines @@
   // estimation.
   NetworkQualityEstimator(
       scoped_ptr<ExternalEstimateProvider> external_estimates_provider,
       const std::map<std::string, std::string>& variation_params,
       bool allow_local_host_requests_for_tests,
       bool allow_smaller_responses_for_tests);
 
   ~NetworkQualityEstimator() override;
 
   // Returns true if RTT is available and sets |rtt| to estimated RTT.
-  // Virtualized for testing. |rtt| should not be null.
-  virtual bool GetRTTEstimate(base::TimeDelta* rtt) const;
+  // Virtualized for testing. |rtt| must not be null.
+  virtual bool GetRTTEstimate(base::TimeDelta* rtt) const WARN_UNUSED_RESULT;
 
   // Returns true if downlink throughput is available and sets |kbps| to
   // estimated downlink throughput (in kilobits per second).
-  // Virtualized for testing. |kbps| should not be null.
-  virtual bool GetDownlinkThroughputKbpsEstimate(int32_t* kbps) const;
+  // Virtualized for testing. |kbps| must not be null.
+  virtual bool GetDownlinkThroughputKbpsEstimate(int32_t* kbps) const
+      WARN_UNUSED_RESULT;
 
   // Notifies NetworkQualityEstimator that the response header of |request| has
   // been received.
   void NotifyHeadersReceived(const URLRequest& request);
 
   // Notifies NetworkQualityEstimator that the response body of |request| has
   // been received.
   void NotifyRequestCompleted(const URLRequest& request);
 
   // Returns true if median RTT is available and sets |rtt| to the median of
   // RTT observations since |begin_timestamp|.
-  // Virtualized for testing. |rtt| should not be null.
+  // Virtualized for testing. |rtt| must not be null.
   virtual bool GetRecentMedianRTT(const base::TimeTicks& begin_timestamp,
-                                  base::TimeDelta* rtt) const;
+                                  base::TimeDelta* rtt) const
+      WARN_UNUSED_RESULT;
 
   // Returns true if median downstream throughput is available and sets |kbps|
   // to the median of downstream throughput (in kilobits per second)
   // observations since |begin_timestamp|. Virtualized for testing. |kbps|
-  // should not be null.
+  // must not be null.
   virtual bool GetRecentMedianDownlinkThroughputKbps(
       const base::TimeTicks& begin_timestamp,
-      int32_t* kbps) const;
+      int32_t* kbps) const WARN_UNUSED_RESULT;
 
   // SocketPerformanceWatcherFactory implementation:
   scoped_ptr<SocketPerformanceWatcher> CreateSocketPerformanceWatcher(
       const Protocol protocol) override;
   void OnUpdatedRTTAvailable(const Protocol protocol,
                              const base::TimeDelta& rtt) override;
+  void OnIncrementalPacketCountAvailable(
+      Protocol protocol,
+      size_t packets_missing,
+      size_t packets_received_in_order,
+      size_t packets_received_out_of_order) override;
 
   // Adds |rtt_observer| to the list of round trip time observers. Must be
   // called on the IO thread.
   void AddRTTObserver(RTTObserver* rtt_observer);
 
   // Removes |rtt_observer| from the list of round trip time observers if it
   // is on the list of observers. Must be called on the IO thread.
   void RemoveRTTObserver(RTTObserver* rtt_observer);
 
   // Adds |throughput_observer| to the list of throughput observers. Must be
   // called on the IO thread.
   void AddThroughputObserver(ThroughputObserver* throughput_observer);
 
   // Removes |throughput_observer| from the list of throughput observers if it
   // is on the list of observers. Must be called on the IO thread.
   void RemoveThroughputObserver(ThroughputObserver* throughput_observer);
 
+  // Adds |packet_count_observer| to the list of packet count observers. Must be
+  // called on the IO thread.
+  void AddPacketCountObserver(PacketCountObserver* packet_count_observer);
+
+  // Removes |packet_count_observer| from the list of packet count observers if
+  // it is on the list of observers. Must be called on the IO thread.
+  void RemovePacketCountObserver(PacketCountObserver* packet_count_observer);
+
  protected:
   // NetworkID is used to uniquely identify a network.
   // For the purpose of network quality estimation and caching, a network is
   // uniquely identified by a combination of |type| and
   // |id|. This approach is unable to distinguish networks with
   // same name (e.g., different Wi-Fi networks with same SSID).
   // This is a protected member to expose it to tests.
   struct NET_EXPORT_PRIVATE NetworkID {
     NetworkID(NetworkChangeNotifier::ConnectionType type, const std::string& id)
         : type(type), id(id) {}
@@ skipping 186 matching lines @@
     }
 
     // Returns the number of observations in this buffer.
     size_t Size() const { return observations_.size(); }
 
     // Clears the observations stored in this buffer.
     void Clear() { observations_.clear(); }
 
     // Returns true iff the |percentile| value of the observations in this
     // buffer is available. Sets |result| to the computed |percentile|
-    // value among all observations since |begin_timestamp|. If the value is
-    // unavailable, false is returned and |result| is not modified. Percentile
-    // value is unavailable if all the values in observation buffer are older
-    // than |begin_timestamp|.
-    // |result| must not be null.
+    // value among all observations since |begin_timestamp| (inclusive). If the
+    // value is unavailable, false is returned and |result| is not modified.
+    // Percentile value is unavailable if all the values in observation buffer
+    // are older than |begin_timestamp|. |result| must not be null.
     bool GetPercentile(const base::TimeTicks& begin_timestamp,
                        ValueType* result,
                        int percentile) const;
 
    private:
     FRIEND_TEST_ALL_PREFIXES(NetworkQualityEstimatorTest, StoreObservations);
     FRIEND_TEST_ALL_PREFIXES(NetworkQualityEstimatorTest,
                              ObtainOperatingParams);
     FRIEND_TEST_ALL_PREFIXES(NetworkQualityEstimatorTest, HalfLifeParam);
 
@@ skipping 90 matching lines @@
   void AddDefaultEstimates();
 
   // Returns an estimate of network quality at the specified |percentile|.
   // Only the observations later than |begin_timestamp| are taken into account.
   // |percentile| must be between 0 and 100 (both inclusive) with higher
   // percentiles indicating less performant networks. For example, if
   // |percentile| is 90, then the network is expected to be faster than the
   // returned estimate with 0.9 probability. Similarly, network is expected to
   // be slower than the returned estimate with 0.1 probability.
   base::TimeDelta GetRTTEstimateInternal(const base::TimeTicks& begin_timestamp,
-                                         int percentile) const;
+                                         int percentile) const
+      WARN_UNUSED_RESULT;
   int32_t GetDownlinkThroughputKbpsEstimateInternal(
       const base::TimeTicks& begin_timestamp,
-      int percentile) const;
+      int percentile) const WARN_UNUSED_RESULT;
 
   // Returns the current network ID checking by calling the platform APIs.
   // Virtualized for testing.
   virtual NetworkID GetCurrentNetworkID() const;
 
   // Writes the estimated quality of the current network to the cache.
   void CacheNetworkQualityEstimate();
 
   void NotifyObserversOfRTT(const RttObservation& observation);
 
   void NotifyObserversOfThroughput(const ThroughputObservation& observation);
 
+  void NotifyObserversOfIncrementalPacketCount(
+      size_t packets_missing,
+      size_t packets_received_in_order,
+      size_t packets_received_out_of_order,
+      const base::TimeTicks& timestamp,
+      ObservationSource source);
+
   // Records the UMA related to RTT.
   void RecordRTTUMA(int32_t estimated_value_msec,
                     int32_t actual_value_msec) const;
 
   // Returns true only if |request| can be used for network quality estimation.
   // Only the requests that go over network are considered to provide useful
   // observations.
   bool RequestProvidesUsefulObservations(const URLRequest& request) const;
 
   // Values of external estimate provider status. This enum must remain
   // synchronized with the enum of the same name in
   // metrics/histograms/histograms.xml.
   enum NQEExternalEstimateProviderStatus {
     EXTERNAL_ESTIMATE_PROVIDER_STATUS_NOT_AVAILABLE,
     EXTERNAL_ESTIMATE_PROVIDER_STATUS_AVAILABLE,
     EXTERNAL_ESTIMATE_PROVIDER_STATUS_QUERIED,
     EXTERNAL_ESTIMATE_PROVIDER_STATUS_QUERY_SUCCESSFUL,
     EXTERNAL_ESTIMATE_PROVIDER_STATUS_CALLBACK,
     EXTERNAL_ESTIMATE_PROVIDER_STATUS_BOUNDARY
   };
 
   // Records the metrics related to external estimate provider.
   void RecordExternalEstimateProviderMetrics(
       NQEExternalEstimateProviderStatus status) const;
 
+  // Gets the ObservationSource that corresponds to the given |protocol|,
+  // updates |observation_source| and returns true. If the corresponding
+  // ObservationSource is unknown, false is returned and |observation_source| is
+  // not modified.
+  bool GetObservationSourceForProtocol(
+      Protocol protocol,
+      ObservationSource* observation_source) const;
+
   // Determines if the requests to local host can be used in estimating the
   // network quality. Set to true only for tests.
   const bool allow_localhost_requests_;
 
   // Determines if the responses smaller than |kMinTransferSizeInBytes|
   // or shorter than |kMinTransferSizeInBytes| can be used in estimating the
   // network quality. Set to true only for tests.
   const bool allow_small_responses_;
 
   // Time when last connection change was observed.
@@ skipping 26 matching lines @@
   NetworkQuality
       default_observations_[NetworkChangeNotifier::CONNECTION_LAST + 1];
 
   // Estimated network quality. Updated on mainframe requests.
   NetworkQuality estimated_median_network_quality_;
 
   // ExternalEstimateProvider that provides network quality using operating
   // system APIs. May be NULL.
   const scoped_ptr<ExternalEstimateProvider> external_estimate_provider_;
 
-  // Observer lists for round trip times and throughput measurements.
+  // Observer lists for round trip times, throughput and packet count
+  // measurements.
   base::ObserverList<RTTObserver> rtt_observer_list_;
   base::ObserverList<ThroughputObserver> throughput_observer_list_;
+  base::ObserverList<PacketCountObserver> packet_count_observer_list_;
 
   base::ThreadChecker thread_checker_;
 
   DISALLOW_COPY_AND_ASSIGN(NetworkQualityEstimator);
 };
 
 }  // namespace net
 
 #endif  // NET_BASE_NETWORK_QUALITY_ESTIMATOR_H_