com.dautelle.realtime
Class ArrayPool

java.lang.Object
  com.dautelle.realtime.ArrayPool

public final class ArrayPool

extends java.lang.Object

This class provides static methods to return ObjectPool for array of any type. The pool returned allocates arrays from the "stack" when the current thread executes in PoolContext.

Allocating large arrays is very time consuming and prone to garbage collection interrruptions. It is therefore highly recommended to use this class when new arrays are dynamically allocated.

Applications may create arrays of any component type including primitive types. For example:

     char[] chars = (char[]) ArrayPool.charArray(128).next();
     Thread[] threads = (Thread[]) ArrayPool.array(Thread.class, 64).next();
     

The arrays returned may have a length larger than the specified capacity. If the exact length is required then custom ObjectFactory should be used instead.

Arrays may be individually recycled when it can be asserted that the arrays will not be referenced anymore. For example:

     ObjectPool pool = ArrayPool.charArray(1024);
     char[] buffer = (char[]) pool.next(); 
     for (int i = reader.read(buffer, 0, buffer.length); i > 0;) {
         ...
     } 
     pool.recycle(buffer);

Note: Array allocation/recycling is effective only if the current thread executes within a PoolContext.

"Stack" allocated arrays are often used to implement dynamically sized Realtime objects. For example:

     public class FastString extends RealtimeObject implements CharSequence {
         private static final Factory FACTORY = new Factory() {
             public Object create() {
                 return new FastString();
             }
         };
         char[] _data; // Dynamic data buffer.
         int _first, _length;
         public static FastString newInstance(int capacity) {
             FastString str = (FastString) FACTORY.object();
             str._data = (char[]) ArrayPool.charArray(capacity).next();
             str._first = 0;
             str._length = 0;
             return str;
         }
    }

Version:

6.0, June 3, 2004

Author:

Jean-Marie Dautelle

Field Summary

static int

MIN_LENGTH Holds the minimum length array (16).

Method Summary

static ObjectPool	array(java.lang.Class componentType, int capacity) Returns the current pool for arrays of specified component type and minimum capacity.
static ObjectPool	byteArray(int capacity) Returns the current pool for byte[].
static ObjectPool	charArray(int capacity) Returns the current pool for char[].
static void	clear(java.lang.Object[] array, int start, int length) Clears an array beginning at the specified position.
static ObjectPool	doubleArray(int capacity) Returns the current pool for double[].
static ObjectPool	floatArray(int capacity) Returns the current pool for float[].
static java.lang.Object	heapCopy(java.lang.Object array, int first, int length) Copies the specified array to the heap.
static int	indexFor(int capacity) Returns a factory index (0-27) for the specified capacity.
static ObjectPool	intArray(int capacity) Returns the current pool for int[].
static ObjectPool	longArray(int capacity) Returns the current pool for long[].
static ObjectPool	objectArray(int capacity) Returns the current pool for Object[].
static java.lang.Object	outerCopy(java.lang.Object array, int first, int length) Copies the specified array into an array from the outer pool.

Methods inherited from class java.lang.Object

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

Field Detail

MIN_LENGTH

public static final int MIN_LENGTH

Holds the minimum length array (16).

See Also:

Constant Field Values

Method Detail

outerCopy

public static java.lang.Object outerCopy(java.lang.Object array,
                                         int first,
                                         int length)

Copies the specified array into an array from the outer pool. This method is typically used when exporting real-time objects referencing arrays allocated through ObjectFactory. For example:

 public class FastString extends RealtimeObject implements CharSequence {
     ...
     public Object export() {
         if (isLocalObject()) {
             super.export();
             _data = (char[]) ArrayPool.outerCopy(_data, _first, _length);
             _first = 0;
         }  // Else non-local object cannot refer to local object.
         return this;
     }
  }

Parameters:

array - the array to copy.

first - the index of the first component to copy (will be at position 0 in the copy).

length - the number of components to copy.

Returns:

a copy allocated in the outer context.

Throws:

java.lang.IllegalArgumentException - if array is not an array.

heapCopy

public static java.lang.Object heapCopy(java.lang.Object array,
                                        int first,
                                        int length)

Copies the specified array to the heap. This method is typically used when moving to the heap real-time objects referencing arrays allocated through an ObjectFactory. For example:

 public class FastString extends RealtimeObject implements CharSequence {
     ...
     public Object toHeap() {
         if (isPoolObject()) {
             super.toHeap();
             _data = (char[]) ArrayPool.heapCopy(_data, _first, _length);
             _first = 0;
         }  // Else heap objects can only refer to heap objects.
         return this;
     }
 }

Parameters:

array - the array to copy.

first - the index of the first component to copy (will be at position 0 in the copy).

length - the number of components to copy.

Returns:

a copy allocated in the heap context.

Throws:

java.lang.IllegalArgumentException - if array is not an array.

clear

public static void clear(java.lang.Object[] array,
                         int start,
                         int length)

Clears an array beginning at the specified position.

Parameters:

array - the array whose components are set to null.

start - the the starting position.

length - the number of components to clear.

Throws:

java.lang.IndexOutOfBoundsException - if clearing would cause access of data outside array bounds.

array

public static ObjectPool array(java.lang.Class componentType,
                               int capacity)

Returns the current pool for arrays of specified component type and minimum capacity.

Parameters:

componentType - the Class object representing the component type of the array.

capacity - the minimum length of the array.

Returns:

the current pool.

objectArray

public static ObjectPool objectArray(int capacity)

Returns the current pool for Object[].

Parameters:

capacity - the minimum length of the array.

Returns:

the current pool.

byteArray

public static ObjectPool byteArray(int capacity)

Returns the current pool for byte[].

Parameters:

capacity - the minimum length of the array.

Returns:

the current pool.

charArray

public static ObjectPool charArray(int capacity)

Returns the current pool for char[].

Parameters:

capacity - the minimum length of the array.

Returns:

the current pool.

intArray

public static ObjectPool intArray(int capacity)

Returns the current pool for int[].

Parameters:

capacity - the minimum length of the array.

Returns:

the current pool.

longArray

public static ObjectPool longArray(int capacity)

Returns the current pool for long[].

Parameters:

capacity - the minimum length of the array.

Returns:

the current pool.

floatArray

public static ObjectPool floatArray(int capacity)

Returns the current pool for float[].

Parameters:

capacity - the minimum length of the array.

Returns:

the current pool.

doubleArray

public static ObjectPool doubleArray(int capacity)

Returns the current pool for double[].

Parameters:

capacity - the minimum length of the array.

Returns:

the current pool.

indexFor

public static int indexFor(int capacity)

Returns a factory index (0-27) for the specified capacity.

Parameters:

capacity - the required capacity.

Returns:

j such as (MIN_LENGTH << j) >= capacity