| <html> |
| <head> |
| <!-- |
| /* |
| * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/module-client/src/main/java/org/apache/http/impl/conn/tsccm/package.html $ |
| * $Revision: 653041 $ |
| * $Date: 2008-05-03 03:39:28 -0700 (Sat, 03 May 2008) $ |
| * |
| * ==================================================================== |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| * ==================================================================== |
| * |
| * This software consists of voluntary contributions made by many |
| * individuals on behalf of the Apache Software Foundation. For more |
| * information on the Apache Software Foundation, please see |
| * <http://www.apache.org/>. |
| * |
| */ |
| --> |
| </head> |
| <body> |
| |
| The implementation of a thread-safe client connection manager. |
| |
| <center> |
| <img src="doc-files/tsccm-structure.png" alt="Relation Diagram"/> |
| </center> |
| |
| <p> |
| The implementation is structured into three areas, as illustrated |
| by the diagram above. |
| Facing the application is the <i>Manager</i> (green), which internally |
| maintains a <i>Pool</i> (yellow) of connections and waiting threads. |
| Both Manager and Pool rely on <i>Operations</i> (cyan) to provide the |
| actual connections. |
| </p> |
| <p> |
| In order to allow connection garbage collection, it is |
| imperative that hard object references between the areas are |
| restricted to the relations indicated by arrows in the diagram: |
| </p> |
| <ul> |
| <li>Applications reference only the Manager objects.</li> |
| <li>Manager objects reference Pool objects, but not vice versa.</li> |
| <li>Operations objects do not reference either Manager or Pool objects.</li> |
| </ul> |
| |
| <p> |
| The following table shows a selection of classes and interfaces, |
| and their assignment to the three areas. |
| </p> |
| <center> |
| <table border="1"> |
| <colgroup> |
| <col width="50%"/> |
| <col width="50%"/> |
| </colgroup> |
| |
| <tr> |
| <td style="text-align: center; background-color: #00ff00;"> |
| {@link org.apache.http.impl.conn.tsccm.ThreadSafeClientConnManager} |
| </td> |
| <td style="text-align: center; background-color: #ffff00;"> |
| {@link org.apache.http.impl.conn.tsccm.AbstractConnPool} |
| </td> |
| </tr> |
| |
| <tr> |
| <td style="text-align: center; background-color: #00ff00;"> |
| {@link org.apache.http.impl.conn.tsccm.BasicPooledConnAdapter} |
| </td> |
| <td style="text-align: center; background-color: #ffff00;"> |
| {@link org.apache.http.impl.conn.tsccm.ConnPoolByRoute} |
| </td> |
| </tr> |
| |
| <!-- appears on both sides! --> |
| |
| <tr> |
| <td style="text-align: right; background-color: #00ff00;"> |
| {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry} |
| </td> |
| <td style="text-align: left; background-color: #ffff00;"> |
| {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry} |
| </td> |
| </tr> |
| |
| <!-- ====================== --> |
| |
| <tr style="border-width: 5px;"> |
| </tr> |
| |
| <tr> |
| <td colspan="2" style="text-align: center; background-color: #00ffff;"> |
| {@link org.apache.http.conn.ClientConnectionOperator} |
| </td> |
| </tr> |
| |
| <tr> |
| <td colspan="2" style="text-align: center; background-color: #00ffff;"> |
| {@link org.apache.http.conn.OperatedClientConnection} |
| </td> |
| </tr> |
| |
| </table> |
| </center> |
| |
| <p> |
| The Manager area has implementations for the connection management |
| interfaces {@link org.apache.http.conn.ClientConnectionManager} |
| and {@link org.apache.http.conn.ManagedClientConnection}. |
| The latter is an adapter from managed to operated connections, based on a |
| {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}. |
| <br/> |
| The Pool area shows an abstract pool class |
| {@link org.apache.http.impl.conn.tsccm.AbstractConnPool} |
| and a concrete implementation |
| {@link org.apache.http.impl.conn.tsccm.ConnPoolByRoute} |
| which uses the same basic algorithm as the |
| <code>MultiThreadedHttpConnectionManager</code> |
| in HttpClient 3.x. |
| A pool contains instances of |
| {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry}. |
| Most other classes in this package also belong to the Pool area. |
| <br/> |
| In the Operations area, you will find only the interfaces for |
| operated connections as defined in the org.apache.http.conn package. |
| The connection manager will work with all correct implementations |
| of these interfaces. This package therefore does not define anything |
| specific to the Operations area. |
| </p> |
| |
| <p> |
| As you have surely noticed, the |
| {@link org.apache.http.impl.conn.tsccm.BasicPoolEntry} |
| appears in both the Manager and Pool areas. |
| This is where things get tricky for connection garbage collection. |
| <br/> |
| A connection pool may start a background thread to implement cleanup. |
| In that case, the connection pool will not be garbage collected until |
| it is shut down, since the background thread keeps a hard reference |
| to the pool. The pool itself keeps hard references to the pooled entries, |
| which in turn reference idle connections. Neither of these is subject |
| to garbage collection. |
| Only the shutdown of the pool will stop the background thread, |
| thereby enabling garbage collection of the pool objects. |
| <br/> |
| A pool entry that is passed to an application by means of a connection |
| adapter will move from the Pool area to the Manager area. When the |
| connection is released by the application, the manager returns the |
| entry back to the pool. With that step, the pool entry moves from |
| the Manager area back to the Pool area. |
| While the entry is in the Manager area, the pool MUST NOT keep a |
| hard reference to it. |
| </p> |
| |
| <p> |
| The purpose of connection garbage collection is to detect when an |
| application fails to return a connection. In order to achieve this, |
| the only hard reference to the pool entry in the Manager area is |
| in the connection wrapper. The manager will not keep a hard reference |
| to the connection wrapper either, since that wrapper is effectively |
| moving to the Application area. |
| If the application drops it's reference to the connection wrapper, |
| that wrapper will be garbage collected, and with it the pool entry. |
| <br/> |
| In order to detect garbage collection of pool entries handed out |
| to the application, the pool keeps a <i>weak reference</i> to the |
| entry. Instances of |
| {@link org.apache.http.impl.conn.tsccm.BasicPoolEntryRef} |
| combine the weak reference with information about the route for |
| which the pool entry was allocated. If one of these entry references |
| becomes stale, the pool can accommodate for the lost connection. |
| This is triggered either by a background thread waiting for the |
| references to be queued by the garbage collector, or by the |
| application calling a {@link |
| org.apache.http.conn.ClientConnectionManager#closeIdleConnections cleanup} |
| method of the connection manager. |
| <br/> |
| Basically the same trick is used for detecting garbage collection |
| of the connection manager itself. The pool keeps a weak reference |
| to the connection manager that created it. However, this will work |
| only if there is a background thread to detect when that reference |
| is queued by the garbage collector. Otherwise, a finalizer of the |
| connection manager will shut down the pool and release it's resources. |
| </p> |
| |
| |
| </body> |
| </html> |