Added Network Quality Estimator Real-time interface to Cronet

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 <stdint.h>
 
 #include <deque>
 #include <map>
 #include <string>
 
 #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"
 #include "net/base/socket_performance_watcher.h"
 #include "net/base/socket_performance_watcher_factory.h"
 
 namespace net {
 
 class URLRequest;
 
 // NetworkQualityEstimator provides network quality estimates (quality of the
 // full paths to all origins that have been connected to).
 // The estimates are based on the observed organic traffic.
 // A NetworkQualityEstimator instance is attached to URLRequestContexts and
 // observes the traffic of URLRequests spawned from the URLRequestContexts.
 // A single instance of NQE can be attached to multiple URLRequestContexts,
 // thereby increasing the single NQE instance's accuracy by providing more
 // observed traffic characteristics.
 class NET_EXPORT_PRIVATE NetworkQualityEstimator
     : public NetworkChangeNotifier::ConnectionTypeObserver,
       public ExternalEstimateProvider::UpdatedEstimateDelegate,
       public SocketPerformanceWatcherFactory {
  public:
+  // On Android, a Java counterpart will be generated for this enum.
+  // GENERATED_JAVA_ENUM_PACKAGE: org.chromium.net
+  // GENERATED_JAVA_CLASS_NAME_OVERRIDE: NetworkQualityObservationSource
+  // GENERATED_JAVA_PREFIX_TO_STRIP:
+  enum ObservationSource {
+    // The observation was taken at the request layer, e.g., a round trip time
+    // is recorded as the time between the request being sent and the first byte
+    // being received.
+    URL_REQUEST,
+    // The observation is taken from TCP statistics maintained by the kernel.
+    TCP,
+    // The observation is taken at the QUIC layer.
+    QUIC,
+    // The observation is a previously cached estimate of the metric.
+    CACHED_ESTIMATE,
+    // The observation is derived from network connection information provided
+    // 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.
+    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);
+  };
+
   // 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
+  // can be kept network specific.
+  // |external_estimates_provider| may be NULL.
+  // |variation_params| is the map containing all field trial parameters for the
+  // network quality estimator field trial.
+  // |allow_local_host_requests_for_tests| should only be true when testing
+  // against local HTTP server and allows the requests to local host to be
+  // used for network quality estimation.
+  // |allow_smaller_responses_for_tests| should only be true when testing.
+  // Allows the responses smaller than |kMinTransferSizeInBytes| or shorter than
+  // |kMinRequestDurationMicroseconds| to be used for network quality
+  // 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;
 
   // 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;
@@ skipping 18 matching lines @@
   virtual bool GetRecentMedianDownlinkThroughputKbps(
       const base::TimeTicks& begin_timestamp,
       int32_t* kbps) const;
 
   // SocketPerformanceWatcherFactory implementation:
   scoped_ptr<SocketPerformanceWatcher> CreateTCPSocketPerformanceWatcher()
       const override;
   scoped_ptr<SocketPerformanceWatcher> CreateUDPSocketPerformanceWatcher()
       const 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);
+
  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 18 matching lines @@
     // - Wi-Fi SSID if the device is connected to a Wi-Fi access point and the
     //   SSID name is available, or
     // - MCC/MNC code of the cellular carrier if the device is connected to a
     //   cellular network, or
     // - "Ethernet" in case the device is connected to ethernet.
     // - An empty string in all other cases or if the network name is not
     //   exposed by platform APIs.
     std::string id;
   };
 
-  // Construct a NetworkQualityEstimator instance allowing for test
-  // configuration. Registers for network type change notifications so estimates
-  // can be kept network specific.
-  // |external_estimates_provider| may be NULL.
-  // |variation_params| is the map containing all field trial parameters for the
-  // network quality estimator field trial.
-  // |allow_local_host_requests_for_tests| should only be true when testing
-  // against local HTTP server and allows the requests to local host to be
-  // used for network quality estimation.
-  // |allow_smaller_responses_for_tests| should only be true when testing.
-  // Allows the responses smaller than |kMinTransferSizeInBytes| or shorter than
-  // |kMinRequestDurationMicroseconds| to be used for network quality
-  // 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);
-
   // Returns true if the cached network quality estimate was successfully read.
   bool ReadCachedNetworkQualityEstimate();
 
   // NetworkChangeNotifier::ConnectionTypeObserver implementation:
   void OnConnectionTypeChanged(
       NetworkChangeNotifier::ConnectionType type) override;
 
   // ExternalEstimateProvider::UpdatedEstimateObserver implementation.
   void OnUpdatedEstimateAvailable() override;
 
