lava.util
Class ObjectRecycler

java.lang.Object
  |
  +--lava.util.ObjectRecycler

public class ObjectRecycler

extends java.lang.Object

Maintains a pool of recyclable objects.

Details: ObjectRecycler provides a mechanism for avoiding the overhead of perpetual object construction and destruction, in programs that otherwise would repetitively instantiate objects of a certain class, use them momentarily, and then discard them. ObjectRecycler allows retired objects to be manually returned to a pool for later reuse.

Each ObjectRecycler is permanently associated with a Class. Calls to construct return either a new instance of the class, or an old instance that has been used and returned to the pool. When new instances are constructed, the default constructor is used. New instances are constructed only when the pool is empty. When old instances are reused, no initialization is performed on them; they are returned in the same condition they were in when they were recycled. If additional initialization requirements exist, the developer should implement the necessary behavior in a subclass of ObjectRecycler.

class StringBufferRecycler
	extends ObjectRecycler
{
	StringBufferRecycler ()
	{
		super (new StringBuffer () . getClass (), 10);
	}
	StringBuffer getBuffer ()
	{
		StringBuffer buf = (StringBuffer) construct ();
		buf . setLength (0);
		return buf;
	}
}

Since:

1999.03.15

Author:

Sharky

Field Summary

protected java.lang.Class	cls The class of objects maintained by this pool.
protected int	max_size Maximum size of pool.
protected java.util.Stack	pool The pool.

Constructor Summary

ObjectRecycler(java.lang.Class cls, int max_size)
Indicates the cls of this pool.

Method Summary

java.lang.Object	construct() Returns an instance of cls.
void	recycle(java.lang.Object o) Returns an instance to the pool.

Methods inherited from class java.lang.Object

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

Field Detail

cls

protected final java.lang.Class cls

The class of objects maintained by this pool.

Details: All objects handled by this ObjectRecycler are immediate instances of class.

pool

protected final java.util.Stack pool

The pool.

Details: The pool is maintained as a Stack so that instances most recently recycled will be immediately reused. This will increase object locality and, hopefully, allow for better cache performance.

max_size

protected final int max_size

Maximum size of pool.

Details: max_size is the maximum number of objects that can be stored in the pool. When the pool is full and additional objects are recycled, they are not entered into the pool. (Presumably, these rejected objects will be garbage collected.)

Constructor Detail

ObjectRecycler

public ObjectRecycler(java.lang.Class cls,
                      int max_size)

Indicates the cls of this pool.

Details: This constructor binds this ObjectRecycler to the given class. All objects that enter and leave the pool will be direct instances of cls. (Hence, cls must not be abstract.)

Parameters:

max_size - maximum pool size

cls - the pool cls

Method Detail

construct

public java.lang.Object construct()

Returns an instance of cls.

Details: construct returns an instance of cls from the pool, or constructs and returns a new one if the pool is empty, using the default constructor for cls.

If this method is called but there is no accessible default constructor for cls, an UnreachableCodeException will be thrown. This indicates programmer error.

Returns:

a new or used instance

recycle

public void recycle(java.lang.Object o)

Returns an instance to the pool.

Details: recycle enters the given object into the pool, for later reuse, with the assumption that no other threads or objects will be using it anymore. If this assumption is wrong, the results may be disasterous.

Parameters:

o - the instance to recycle