Package net.sf.eBus.util

Class 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 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)
        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()
        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)
        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.