1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/mobile/android/thirdparty/ch/boye/httpclientandroidlib/impl/conn/tsccm/package.html Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,200 @@
1.4 +<html>
1.5 +<head>
1.6 +<!--
1.7 +/*
1.8 + * ====================================================================
1.9 + * Licensed to the Apache Software Foundation (ASF) under one
1.10 + * or more contributor license agreements. See the NOTICE file
1.11 + * distributed with this work for additional information
1.12 + * regarding copyright ownership. The ASF licenses this file
1.13 + * to you under the Apache License, Version 2.0 (the
1.14 + * "License"); you may not use this file except in compliance
1.15 + * with the License. You may obtain a copy of the License at
1.16 + *
1.17 + * http://www.apache.org/licenses/LICENSE-2.0
1.18 + *
1.19 + * Unless required by applicable law or agreed to in writing,
1.20 + * software distributed under the License is distributed on an
1.21 + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
1.22 + * KIND, either express or implied. See the License for the
1.23 + * specific language governing permissions and limitations
1.24 + * under the License.
1.25 + * ====================================================================
1.26 + *
1.27 + * This software consists of voluntary contributions made by many
1.28 + * individuals on behalf of the Apache Software Foundation. For more
1.29 + * information on the Apache Software Foundation, please see
1.30 + * <http://www.apache.org/>.
1.31 + *
1.32 + */
1.33 +-->
1.34 +</head>
1.35 +<body>
1.36 +The implementation of a thread-safe client connection manager.
1.37 +
1.38 +<center>
1.39 +<img src="doc-files/tsccm-structure.png" alt="Relation Diagram"/>
1.40 +</center>
1.41 +
1.42 +<p>
1.43 +The implementation is structured into three areas, as illustrated
1.44 +by the diagram above.
1.45 +Facing the application is the <i>Manager</i> (green), which internally
1.46 +maintains a <i>Pool</i> (yellow) of connections and waiting threads.
1.47 +Both Manager and Pool rely on <i>Operations</i> (cyan) to provide the
1.48 +actual connections.
1.49 +</p>
1.50 +<p>
1.51 +In order to allow connection garbage collection, it is
1.52 +imperative that hard object references between the areas are
1.53 +restricted to the relations indicated by arrows in the diagram:
1.54 +</p>
1.55 +<ul>
1.56 +<li>Applications reference only the Manager objects.</li>
1.57 +<li>Manager objects reference Pool objects, but not vice versa.</li>
1.58 +<li>Operations objects do not reference either Manager or Pool objects.</li>
1.59 +</ul>
1.60 +
1.61 +<p>
1.62 +The following table shows a selection of classes and interfaces,
1.63 +and their assignment to the three areas.
1.64 +</p>
1.65 +<center>
1.66 +<table border="1">
1.67 +<colgroup>
1.68 + <col width="50%"/>
1.69 + <col width="50%"/>
1.70 +</colgroup>
1.71 +
1.72 +<tr>
1.73 +<td style="text-align: center; background-color: #00ff00;">
1.74 +{@link org.apache.http.impl.conn.tsccm.ThreadSafeClientConnManager}
1.75 +</td>
1.76 +<td style="text-align: center; background-color: #ffff00;">
1.77 +{@link org.apache.http.impl.conn.tsccm.AbstractConnPool}
1.78 +</td>
1.79 +</tr>
1.80 +
1.81 +<tr>
1.82 +<td style="text-align: center; background-color: #00ff00;">
1.83 +{@link org.apache.http.impl.conn.tsccm.BasicPooledConnAdapter}
1.84 +</td>
1.85 +<td style="text-align: center; background-color: #ffff00;">
1.86 +{@link org.apache.http.impl.conn.tsccm.ConnPoolByRoute}
1.87 +</td>
1.88 +</tr>
1.89 +
1.90 +<!-- appears on both sides! -->
1.91 +
1.92 +<tr>
1.93 +<td style="text-align: right; background-color: #00ff00;">
1.94 +{@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}
1.95 +</td>
1.96 +<td style="text-align: left; background-color: #ffff00;">
1.97 +{@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}
1.98 +</td>
1.99 +</tr>
1.100 +
1.101 +<!-- ====================== -->
1.102 +
1.103 +<tr style="border-width: 5px;">
1.104 +</tr>
1.105 +
1.106 +<tr>
1.107 +<td colspan="2" style="text-align: center; background-color: #00ffff;">
1.108 +{@link org.apache.http.conn.ClientConnectionOperator}
1.109 +</td>
1.110 +</tr>
1.111 +
1.112 +<tr>
1.113 +<td colspan="2" style="text-align: center; background-color: #00ffff;">
1.114 +{@link org.apache.http.conn.OperatedClientConnection}
1.115 +</td>
1.116 +</tr>
1.117 +
1.118 +</table>
1.119 +</center>
1.120 +
1.121 +<p>
1.122 +The Manager area has implementations for the connection management
1.123 +interfaces {@link org.apache.http.conn.ClientConnectionManager}
1.124 +and {@link org.apache.http.conn.ManagedClientConnection}.
1.125 +The latter is an adapter from managed to operated connections, based on a
1.126 +{@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}.
1.127 +<br/>
1.128 +The Pool area shows an abstract pool class
1.129 +{@link org.apache.http.impl.conn.tsccm.AbstractConnPool}
1.130 +and a concrete implementation
1.131 +{@link org.apache.http.impl.conn.tsccm.ConnPoolByRoute}
1.132 +which uses the same basic algorithm as the
1.133 +<code>MultiThreadedHttpConnectionManager</code>
1.134 +in HttpClient 3.x.
1.135 +A pool contains instances of
1.136 +{@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}.
1.137 +Most other classes in this package also belong to the Pool area.
1.138 +<br/>
1.139 +In the Operations area, you will find only the interfaces for
1.140 +operated connections as defined in the org.apache.http.conn package.
1.141 +The connection manager will work with all correct implementations
1.142 +of these interfaces. This package therefore does not define anything
1.143 +specific to the Operations area.
1.144 +</p>
1.145 +
1.146 +<p>
1.147 +As you have surely noticed, the
1.148 +{@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}
1.149 +appears in both the Manager and Pool areas.
1.150 +This is where things get tricky for connection garbage collection.
1.151 +<br/>
1.152 +A connection pool may start a background thread to implement cleanup.
1.153 +In that case, the connection pool will not be garbage collected until
1.154 +it is shut down, since the background thread keeps a hard reference
1.155 +to the pool. The pool itself keeps hard references to the pooled entries,
1.156 +which in turn reference idle connections. Neither of these is subject
1.157 +to garbage collection.
1.158 +Only the shutdown of the pool will stop the background thread,
1.159 +thereby enabling garbage collection of the pool objects.
1.160 +<br/>
1.161 +A pool entry that is passed to an application by means of a connection
1.162 +adapter will move from the Pool area to the Manager area. When the
1.163 +connection is released by the application, the manager returns the
1.164 +entry back to the pool. With that step, the pool entry moves from
1.165 +the Manager area back to the Pool area.
1.166 +While the entry is in the Manager area, the pool MUST NOT keep a
1.167 +hard reference to it.
1.168 +</p>
1.169 +
1.170 +<p>
1.171 +The purpose of connection garbage collection is to detect when an
1.172 +application fails to return a connection. In order to achieve this,
1.173 +the only hard reference to the pool entry in the Manager area is
1.174 +in the connection wrapper. The manager will not keep a hard reference
1.175 +to the connection wrapper either, since that wrapper is effectively
1.176 +moving to the Application area.
1.177 +If the application drops it's reference to the connection wrapper,
1.178 +that wrapper will be garbage collected, and with it the pool entry.
1.179 +<br/>
1.180 +In order to detect garbage collection of pool entries handed out
1.181 +to the application, the pool keeps a <i>weak reference</i> to the
1.182 +entry. Instances of
1.183 +{@link org.apache.http.impl.conn.tsccm.BasicPoolEntryRef}
1.184 +combine the weak reference with information about the route for
1.185 +which the pool entry was allocated. If one of these entry references
1.186 +becomes stale, the pool can accommodate for the lost connection.
1.187 +This is triggered either by a background thread waiting for the
1.188 +references to be queued by the garbage collector, or by the
1.189 +application calling a {@link
1.190 + org.apache.http.conn.ClientConnectionManager#closeIdleConnections cleanup}
1.191 +method of the connection manager.
1.192 +<br/>
1.193 +Basically the same trick is used for detecting garbage collection
1.194 +of the connection manager itself. The pool keeps a weak reference
1.195 +to the connection manager that created it. However, this will work
1.196 +only if there is a background thread to detect when that reference
1.197 +is queued by the garbage collector. Otherwise, a finalizer of the
1.198 +connection manager will shut down the pool and release it's resources.
1.199 +</p>
1.200 +
1.201 +
1.202 +</body>
1.203 +</html>
