ecologylab.generic
Class ResourcePool<T>

java.lang.Object
  ecologylab.generic.Debug
      ecologylab.generic.ResourcePool<T>

Direct Known Subclasses:

MessageWithMetadataPool, ResourcePoolWithSize, XMLReaderPool

public abstract class ResourcePool<T>
extends Debug

This class provides access to a pool of pre-allocated resources. The pool grows and contracts throughout its lifetime to suit the number of resources necessary and to attempt to minimize memory footprints; acquire() and release() are amortized O(1) complexity (although expansion/contraction triggers may take longer). The primary way of accessing resources that are controlled by a pool are through the acquire and release methods. Every acquire should have a matching release, to ensure that resources may be recycled by later calls to acquire. Subclasses of ResourcePool ensure that the resources obtained through the acquire method are "clean", that is, they are immediately ready for use as if they were just instantiated.

Author:

Zach Toups (toupsz@gmail.com)

Field Summary

protected static int

DEFAULT_POOL_SIZE

Constructor Summary

protected	ResourcePool(boolean instantiateResourcesInPool, int initialPoolSize, int minimumPoolSize) Special constructor that will only instantiate the backing pool resources if the first argument is true.
	ResourcePool(int initialPoolSize, int minimumPoolSize) Creates a new ResourcePool with the specified initialPoolSize (or minimumPoolSize, minimumPoolSize > initialPoolSize) and minimum capacity.

Method Summary

T	acquire() Take a resource from the pool, making it unavailable for other segments of the program to use.
protected abstract void	clean(T objectToClean) Ensure that the given Object is "clean", that is, in the state it would be in if it were just instantiated.
protected abstract T	generateNewResource() Instantiates a resource of type T.
protected void	instantiateResourcesInPool()
T	release(T resourceToRelease) Return a resource for use by another part of the program.

Methods inherited from class ecologylab.generic.Debug

classSimpleName, closeLoggingFile, debug, debug, debug, debug, debugA, debugA, debugA, debugI, debugI, debugI, error, error, getClassName, getClassName, getInteractive, getPackageName, getPackageName, getPackageName, initialize, level, level, level, logToFile, print, print, println, println, println, println, println, println, printlnA, printlnA, printlnA, printlnI, printlnI, printlnI, printlnI, setLoggingFile, show, show, superString, toggleInteractive, toString, toString, warning, warning, weird, weird

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_POOL_SIZE

protected static final int DEFAULT_POOL_SIZE

See Also:

Constant Field Values

Constructor Detail

ResourcePool

protected ResourcePool(boolean instantiateResourcesInPool,
                       int initialPoolSize,
                       int minimumPoolSize)

Special constructor that will only instantiate the backing pool resources if the first argument is true. This method can be used by subclasses to set up member variables before calling instantiateResourcesInPool(), so that the instantiation will use the member variables.

Parameters:

instantiateResourcesInPool -

initialPoolSize -

minimumPoolSize -

ResourcePool

public ResourcePool(int initialPoolSize,
                    int minimumPoolSize)

Creates a new ResourcePool with the specified initialPoolSize (or minimumPoolSize, minimumPoolSize > initialPoolSize) and minimum capacity. Note that this constructor will call generateNewResource (capacity) times to fill in the backing collection. If generateNewResource relies upon setting fields, the subclass should *NOT* call this constructor and should instead call ResourcePool(boolean, int, int).

Parameters:

initialPoolSize - the initial size of the backing pool of objects.

minimumPoolSize - the minimum size for the backing pool of objects. This is important to specify, otherwise repeatedly aquire()'ing and release()'ing resources can have detrimental performance effects.

Method Detail

acquire

public final T acquire()

Take a resource from the pool, making it unavailable for other segments of the program to use. Objects returned by calls to acquire() are "clean", that is, they are in the same state they would be in as if they were just instantiated.

Returns:

release

public final T release(T resourceToRelease)

Return a resource for use by another part of the program. The resource will be cleaned at some later time when it is acquire()'ed. Resources that are released should NOT be used again.

Parameters:

resourceToRelease -

Returns:

null; this is meant as a convienence, so that the programmer can use the line: resource = recPool.release(resource);, automatically unlinking the released resource from the binding in the resource user's code.

generateNewResource

protected abstract T generateNewResource()

Instantiates a resource of type T.

Returns:

clean

protected abstract void clean(T objectToClean)

Ensure that the given Object is "clean", that is, in the state it would be in if it were just instantiated. For example, if this class were handling StringBuilders, it should ensure that the StringBuilder does not contain any characters from a previous use. clean(T) is automatically called immediately before an object is returned from the acquire() method.

Parameters:

objectToClean -

instantiateResourcesInPool

protected void instantiateResourcesInPool()