• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef NET_SOCKET_CLIENT_SOCKET_POOL_H_
6 #define NET_SOCKET_CLIENT_SOCKET_POOL_H_
7 
8 #include <deque>
9 #include <string>
10 
11 #include "base/basictypes.h"
12 #include "base/memory/ref_counted.h"
13 #include "base/memory/scoped_ptr.h"
14 #include "base/template_util.h"
15 #include "base/time/time.h"
16 #include "net/base/completion_callback.h"
17 #include "net/base/load_states.h"
18 #include "net/base/net_export.h"
19 #include "net/base/request_priority.h"
20 #include "net/dns/host_resolver.h"
21 
22 namespace base {
23 class DictionaryValue;
24 }
25 
26 namespace net {
27 
28 class ClientSocketHandle;
29 class ClientSocketPoolHistograms;
30 class StreamSocket;
31 
32 // ClientSocketPools are layered. This defines an interface for lower level
33 // socket pools to communicate with higher layer pools.
34 class NET_EXPORT HigherLayeredPool {
35  public:
~HigherLayeredPool()36   virtual ~HigherLayeredPool() {}
37 
38   // Instructs the HigherLayeredPool to close an idle connection. Return true if
39   // one was closed.  Closing an idle connection will call into the lower layer
40   // pool it came from, so must be careful of re-entrancy when using this.
41   virtual bool CloseOneIdleConnection() = 0;
42 };
43 
44 // ClientSocketPools are layered. This defines an interface for higher level
45 // socket pools to communicate with lower layer pools.
46 class NET_EXPORT LowerLayeredPool {
47  public:
~LowerLayeredPool()48   virtual ~LowerLayeredPool() {}
49 
50   // Returns true if a there is currently a request blocked on the per-pool
51   // (not per-host) max socket limit, either in this pool, or one that it is
52   // layered on top of.
53   virtual bool IsStalled() const = 0;
54 
55   // Called to add or remove a higher layer pool on top of |this|.  A higher
56   // layer pool may be added at most once to |this|, and must be removed prior
57   // to destruction of |this|.
58   virtual void AddHigherLayeredPool(HigherLayeredPool* higher_pool) = 0;
59   virtual void RemoveHigherLayeredPool(HigherLayeredPool* higher_pool) = 0;
60 };
61 
62 // A ClientSocketPool is used to restrict the number of sockets open at a time.
63 // It also maintains a list of idle persistent sockets.
64 //
65 class NET_EXPORT ClientSocketPool : public LowerLayeredPool {
66  public:
67   // Subclasses must also have an inner class SocketParams which is
68   // the type for the |params| argument in RequestSocket() and
69   // RequestSockets() below.
70 
71   // Requests a connected socket for a group_name.
72   //
73   // There are five possible results from calling this function:
74   // 1) RequestSocket returns OK and initializes |handle| with a reused socket.
75   // 2) RequestSocket returns OK with a newly connected socket.
76   // 3) RequestSocket returns ERR_IO_PENDING.  The handle will be added to a
77   // wait list until a socket is available to reuse or a new socket finishes
78   // connecting.  |priority| will determine the placement into the wait list.
79   // 4) An error occurred early on, so RequestSocket returns an error code.
80   // 5) A recoverable error occurred while setting up the socket.  An error
81   // code is returned, but the |handle| is initialized with the new socket.
82   // The caller must recover from the error before using the connection, or
83   // Disconnect the socket before releasing or resetting the |handle|.
84   // The current recoverable errors are: the errors accepted by
85   // IsCertificateError(err) and PROXY_AUTH_REQUESTED, or
86   // HTTPS_PROXY_TUNNEL_RESPONSE when reported by HttpProxyClientSocketPool.
87   //
88   // If this function returns OK, then |handle| is initialized upon return.
89   // The |handle|'s is_initialized method will return true in this case.  If a
90   // StreamSocket was reused, then ClientSocketPool will call
91   // |handle|->set_reused(true).  In either case, the socket will have been
92   // allocated and will be connected.  A client might want to know whether or
93   // not the socket is reused in order to request a new socket if he encounters
94   // an error with the reused socket.
95   //
96   // If ERR_IO_PENDING is returned, then the callback will be used to notify the
97   // client of completion.
98   //
99   // Profiling information for the request is saved to |net_log| if non-NULL.
100   virtual int RequestSocket(const std::string& group_name,
101                             const void* params,
102                             RequestPriority priority,
103                             ClientSocketHandle* handle,
104                             const CompletionCallback& callback,
105                             const BoundNetLog& net_log) = 0;
106 
107   // RequestSockets is used to request that |num_sockets| be connected in the
108   // connection group for |group_name|.  If the connection group already has
109   // |num_sockets| idle sockets / active sockets / currently connecting sockets,
110   // then this function doesn't do anything.  Otherwise, it will start up as
111   // many connections as necessary to reach |num_sockets| total sockets for the
112   // group.  It uses |params| to control how to connect the sockets.   The
113   // ClientSocketPool will assign a priority to the new connections, if any.
114   // This priority will probably be lower than all others, since this method
115   // is intended to make sure ahead of time that |num_sockets| sockets are
116   // available to talk to a host.
117   virtual void RequestSockets(const std::string& group_name,
118                               const void* params,
119                               int num_sockets,
120                               const BoundNetLog& net_log) = 0;
121 
122   // Called to cancel a RequestSocket call that returned ERR_IO_PENDING.  The
123   // same handle parameter must be passed to this method as was passed to the
124   // RequestSocket call being cancelled.  The associated CompletionCallback is
125   // not run.  However, for performance, we will let one ConnectJob complete
126   // and go idle.
127   virtual void CancelRequest(const std::string& group_name,
128                              ClientSocketHandle* handle) = 0;
129 
130   // Called to release a socket once the socket is no longer needed.  If the
131   // socket still has an established connection, then it will be added to the
132   // set of idle sockets to be used to satisfy future RequestSocket calls.
133   // Otherwise, the StreamSocket is destroyed.  |id| is used to differentiate
134   // between updated versions of the same pool instance.  The pool's id will
135   // change when it flushes, so it can use this |id| to discard sockets with
136   // mismatched ids.
137   virtual void ReleaseSocket(const std::string& group_name,
138                              scoped_ptr<StreamSocket> socket,
139                              int id) = 0;
140 
141   // This flushes all state from the ClientSocketPool.  This means that all
142   // idle and connecting sockets are discarded with the given |error|.
143   // Active sockets being held by ClientSocketPool clients will be discarded
144   // when released back to the pool.
145   // Does not flush any pools wrapped by |this|.
146   virtual void FlushWithError(int error) = 0;
147 
148   // Called to close any idle connections held by the connection manager.
149   virtual void CloseIdleSockets() = 0;
150 
151   // The total number of idle sockets in the pool.
152   virtual int IdleSocketCount() const = 0;
153 
154   // The total number of idle sockets in a connection group.
155   virtual int IdleSocketCountInGroup(const std::string& group_name) const = 0;
156 
157   // Determine the LoadState of a connecting ClientSocketHandle.
158   virtual LoadState GetLoadState(const std::string& group_name,
159                                  const ClientSocketHandle* handle) const = 0;
160 
161   // Retrieves information on the current state of the pool as a
162   // DictionaryValue.  Caller takes possession of the returned value.
163   // If |include_nested_pools| is true, the states of any nested
164   // ClientSocketPools will be included.
165   virtual base::DictionaryValue* GetInfoAsValue(
166       const std::string& name,
167       const std::string& type,
168       bool include_nested_pools) const = 0;
169 
170   // Returns the maximum amount of time to wait before retrying a connect.
171   static const int kMaxConnectRetryIntervalMs = 250;
172 
173   // The set of histograms specific to this pool.  We can't use the standard
174   // UMA_HISTOGRAM_* macros because they are callsite static.
175   virtual ClientSocketPoolHistograms* histograms() const = 0;
176 
177   static base::TimeDelta unused_idle_socket_timeout();
178   static void set_unused_idle_socket_timeout(base::TimeDelta timeout);
179 
180   static base::TimeDelta used_idle_socket_timeout();
181   static void set_used_idle_socket_timeout(base::TimeDelta timeout);
182 
183  protected:
184   ClientSocketPool();
185   virtual ~ClientSocketPool();
186 
187   // Return the connection timeout for this pool.
188   virtual base::TimeDelta ConnectionTimeout() const = 0;
189 
190  private:
191   DISALLOW_COPY_AND_ASSIGN(ClientSocketPool);
192 };
193 
194 template <typename PoolType>
RequestSocketsForPool(PoolType * pool,const std::string & group_name,const scoped_refptr<typename PoolType::SocketParams> & params,int num_sockets,const BoundNetLog & net_log)195 void RequestSocketsForPool(
196     PoolType* pool,
197     const std::string& group_name,
198     const scoped_refptr<typename PoolType::SocketParams>& params,
199     int num_sockets,
200     const BoundNetLog& net_log) {
201   pool->RequestSockets(group_name, &params, num_sockets, net_log);
202 }
203 
204 }  // namespace net
205 
206 #endif  // NET_SOCKET_CLIENT_SOCKET_POOL_H_
207