Commons Pool

The Commons Pool project is built around a single idea - the creation of an ObjectPool. This page captures our “best practices” discovered over the course of building the GeoTools project.

References:

• http://commons.apache.org/pool/

ObjectPool as a Cache

You can configure an SoftReferenceObjectPool to use weak references, the result functions the same as a cache.

ObjectPool for Interning

You can configure an ObjectPool to use weak references in order to “Intern” objects and prevent duplicates from being used in your application.

ObjectPool as a Pool

First comes the set up - so the object pool can create the objects as needed.:

public interface KeyedPoolableObjectFactory {
  Object makeObject(Object key);
  void activateObject(Object key, Object obj);
  void passivateObject(Object key, Object obj);
  boolean validateObject(Object key, Object obj);
  void destroyObject(Object key, Object obj);
}

ObjectPool Configuration

And then comes the configuration (of GenericKeyedObjectPool ):

• Number of Objects

  maxActive

  capacity of created objects

  maxIdle

  maximum number of lurkers

• What to do when at capacity:

  whenExhausedAction

  fail, grow or block when capacity reached

• When to check objects in pool

  testOnBorrow

  Check with validateObject when borrowed

  testOnreturn

  Check with validateObject when returned

  testWhenIdle

  Check with validateObject from the eviction thread

• Eviction Thread

  timeBetweenEvictionRunsMillis

  Time to sleep

  minEvictableIdleTimeMills

  time to wait before an object could be cleaned up

The way it works is this, for a maxActive of 20 at most 20 objects will be created. If they are all returned the pool will throw the instances away until it has maxIdle (this is kind of its comfort zone). After this point each object will have to time out (based on minEvictableIdleTimeMills) before it is reclaimed.:

   maxActive
/--This is the absolute capacity of our ObjectCache
|
|  Objects are immediately evicted when they are not in use
|
\-> maxIdle
/-- This is the "comfort zone" that your ObjectCache will try for under heavy use
|
|  Objects are evicted when they have not been used, every minEvictableIdleTimeMills
|
\-> Empty

Eviction

Here is how eviction works:

1. it will grab numTestsPerEvictionRun objects from the pool
2. for any object that has exceeded minEvictableIdleTimeMillis it will call validateObject
3. it will throw away any object that fails the validateObject test
4. If we have less than minIdle left in the pool new objects will be spawned

You can perform eviction in a thread controlled by setting testWhenIdle and providing a value for timeBetweenEvictionRunsMillis.

GenericObjectPool Configuration

GenericObjectPool introduces the concept of a “soft min” operating as a preferred number object objects to hold in reserved (even when we are completly idle).

This concept is a little freaky in that it looks like the GenericObjectPool will create these objects in a background thread even if nothing is going on.

minIdle

minimum number of lurkers

softMinEvictableIdleTimeMills

time to wait before an object is cleaned up

The way it works is this, for a maxActive of 20 at most 20 objects will be created. If they are all returned the pool will throw the instances away until it has maxIdle (this is kind of its comfort zone). As each object times out we will be left with minIdel number of objects in the pool.:

   maxActive
/--This is the absolute capacity of our ObjectCache
|
|  Objects are immediately evicted when they are not in use
|
\-> maxIdle
/-- This is the "comfort zone" that your ObjectCache will try for under heavy use
|
|  Objects are evicted when they have not been used, every minEvictableIdleTimeMills
|
\-> minIdle
/-> This is the number of Objects reserved when we are completely idle
|
| Objects are spawned as needed, every softMinEvictableIdleTimeMills
|
\-- Empty