gzz.util
Class Pool

java.lang.Object
  |
  +--gzz.util.Pool

public abstract class Pool

extends java.lang.Object

A pool for throw-away objects. This is an experiment for solving our problem with object creation cost (esp. on Kaffe). It caches throw-away objects like vobs, and allows them to be explicitly released-- but still keeps a reference to them, so that they won't be gc'ed. The next time an object of that type is needed, the released object will be used.

This means that every object of that type (a Pool instance is type-specific) needs to be created through the pool, so that an old, released instance can be used if there is one.

Note that Pool needs to be subclassed, and the abstract create() method has to be implemented. This method creates a new instance of the class the Pool caches. Also, by convention a get(...) should be implemented that takes the same parameters as the constructor of the served class; for example, a FooPool class that caches instances of class Foo, which has the constructors Foo() and Foo(int i), should define the methods Foo FooPool.get() and Foo FooPool.get(int i).

The get(...) method should call getObject(), defined in Pool, cast the result to the correct class (in our example, Foo), and do whatever the corresponding constructor would do.

Caution: This code makes the assumption that all object instances requested from it will be released relatively soon. If references are held for a longer time, those object instances must be created normally; otherwise, Pool might trample a lot of memory.

XXX Currently, the object instances are kept forever. At some point, we will probably want to have something like a pack() method that throws away all currently unused, cached object instances, because we will e.g. have more exotic Vob types which we use a lot for some views, but not at all most of the time.

Nested Class Summary

static class	Pool.AbstractPoolable An abstract implementation of Poolable.
static interface	Pool.Poolable

Field Summary

protected Pool.Poolable[]	cache The cache of Poolables.
protected int	endIndex The index of the last used object in the cache array, plus one.
static int	INITIAL_LENGTH The initial size of the cache array.
static java.lang.String	rcsid
protected int	startIndex The index of the first used object in the cache array.
protected boolean[]	used An array of the same length as cache, determining for every element of cache whether it is currently used.

Constructor Summary

Pool()

Method Summary

protected abstract Pool.Poolable	create() Create a new object of the type cached by this Pool.
protected Pool.Poolable	getObject() Get a Placeable object not yet casted to the class this Pool caches.
void	release(int index) Release the object instance at the given index in the pool.

Methods inherited from class java.lang.Object

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

Field Detail

rcsid

public static final java.lang.String rcsid

See Also:

Constant Field Values

INITIAL_LENGTH

public static final int INITIAL_LENGTH

The initial size of the cache array. Note: no new objects are created until specifically requested. Initially, all the pointers in the cache array are to null.

See Also:

Constant Field Values

cache

protected Pool.Poolable[] cache

The cache of Poolables. Valid at least up to endIndex-1. When looking beyond endIndex-1, one must test for null entries and possibly create new objects through create().

used

protected boolean[] used

An array of the same length as cache, determining for every element of cache whether it is currently used. Unused elements can be claimed inside the getObject() method. (Note, though, that it may be null, in which case it will be initialized though the create() method.

See Also:

cache, getObject()

startIndex

protected int startIndex

The index of the first used object in the cache array. startIndex must be <= endIndex.

Note: there won't be any used objects with an index < startIndex or >= endIndex, but there may be unused objects >= startIndex and < endIndex, because objects can be released in a different order than they were requested in the first place.

endIndex

protected int endIndex

The index of the last used object in the cache array, plus one.

Constructor Detail

Pool

public Pool()

Method Detail

create

protected abstract Pool.Poolable create()

Create a new object of the type cached by this Pool. This method is called by the getObject() method when there is no cached, currently unused instance. It does not have to worry about putting the object into the cache array or about calling setPool in the Poolable: the getObject() method will take care of that.

getObject

protected final Pool.Poolable getObject()

Get a Placeable object not yet casted to the class this Pool caches. If there is an unused object instance available, it is returned (and claimed as used); otherwise, a new instance is created and put into the cache.

release

public final void release(int index)

Release the object instance at the given index in the pool. This is normally called by the Poolable.release() convenience function.