PageRenderTime 23ms CodeModel.GetById 20ms app.highlight 1ms RepoModel.GetById 0ms app.codeStats 0ms

/lib/src/org/apache/http/impl/conn/tsccm/package.html

http://github.com/onedanshow/Screen-Courter
HTML | 200 lines | 153 code | 17 blank | 30 comment | 0 complexity | 99e50c3bfaeda315182d7108e49bf45b MD5 | raw file
Possible License(s): GPL-3.0
  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>
 33The implementation of a thread-safe client connection manager.
 34
 35<center>
 36<img src="doc-files/tsccm-structure.png" alt="Relation Diagram"/>
 37</center>
 38
 39<p>
 40The implementation is structured into three areas, as illustrated
 41by the diagram above.
 42Facing the application is the <i>Manager</i> (green), which internally
 43maintains a <i>Pool</i> (yellow) of connections and waiting threads.
 44Both Manager and Pool rely on <i>Operations</i> (cyan) to provide the
 45actual connections.
 46</p>
 47<p>
 48In order to allow connection garbage collection, it is
 49imperative that hard object references between the areas are
 50restricted 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>
 57
 58<p>
 59The following table shows a selection of classes and interfaces,
 60and 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>
 68
 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>
 77
 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>
 86
 87<!-- appears on both sides! -->
 88
 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>
 97
 98<!-- ====================== -->
 99
100<tr style="border-width: 5px;">
101</tr>
102
103<tr>
104<td colspan="2" style="text-align: center; background-color: #00ffff;">
105{@link org.apache.http.conn.ClientConnectionOperator}
106</td>
107</tr>
108
109<tr>
110<td colspan="2" style="text-align: center; background-color: #00ffff;">
111{@link org.apache.http.conn.OperatedClientConnection}
112</td>
113</tr>
114
115</table>
116</center>
117
118<p>
119The Manager area has implementations for the connection management
120interfaces {@link org.apache.http.conn.ClientConnectionManager}
121and {@link org.apache.http.conn.ManagedClientConnection}.
122The latter is an adapter from managed to operated connections, based on a
123{@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}.
124<br/>
125The Pool area shows an abstract pool class
126{@link org.apache.http.impl.conn.tsccm.AbstractConnPool}
127and a concrete implementation
128{@link org.apache.http.impl.conn.tsccm.ConnPoolByRoute}
129which uses the same basic algorithm as the
130<code>MultiThreadedHttpConnectionManager</code>
131in HttpClient 3.x.
132A pool contains instances of
133{@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}.
134Most other classes in this package also belong to the Pool area.
135<br/>
136In the Operations area, you will find only the interfaces for
137operated connections as defined in the org.apache.http.conn package.
138The connection manager will work with all correct implementations
139of these interfaces. This package therefore does not define anything
140specific to the Operations area.
141</p>
142
143<p>
144As you have surely noticed, the
145{@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}
146appears in both the Manager and Pool areas.
147This is where things get tricky for connection garbage collection.
148<br/>
149A connection pool may start a background thread to implement cleanup.
150In that case, the connection pool will not be garbage collected until
151it is shut down, since the background thread keeps a hard reference
152to the pool. The pool itself keeps hard references to the pooled entries,
153which in turn reference idle connections. Neither of these is subject
154to garbage collection.
155Only the shutdown of the pool will stop the background thread,
156thereby enabling garbage collection of the pool objects.
157<br/>
158A pool entry that is passed to an application by means of a connection
159adapter will move from the Pool area to the Manager area. When the
160connection is released by the application, the manager returns the
161entry back to the pool. With that step, the pool entry moves from
162the Manager area back to the Pool area.
163While the entry is in the Manager area, the pool MUST NOT keep a
164hard reference to it.
165</p>
166
167<p>
168The purpose of connection garbage collection is to detect when an
169application fails to return a connection. In order to achieve this,
170the only hard reference to the pool entry in the Manager area is
171in the connection wrapper. The manager will not keep a hard reference
172to the connection wrapper either, since that wrapper is effectively
173moving to the Application area.
174If the application drops it's reference to the connection wrapper,
175that wrapper will be garbage collected, and with it the pool entry.
176<br/>
177In order to detect garbage collection of pool entries handed out
178to the application, the pool keeps a <i>weak reference</i> to the
179entry. Instances of
180{@link org.apache.http.impl.conn.tsccm.BasicPoolEntryRef}
181combine the weak reference with information about the route for
182which the pool entry was allocated. If one of these entry references
183becomes stale, the pool can accommodate for the lost connection.
184This is triggered either by a background thread waiting for the
185references to be queued by the garbage collector, or by the
186application calling a {@link
187    org.apache.http.conn.ClientConnectionManager#closeIdleConnections cleanup}
188method of the connection manager.
189<br/>
190Basically the same trick is used for detecting garbage collection
191of the connection manager itself. The pool keeps a weak reference
192to the connection manager that created it. However, this will work
193only if there is a background thread to detect when that reference
194is queued by the garbage collector. Otherwise, a finalizer of the
195connection manager will shut down the pool and release it's resources.
196</p>
197
198
199</body>
200</html>