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