mobile/android/thirdparty/ch/boye/httpclientandroidlib/impl/conn/tsccm/package.html@fc2d59ddac77
mobile/android/thirdparty/ch/boye/httpclientandroidlib/impl/conn/tsccm/package.html
Wed, 31 Dec 2014 07:22:50 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 07:22:50 +0100
- branch
- TOR_BUG_3246
- changeset 4
- fc2d59ddac77
- permissions
- -rw-r--r--
Correct previous dual key logic pending first delivery installment.
1 <html>
2 <head>
3 <!--
4 /*
5 * ====================================================================
6 * Licensed to the Apache Software Foundation (ASF) under one
7 * or more contributor license agreements. See the NOTICE file
8 * distributed with this work for additional information
9 * regarding copyright ownership. The ASF licenses this file
10 * to you under the Apache License, Version 2.0 (the
11 * "License"); you may not use this file except in compliance
12 * with the License. You may obtain a copy of the License at
13 *
14 * http://www.apache.org/licenses/LICENSE-2.0
15 *
16 * Unless required by applicable law or agreed to in writing,
17 * software distributed under the License is distributed on an
18 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
19 * KIND, either express or implied. See the License for the
20 * specific language governing permissions and limitations
21 * under the License.
22 * ====================================================================
23 *
24 * This software consists of voluntary contributions made by many
25 * individuals on behalf of the Apache Software Foundation. For more
26 * information on the Apache Software Foundation, please see
27 * <http://www.apache.org/>.
28 *
29 */
30 -->
31 </head>
32 <body>
33 The implementation of a thread-safe client connection manager.
35 <center>
36 <img src="doc-files/tsccm-structure.png" alt="Relation Diagram"/>
37 </center>
39 <p>
40 The implementation is structured into three areas, as illustrated
41 by the diagram above.
42 Facing the application is the <i>Manager</i> (green), which internally
43 maintains a <i>Pool</i> (yellow) of connections and waiting threads.
44 Both Manager and Pool rely on <i>Operations</i> (cyan) to provide the
45 actual connections.
46 </p>
47 <p>
48 In order to allow connection garbage collection, it is
49 imperative that hard object references between the areas are
50 restricted to the relations indicated by arrows in the diagram:
51 </p>
52 <ul>
53 <li>Applications reference only the Manager objects.</li>
54 <li>Manager objects reference Pool objects, but not vice versa.</li>
55 <li>Operations objects do not reference either Manager or Pool objects.</li>
56 </ul>
58 <p>
59 The following table shows a selection of classes and interfaces,
60 and their assignment to the three areas.
61 </p>
62 <center>
63 <table border="1">
64 <colgroup>
65 <col width="50%"/>
66 <col width="50%"/>
67 </colgroup>
69 <tr>
70 <td style="text-align: center; background-color: #00ff00;">
71 {@link org.apache.http.impl.conn.tsccm.ThreadSafeClientConnManager}
72 </td>
73 <td style="text-align: center; background-color: #ffff00;">
74 {@link org.apache.http.impl.conn.tsccm.AbstractConnPool}
75 </td>
76 </tr>
78 <tr>
79 <td style="text-align: center; background-color: #00ff00;">
80 {@link org.apache.http.impl.conn.tsccm.BasicPooledConnAdapter}
81 </td>
82 <td style="text-align: center; background-color: #ffff00;">
83 {@link org.apache.http.impl.conn.tsccm.ConnPoolByRoute}
84 </td>
85 </tr>
87 <!-- appears on both sides! -->
89 <tr>
90 <td style="text-align: right; background-color: #00ff00;">
91 {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}
92 </td>
93 <td style="text-align: left; background-color: #ffff00;">
94 {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}
95 </td>
96 </tr>
98 <!-- ====================== -->
100 <tr style="border-width: 5px;">
101 </tr>
103 <tr>
104 <td colspan="2" style="text-align: center; background-color: #00ffff;">
105 {@link org.apache.http.conn.ClientConnectionOperator}
106 </td>
107 </tr>
109 <tr>
110 <td colspan="2" style="text-align: center; background-color: #00ffff;">
111 {@link org.apache.http.conn.OperatedClientConnection}
112 </td>
113 </tr>
115 </table>
116 </center>
118 <p>
119 The Manager area has implementations for the connection management
120 interfaces {@link org.apache.http.conn.ClientConnectionManager}
121 and {@link org.apache.http.conn.ManagedClientConnection}.
122 The latter is an adapter from managed to operated connections, based on a
123 {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}.
124 <br/>
125 The Pool area shows an abstract pool class
126 {@link org.apache.http.impl.conn.tsccm.AbstractConnPool}
127 and a concrete implementation
128 {@link org.apache.http.impl.conn.tsccm.ConnPoolByRoute}
129 which uses the same basic algorithm as the
130 <code>MultiThreadedHttpConnectionManager</code>
131 in HttpClient 3.x.
132 A pool contains instances of
133 {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}.
134 Most other classes in this package also belong to the Pool area.
135 <br/>
136 In the Operations area, you will find only the interfaces for
137 operated connections as defined in the org.apache.http.conn package.
138 The connection manager will work with all correct implementations
139 of these interfaces. This package therefore does not define anything
140 specific to the Operations area.
141 </p>
143 <p>
144 As you have surely noticed, the
145 {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}
146 appears in both the Manager and Pool areas.
147 This is where things get tricky for connection garbage collection.
148 <br/>
149 A connection pool may start a background thread to implement cleanup.
150 In that case, the connection pool will not be garbage collected until
151 it is shut down, since the background thread keeps a hard reference
152 to the pool. The pool itself keeps hard references to the pooled entries,
153 which in turn reference idle connections. Neither of these is subject
154 to garbage collection.
155 Only the shutdown of the pool will stop the background thread,
156 thereby enabling garbage collection of the pool objects.
157 <br/>
158 A pool entry that is passed to an application by means of a connection
159 adapter will move from the Pool area to the Manager area. When the
160 connection is released by the application, the manager returns the
161 entry back to the pool. With that step, the pool entry moves from
162 the Manager area back to the Pool area.
163 While the entry is in the Manager area, the pool MUST NOT keep a
164 hard reference to it.
165 </p>
167 <p>
168 The purpose of connection garbage collection is to detect when an
169 application fails to return a connection. In order to achieve this,
170 the only hard reference to the pool entry in the Manager area is
171 in the connection wrapper. The manager will not keep a hard reference
172 to the connection wrapper either, since that wrapper is effectively
173 moving to the Application area.
174 If the application drops it's reference to the connection wrapper,
175 that wrapper will be garbage collected, and with it the pool entry.
176 <br/>
177 In order to detect garbage collection of pool entries handed out
178 to the application, the pool keeps a <i>weak reference</i> to the
179 entry. Instances of
180 {@link org.apache.http.impl.conn.tsccm.BasicPoolEntryRef}
181 combine the weak reference with information about the route for
182 which the pool entry was allocated. If one of these entry references
183 becomes stale, the pool can accommodate for the lost connection.
184 This is triggered either by a background thread waiting for the
185 references to be queued by the garbage collector, or by the
186 application calling a {@link
187 org.apache.http.conn.ClientConnectionManager#closeIdleConnections cleanup}
188 method of the connection manager.
189 <br/>
190 Basically the same trick is used for detecting garbage collection
191 of the connection manager itself. The pool keeps a weak reference
192 to the connection manager that created it. However, this will work
193 only if there is a background thread to detect when that reference
194 is queued by the garbage collector. Otherwise, a finalizer of the
195 connection manager will shut down the pool and release it's resources.
196 </p>
199 </body>
200 </html>
