org.apache.avalon.excalibur.pool
Class ResourceLimitingPool

java.lang.Object
  org.apache.avalon.framework.logger.AbstractLogEnabled
      org.apache.avalon.excalibur.pool.ResourceLimitingPool

All Implemented Interfaces:

Disposable, LogEnabled, Pool, ThreadSafe

public class ResourceLimitingPool

extends AbstractLogEnabled

implements Pool, LogEnabled, Disposable, ThreadSafe

General Pool implementation which supports; weak and strong pool size limits, optional blocking gets when poolables are not available, and automatic pool trimming of unused poolables.

Whenever get() is called, the pool tests to see whether it is time to trim old poolables from the pool. If any old poolables exist then they are removed at this time. This means that old poolables will not be removed if get() is never called. Applications can optionally call trim() to force old objects to be trimmed. See the trim() method for details of how trimming works.

Since:

4.1

Version:

CVS $Revision: 1.5 $ $Date: 2004/03/29 16:50:37 $

Author:

Avalon Development Team

Field Summary

protected java.lang.Object

m_semaphore Object used to synchronize access to the get and put methods

Constructor Summary

ResourceLimitingPool(ObjectFactory factory, int max, boolean maxStrict, boolean blocking, long blockTimeout, long trimInterval)
Creates a new ResourceLimitingPool

Method Summary

void	dispose() The dispose operation is called at the end of a components lifecycle.
Poolable	get() Gets a Poolable from the pool.
int	getReadySize() Returns the number of available Poolables waiting in the pool.
int	getSize() Returns the total number of Poolables created by the pool.
protected Poolable	newPoolable() Create a new poolable instance by by calling the newInstance method on the pool's ObjectFactory.
protected void	permanentlyRemovePoolable(Poolable poolable) Permanently removes a poolable from the pool's active list and destroys it so that it will not ever be reused.
void	put(Poolable poolable) Returns a poolable to the pool and notifies any thread blocking.
protected void	removePoolable(Poolable poolable) Called when an object is being removed permanently from the pool.
int	trim() Forces the pool to trim, remove, old Poolables from the pool.

Methods inherited from class org.apache.avalon.framework.logger.AbstractLogEnabled

enableLogging, getLogger, setupLogger, setupLogger, setupLogger

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.avalon.framework.logger.LogEnabled

enableLogging

Field Detail

m_semaphore

protected final java.lang.Object m_semaphore

Object used to synchronize access to the get and put methods

Constructor Detail

ResourceLimitingPool

public ResourceLimitingPool(ObjectFactory factory,
                            int max,
                            boolean maxStrict,
                            boolean blocking,
                            long blockTimeout,
                            long trimInterval)

Creates a new ResourceLimitingPool

Parameters:

factory - The ObjectFactory which will be used to create new Poolables as needed by the pool.

max - Maximum number of Poolables which can be stored in the pool, 0 implies no limit.

maxStrict - true if the pool should never allow more than max Poolable to be created. Will cause an exception to be thrown if more than max Poolables are requested and blocking is false.

blocking - true if the pool should cause a thread calling get() to block when Poolables are not currently available in the pool.

blockTimeout - The maximum amount of time, in milliseconds, that a call to get() will block before an exception is thrown. A value of 0 implies an indefinate wait.

trimInterval - The minimum interval with which old unused poolables will be removed from the pool. A value of 0 will cause the pool to never trim poolables.

Method Detail

get

public Poolable get()
             throws java.lang.Exception

Gets a Poolable from the pool. If there is room in the pool, a new Poolable will be created. Depending on the parameters to the constructor, the method may block or throw an exception if a Poolable is not available on the pool.

Specified by:

get in interface Pool

Returns:

Always returns a Poolable. Contract requires that put must always be called with the Poolable returned.

Throws:

java.lang.Exception - An exception may be thrown as described above or if there is an exception thrown by the ObjectFactory's newInstance() method.

put

public void put(Poolable poolable)

Returns a poolable to the pool and notifies any thread blocking.

Specified by:

put in interface Pool

Parameters:

poolable - Poolable to return to the pool.

dispose

public void dispose()

The dispose operation is called at the end of a components lifecycle. This method will be called after Startable.stop() method (if implemented by component). Components use this method to release and destroy any resources that the Component owns.

Specified by:

dispose in interface Disposable

permanentlyRemovePoolable

protected void permanentlyRemovePoolable(Poolable poolable)

Permanently removes a poolable from the pool's active list and destroys it so that it will not ever be reused.

This method is only called by threads that have m_semaphore locked.

getSize

public int getSize()

Returns the total number of Poolables created by the pool. Includes active and ready.

getReadySize

public int getReadySize()

Returns the number of available Poolables waiting in the pool.

newPoolable

protected Poolable newPoolable()
                        throws java.lang.Exception

Create a new poolable instance by by calling the newInstance method on the pool's ObjectFactory.

This is the method to override when you need to enforce creational policies.

This method is only called by threads that have m_semaphore locked.

Throws:

java.lang.Exception

removePoolable

protected void removePoolable(Poolable poolable)

Called when an object is being removed permanently from the pool. This is the method to override when you need to enforce destructional policies.

This method is only called by threads that have m_semaphore locked.

Parameters:

poolable - Poolable to be completely removed from the pool.

trim

public int trim()

Forces the pool to trim, remove, old Poolables from the pool. If the Pool was created with a non-zero value for trimInterval, then this method will be called at that interval when get() is called. If get() is not called for long periods of time then if may be necessary to call this method manually.

Trimming is done by maintaining two lists of objects. The first is a ready list of new poolables. The second is a list of old poolables. Each time trim() is called, the contents of the old list are removed from the pool. Then the contents of the new list is moved into the old list.

Each time get() is called on the pool, the new list is checked first, then the old list is checked, finally a new poolable may be created if both lists are empty. Then whenever put() is called, the poolables are always returned to the new list. In this way, the need for maining time stamps for each poolable can be avoided while at the same time avoiding unnecessary removal and creation on poolables.

This works out to a poolable having a maximum idle time of two calls to trim() or twice the value of trimInterval.

NOTE - The trimming feature does not harm performance because pools with high load will not have old poolables to be trimmed, and the benefits to system resources from not keeping around unused poolables makes up for any hit.

Returns:

the number of Poolables that were trimmed.