The Tor Browser / file comparison
comparison: mobile/android/thirdparty/ch/boye/httpclientandroidlib/impl/conn/tsccm/package.html
mobile/android/thirdparty/ch/boye/httpclientandroidlib/impl/conn/tsccm/package.html
- branch
- TOR_BUG_3246
- changeset 4
- fc2d59ddac77
equal
deleted
inserted
replaced
| -1:000000000000 | 0:61f6eabb1c3f |
|---|---|
| 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. | |
| 34 | |
| 35 <center> | |
| 36 <img src="doc-files/tsccm-structure.png" alt="Relation Diagram"/> | |
| 37 </center> | |
| 38 | |
| 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> | |
| 57 | |
| 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> | |
| 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> | |
| 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> | |
| 142 | |
| 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> | |
| 166 | |
| 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> | |
| 197 | |
| 198 | |
| 199 </body> | |
| 200 </html> |
