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"
 
 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:
+  // 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: OBSERVATION_SOURCE_
+  enum ObservationSource {
+    OBSERVATION_SOURCE_URL_REQUEST,
+    OBSERVATION_SOURCE_TCP,
+    OBSERVATION_SOURCE_QUIC,
+    OBSERVATION_SOURCE_CACHED_ESTIMATE,
+    OBSERVATION_SOURCE_DEFAULT_FROM_PLATFORM,

[pauljensen, 2015/09/02 16:54:48]

Each of these needs a comment explaining it.

[bengr, 2015/09/14 21:04:35]

Done.

+    OBSERVATION_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
+    // times is specified in milliseconds.

[pauljensen, 2015/09/02 16:54:48]

times->time

[bengr, 2015/09/14 21:04:35]

Done.

+    virtual void OnRTTObservation(int32_t rtt_ms,
+                                  const base::TimeTicks& timestamp,

[pauljensen, 2015/09/02 16:54:48]

You might want to explain what |timestamp| is a timestamp of...I'd imagine
OnRTTObservation() getting called immediately after an observation is taken, so
a timestamp of when the observation was taken seems redundant with
TimeTicks::Now().

[bengr, 2015/09/14 21:04:35]

Right. I wanted to decouple this so that there wouldn't be any confusion about
when the observation was taken and to save the observer the trouble of calling
Now(). I'd imagine that observers might queue observations, so it's also a
convenience to have the timestamp. Moreover, I wasn't completely sure that
observations would always be reported immediately after being made.

+                                  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);
 
   ~NetworkQualityEstimator() override;
 
@@ skipping 20 matching lines @@
   virtual bool GetRecentMedianRTT(const base::TimeTicks& begin_timestamp,
                                   base::TimeDelta* rtt) const;
 
   // Returns true if median downstream throughput is available and sets |kbps|
   // to the median of downstream Kbps observations since |begin_timestamp|.
   // Virtualized for testing. |kbps| should not be null.
   virtual bool GetRecentMedianDownlinkThroughputKbps(
       const base::TimeTicks& begin_timestamp,
       int32_t* kbps) const;
 
+  // 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);
+
+  // Configure for testing. If true, |allow_local_host_requests| will include
+  // observations from localhost, and |allow_smaller_responses| will remove
+  // the requirement of throughtput observations that response size be above
+  // a threshold.
+  void ConfigureForTests(bool allow_local_host_requests,
+                         bool allow_smaller_responses);
+
  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 117 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 135 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;
 
   // 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_;
+  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_;
+  bool allow_small_responses_;
 
   // Time when last connection change was observed.
   base::TimeTicks last_connection_change_;
 
   // ID of the current network.
   NetworkID current_network_id_;
 
   // Peak network quality (fastest round-trip-time (RTT) and highest
   // downstream throughput) measured since last connectivity change. RTT is
   // measured from time the request is sent until the first byte received.
@@ skipping 17 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_estimates_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_