+The implementation is structured into three areas, as illustrated +by the diagram above. +Facing the application is the Manager (green), which internally +maintains a Pool (yellow) of connections and waiting threads. +Both Manager and Pool rely on Operations (cyan) to provide the +actual connections. +
+ +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: + ++The following table shows a selection of classes and interfaces, +and their assignment to the three areas. +
+| +{@link org.apache.http.impl.conn.tsccm.ThreadSafeClientConnManager} + | ++{@link org.apache.http.impl.conn.tsccm.AbstractConnPool} + | +
| +{@link org.apache.http.impl.conn.tsccm.TSCCMConnAdapter} + | ++{@link org.apache.http.impl.conn.tsccm.ConnPoolByRoute} + | +
| +{@link org.apache.http.impl.conn.tsccm.BasicPoolEntry} + | ++{@link org.apache.http.impl.conn.tsccm.BasicPoolEntry} + | +
| +{@link org.apache.http.conn.ClientConnectionOperator} + | +|
| +{@link org.apache.http.conn.OperatedClientConnection} + | +|
+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}.
+
+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
+MultiThreadedHttpConnectionManager
+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.
+
+In the Operations area, you will find only the interfaces for
+operated connections as defined in {@link org.apache.http.conn}.
+The connection manager will work with all correct implementations
+of these interfaces. This package therefore does not define anything
+specific to the Operations area.
+
+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.
+
+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.
+
+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.
+
+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.
+
+In order to detect garbage collection of pool entries handed out
+to the application, the pool keeps a weak reference 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.
+
+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.
+