Adds LogDnsClient::NotifyWhenNotThrottled

components/certificate_transparency/log_dns_client.h

 // Copyright 2016 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 COMPONENTS_CERTIFICATE_TRANSPARENCY_LOG_DNS_CLIENT_H_
 #define COMPONENTS_CERTIFICATE_TRANSPARENCY_LOG_DNS_CLIENT_H_
 
 #include <stdint.h>
 
 #include <list>
@@ skipping 23 matching lines @@
  public:
   // Invoked when an audit proof query completes.
   // If an error occurred, |net_error| will be a net::Error code, otherwise it
   // will be net::OK and |proof| will be the audit proof that was received.
   // The log ID of |proof| will not be set, as that is not known by this class,
   // 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
   // positive value for |max_concurrent_queries|. Queries that would exceed this
   // limit will fail with net::TEMPORARILY_THROTTLED. Setting this to 0 will
   // disable this limit.
   LogDnsClient(std::unique_ptr<net::DnsClient> dns_client,
                const net::NetLogWithSource& net_log,
                size_t max_concurrent_queries);
   // Must be deleted on the same thread that it was created on.
   ~LogDnsClient() override;
 
   // Called by NetworkChangeNotifier when the DNS config changes.
   // The DnsClient's config will be updated in response.
   void OnDNSChanged() override;
 
   // 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
   // provided in |tree_size|.
   // The |callback| is invoked when the query is complete, or an asynchronous
   // error occurs. It will only be invoked if this method returns
   // net::ERR_IO_PENDING.
   // Returns:
@@ skipping 36 matching lines @@
   // Used to perform DNS queries.
   std::unique_ptr<net::DnsClient> dns_client_;
   // Passed to the DNS client for logging.
   net::NetLogWithSource net_log_;
   // A FIFO queue of ongoing queries. Since entries will always be appended to
   // 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);
 };
 
 }  // namespace certificate_transparency
 #endif  // COMPONENTS_CERTIFICATE_TRANSPARENCY_LOG_DNS_CLIENT_H_