net.sf.eBus.util

Class IndexPool

java.lang.Object

net.sf.eBus.util.IndexPool

All Implemented Interfaces:

Serializable

public final class IndexPool
extends Object
implements Serializable

IndexPool provides integer index value reuse. When you create an IndexPool, you may specify the minimum and maximum allowed values (inclusive). You retrieve the next available value using nextIndex() and return values to the pool with returnIndex(int). When the pool is exhausted, nextIndex() throws an IllegalStateException. The application is responsible for returning unused indices to the pool by calling returnIndex(int). The application is also responsible for making sure that returnIndex(int) calls contain unique indicies and that the same index does not appear in the pool multiple times.

IndexPool uses both an AtomicInteger and a ConcurrentLinkedDeque (as a stack) to track available indices. When nextIndex() is called, it first checks if the index stack is empty. If it is empty, then AtomicInteger.getAndIncrement() is called to get the next unused index. If the returned value is > than the maximum allowed index, then IllegalStateException exception is thrown. If the index stack is not empty, then the an index is popped off the stack and returned. The idea behind this technique is to continually use the same indices in the hopes this improves processor cache hits.

IndexPool has no memory between application executions. If you need to persist index values between executions, use IndexCache.

Note: IndexPool is synchronized. It is safe for multiple threads to access the same IndexPoool instance without synchronizing.

Author:

Charles Rapp

See Also:

IndexCache, Serialized Form

Constructor Summary

Constructors

Constructor and Description
IndexPool() Creates a pool with the default size.
IndexPool(int minIndex, int maxIndex) Creates a pool with the specified minimum and maximum indicies (inclusive).

Method Summary

Modifier and Type	Method and Description
int	maxIndex() Returns the pool's maximum index.
int	minIndex() Returns the pool's minimum index.
int	nextIndex() Returns the next available index.
void	reset() Resets the index pool to its initial state.
void	returnIndex(int index) Puts an index back into the pool for reuse.
String	toString() Returns a textual representation of this index pool.

Methods inherited from class java.lang.Object

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

Constructor Detail

IndexPool

public IndexPool()

Creates a pool with the default size.

The default settings are:

• Minimum index is zero (this will be the first assigned value).
• Maximum index is Integer.MAX_VALUE.

IndexPool

public IndexPool(int minIndex,
                 int maxIndex)
          throws IllegalArgumentException

Creates a pool with the specified minimum and maximum indicies (inclusive).

Parameters:

minIndex - the minimum index (nextIndex() will return this value first.)

maxIndex - the maximum index (inclusive).

Throws:

IllegalArgumentException - if:

• minIndex is <= zero.
• maxIndex is <= zero.
• minIndex is > maxIndex.

Method Detail

toString

public String toString()

Returns a textual representation of this index pool.

Overrides:

toString in class Object

Returns:

a textual representation of this index pool.

minIndex

public int minIndex()

Returns the pool's minimum index.

Returns:

the pool's minimum index.

maxIndex

public int maxIndex()

Returns the pool's maximum index.

Returns:

the pool's maximum index.

nextIndex

public int nextIndex()
              throws IllegalStateException

Returns the next available index.

Returns:

the next available index.

Throws:

IllegalStateException - if all indices are in use and the pool is exhausted. This may be due to a failure to return unused indicies to the pool.

returnIndex

public void returnIndex(int index)
                 throws IndexOutOfBoundsException

Puts an index back into the pool for reuse.

Note: this method does not prevent returning the same index to the pool multiple times. It is the caller's responsibility to make sure that an index appears only once in the pool.

Parameters:

index - Put this index back in the pool.

Throws:

IndexOutOfBoundsException - if index is less than the minimum index value or greater than or equal to the maximum index value.

reset

public void reset()

Resets the index pool to its initial state. All indices are available for use. Any outstanding indices are invalid.