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:

it will grab numTestsPerEvictionRun objects from the pool
for any object that has exceeded minEvictableIdleTimeMillis it will call validateObject
it will throw away any object that fails the validateObject test
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 completely 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 minIdle 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

GeoTools

OSGeo