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