@@ skipping 10 matching lines @@
                            PercentileDifferentTimestamps);
   FRIEND_TEST_ALL_PREFIXES(NetworkQualityEstimatorTest, ComputedPercentiles);
   FRIEND_TEST_ALL_PREFIXES(NetworkQualityEstimatorTest, TestCaching);
   FRIEND_TEST_ALL_PREFIXES(NetworkQualityEstimatorTest,
                            TestLRUCacheMaximumSize);
   FRIEND_TEST_ALL_PREFIXES(NetworkQualityEstimatorTest, TestGetMedianRTTSince);
   FRIEND_TEST_ALL_PREFIXES(NetworkQualityEstimatorTest,
                            TestExternalEstimateProvider);
   FRIEND_TEST_ALL_PREFIXES(NetworkQualityEstimatorTest,
                            TestExternalEstimateProviderMergeEstimates);
+  FRIEND_TEST_ALL_PREFIXES(NetworkQualityEstimatorTest, TestObservers);
 
   // NetworkQuality is used to cache the quality of a network connection.
   class NET_EXPORT_PRIVATE NetworkQuality {
    public:
     NetworkQuality();
     // |rtt| is the estimate of the round trip time.
     // |downstream_throughput_kbps| is the estimate of the downstream
     // throughput.
     NetworkQuality(const base::TimeDelta& rtt,
                    int32_t downstream_throughput_kbps);
@@ skipping 37 matching lines @@
     const base::TimeTicks last_update_time_;
 
     // Quality of this cached network.
     const NetworkQuality network_quality_;
 
    private:
     DISALLOW_ASSIGN(CachedNetworkQuality);
   };
 
   // Records the round trip time or throughput observation, along with the time
-  // the observation was made.
+  // the observation was made. The units of value are type specific. For round
+  // trip time observations, the value is in milliseconds. For throughput,
+  // the value is in kilobits per second. Observations can be made at several
+  // places in the network stack, thus the observation source is provided as
+  // well.
   struct NET_EXPORT_PRIVATE Observation {
-    Observation(int32_t value, base::TimeTicks timestamp);
+    Observation(int32_t value,
+                base::TimeTicks timestamp,
+                ObservationSource source);
     ~Observation();
 
     // Value of the observation.
     const int32_t value;
 
     // Time when the observation was taken.
     const base::TimeTicks timestamp;
+
+    // The source of the observation.
+    const ObservationSource source;
   };
 
   // Holds an observation and its weight.
   struct NET_EXPORT_PRIVATE WeightedObservation {
     WeightedObservation(int32_t value, double weight)
         : value(value), weight(weight) {}
     WeightedObservation(const WeightedObservation& other)
         : WeightedObservation(other.value, other.weight) {}
 
     WeightedObservation& operator=(const WeightedObservation& other) {
@@ skipping 141 matching lines @@
       const base::TimeTicks& begin_timestamp,
       int percentile) const;
 
   // 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 Observation& observation);
+
+  void NotifyObserversOfThroughput(const Observation& observation);
+
   // 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
@@ skipping 50 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.
+  base::ObserverList<RTTObserver> rtt_observer_list_;
+  base::ObserverList<ThroughputObserver> throughput_observer_list_;
+
   base::ThreadChecker thread_checker_;
 
   DISALLOW_COPY_AND_ASSIGN(NetworkQualityEstimator);
 };
 
 }  // namespace net
 
 #endif  // NET_BASE_NETWORK_QUALITY_ESTIMATOR_H_