Adds LogDnsClient::NotifyWhenNotThrottled

components/certificate_transparency/log_dns_client.h

Index: components/certificate_transparency/log_dns_client.h
diff --git a/components/certificate_transparency/log_dns_client.h b/components/certificate_transparency/log_dns_client.h
index 2d15c1c8c44760b8f228bbf99b4068e1637ff0ae..ad7cc05ab3c65f7ca4d0adc26b49aed12789813a 100644
--- a/components/certificate_transparency/log_dns_client.h
+++ b/components/certificate_transparency/log_dns_client.h
@@ -39,10 +39,15 @@ class LogDnsClient : public net::NetworkChangeNotifier::DNSObserver {
   // but the leaf index will be set.
   using AuditProofCallback =
       base::Callback<void(net::Error result,
                           std::unique_ptr<net::ct::MerkleAuditProof> proof)>;
 
+  // Invoked when the number of concurrent queries drops below the limit.
+  // The limit is set by |max_concurrent_queries| (passed to the constructor).
+  using NotThrottledCallback =
+      base::Callback<void(base::WeakPtr<LogDnsClient> sender)>;

[Ryan Sleevi, 2016/10/03 23:56:04]

From an API design standpoint, it's never desirable to expose base::WeakPtr<> as
part of a public API contract, because that adds significantly to the complexity
of reasoning about lifetime management.

https://groups.google.com/a/chromium.org/d/msg/chromium-dev/Oy3uuiTSwDk/5UDyR...
has a much longer explanation of why this is.

To this specific issue, however, if the caller cares about the state of which
LogDnsClient is used, they should be the one smuggling the pointer. When using a
base::Callback pattern (as opposed to a Delegate interface), because the caller
can curry all necessary arguments, your API contract doesn't and shouldn't
specify what's meaningful to the caller, but allow them to determine that
themselves. This can also help reduce compile-time and generated code.

[Rob Percival, 2016/10/04 18:53:03]

Done.

+
   // Creates a log client that will take ownership of |dns_client| and use it
   // to perform DNS queries. Queries will be logged to |net_log|.
   // The |dns_client| does not need to be configured first - this will be done
   // automatically as needed.
   // A limit can be set on the number of concurrent DNS queries by providing a
@@ -61,10 +66,17 @@ class LogDnsClient : public net::NetworkChangeNotifier::DNSObserver {
 
   // Called by NetworkChangeNotifier when the DNS config is first read.
   // The DnsClient's config will be updated in response.
   void OnInitialDNSConfigRead() override;
 
+  // Registers a callback to be invoked when the number of concurrent queries
+  // falls below the limit defined by |max_concurrent_queries| (passed to the
+  // constructor of LogDnsClient). This callback will fire once and then be
+  // unregistered. Should only be used if QueryAuditProof() returns
+  // net::ERR_TEMPORARILY_THROTTLED.
+  void NotifyWhenNotThrottled(const NotThrottledCallback& callback);
+
   // Queries a CT log to retrieve an audit proof for the leaf with |leaf_hash|.
   // The log is identified by |domain_for_log|, which is the DNS name used as a
   // suffix for all queries.
   // The |leaf_hash| is the SHA-256 Merkle leaf hash (see RFC6962, section 2.1).
   // The size of the CT log tree, for which the proof is requested, must be
@@ -117,10 +129,12 @@ class LogDnsClient : public net::NetworkChangeNotifier::DNSObserver {
   // the end and lookups will typically yield entries at the beginning,
   // std::list is an efficient choice.
   std::list<std::unique_ptr<AuditProofQuery>> audit_proof_queries_;
   // The maximum number of queries that can be in flight at one time.
   size_t max_concurrent_queries_;
+  // Callbacks to invoke when the number of concurrent queries is at its limit.
+  std::list<NotThrottledCallback> not_throttled_callbacks_;
   // Creates weak_ptrs to this, for callback purposes.
   base::WeakPtrFactory<LogDnsClient> weak_ptr_factory_;
 
   DISALLOW_COPY_AND_ASSIGN(LogDnsClient);
 };