Package net.algart.arrays

Class BufferMemoryModel

java.lang.Object
net.algart.arrays.AbstractMemoryModel
net.algart.arrays.BufferMemoryModel
All Implemented Interfaces:
MemoryModel
public class BufferMemoryModel extends AbstractMemoryModel

The memory model, based on ByteBuffer and other buffers from java.nio package. It means that AlgART array of elements of some type (byte, char, etc.) contains an underlying NIO buffer TypeBuffer (correspondingly ByteBuffer, CharBuffer, etc.), and any access to AlgART array elements is translated to corresponding access to the underlying NIO buffer. The only exception is bit arrays, where the bits are packed into elements of LongBuffer, as specified in PackedBitBuffers class.

Unlike the simple memory model, this model supports primitive element types only: BitArray, CharArray, ByteArray, ShortArray, IntArray, LongArray, FloatArray, DoubleArray. If you need to store objects in NIO buffers, you may use the AlgART arrays, created by this memory model, as a storage for combined arrays, created by CombinedMemoryModel.

The maximal theoretical limit for length and capacity of AlgART arrays, supported by this memory model, is 234-64 for bit arrays and 231/size-1 for all other element types, where size is 1,2,2,4,8,4,8 for element types byte, char, short, int, long, float, double correspondingly. In other words, the capacity of AlgART array cannot exceed 2 GB. The real limit is little less in 32-bit JVM, usually ~1.0-1.5 GB.

The NIO buffers, used by this memory model, are always direct: they are created by ByteBuffer.allocateDirect method with, for non-byte arrays, the following byteBuffer.asTypeBuffer() call. The byte order in the buffers is always native, excepting the case when AlgART arrays are created via asUpdatableArray(ByteBuffer, Class) method, when the byte order of the passed buffer is preserver.

Arrays, created by this memory model, never implement DirectAccessible interface. However, if is absolutely necessary to provide maximal performance for this memory model, you may use getByteBuffer(Array) method to get a reference to the internal underlying ByteBuffer.

All arrays, created by this memory model, have empty implementation of Array.loadResources(ArrayContext), Array.flushResources(ArrayContext), Array.flushResources(ArrayContext, boolean) and Array.freeResources(ArrayContext, boolean) methods: these methods do nothing.

This class is immutable and thread-safe: there are no ways to modify settings of its instance returned by getInstance() method. Moreover, it is a singleton: getInstance() always returns the same object.

Author:
Daniel Alievsky

  • Method Details

    • getInstance

      public static BufferMemoryModel getInstance()
      Returns an instance of this memory model. This method always returns the same object.
      Returns:
      an instance of this memory model.

    • newEmptyArray

      public MutableArray newEmptyArray(Class<?> elementType)
      Description copied from interface: MemoryModel
      Allocates an empty resizable array with the specified element type and a little initial capacity. It is equivalent to newEmptyArray(elementType, n), where n is some little value.

      Example of usage:

           MutableFloatArray a = (MutableFloatArray)memoryModel.newEmptyArray(float.class);
      Specified by:
      newEmptyArray in interface MemoryModel
      Specified by:
      newEmptyArray in class AbstractMemoryModel
      Parameters:
      elementType - the type of array elements.
      Returns:
      created AlgART array.
      See Also:

    • newEmptyArray

      public MutableArray newEmptyArray(Class<?> elementType, long initialCapacity)
      Description copied from interface: MemoryModel
      Allocates an empty resizable array with the specified element type and initial capacity.

      The element type can be either usual object class (as String.class), or one of the primitive types: boolean.class, byte.class, short.class, int.class, long.class, float.class, double.class, char.class. The element type cannot be void.class.

      In a case of primitive types, the created array will implement the corresponding interface BitArray, ByteArray, ShortArray, IntArray, LongArray, FloatArray, DoubleArray or CharArray. In this case, the created array (unlike standard ArrayList) will occupy the same amount of memory as the Java array boolean[initialCapacity], byte[initialCapacity], etc.

      In a case of non-primitive types (Object inheritors), the created array will implement the MutableObjectArray interface.

      Some element type may be not supported by this memory model. For example, some memory models may support only primitive types, or only one concrete type. In such a case, UnsupportedElementTypeException will be thrown.

      Some too large array capacities may be not supported by this memory model. For example, SimpleMemoryModel does not support arrays larger than 0x7FFFFFFF (Integer.MAX_VALUE) elements.

      Example of usage:

           MutableFloatArray a = (MutableFloatArray)memoryModel.newEmptyArray(float.class, 10000);
      Specified by:
      newEmptyArray in interface MemoryModel
      Specified by:
      newEmptyArray in class AbstractMemoryModel
      Parameters:
      elementType - the type of array elements.
      initialCapacity - the initial capacity of the array.
      Returns:
      created AlgART array.
      See Also:

    • newArray

      public MutableArray newArray(Class<?> elementType, long initialLength)
      Description copied from interface: MemoryModel
      Allocates a zero-filled resizable array with the specified element type and initial length. The capacity of new array will be equal to its length.

      This method is equivalent to the following call: newEmptyArray(elementType, initialLength).length(initialLength).trim().

      Specified by:
      newArray in interface MemoryModel
      Specified by:
      newArray in class AbstractMemoryModel
      Parameters:
      elementType - the type of array elements.
      initialLength - the initial length and capacity of the array.
      Returns:
      created AlgART array.
      See Also:

    • newUnresizableArray

      public UpdatableArray newUnresizableArray(Class<?> elementType, long length)
      Description copied from interface: MemoryModel
      Allocates a zero-filled unresizable array with the specified element type and length. The capacity of new array will be equal to its length.

      The analogous result may be obtained the following call: newArray(elementType, length).asUnresizable(). However, we don't recommend to use such code. If you are sure that you will not need to change the array length, please always use this method (or newUnresizableBitArray, newUnresizableBteArray, etc.). In some memory models, creating resizable array with the given length may require much more resources that creating unresizable one. For example, in the large memory model every resizable array is stored in the file consisting of integer number of blocks per DataFileModel.recommendedBankSize(true) bytes.

      Specified by:
      newUnresizableArray in interface MemoryModel
      Specified by:
      newUnresizableArray in class AbstractMemoryModel
      Parameters:
      elementType - the type of array elements.
      length - the length and capacity of the array.
      Returns:
      created unresizable AlgART array.
      See Also:

    • isElementTypeSupported

      public boolean isElementTypeSupported(Class<?> elementType)
      Description copied from interface: MemoryModel
      Returns true if this memory model can create arrays with this element type. If it does not support it, creation methods of this memory model will throw UnsupportedElementTypeException. The result is not defined for void.class.
      Specified by:
      isElementTypeSupported in interface MemoryModel
      Specified by:
      isElementTypeSupported in class AbstractMemoryModel
      Parameters:
      elementType - the type of array elements.
      Returns:
      true if this memory model supports this element type.

    • areAllPrimitiveElementTypesSupported

      public boolean areAllPrimitiveElementTypesSupported()
      Description copied from interface: MemoryModel
      Returns true if this memory model can create arrays with all primitive element types: boolean, char, byte, short, int, long, float, double.
      Specified by:
      areAllPrimitiveElementTypesSupported in interface MemoryModel
      Specified by:
      areAllPrimitiveElementTypesSupported in class AbstractMemoryModel
      Returns:
      true if this memory model supports all primitive element types.
      See Also:

    • areAllElementTypesSupported

      public boolean areAllElementTypesSupported()
      Description copied from interface: MemoryModel
      Returns true if this memory model can create arrays with all element types. This package offers only one such memory model: SimpleMemoryModel.
      Specified by:
      areAllElementTypesSupported in interface MemoryModel
      Specified by:
      areAllElementTypesSupported in class AbstractMemoryModel
      Returns:
      true if this memory model supports element types.
      See Also:

    • maxSupportedLength

      public long maxSupportedLength(Class<?> elementType)
      This implementation returns 234-64 for boolean.class or 231/size-1 for all other element types, where size is 1,2,2,4,8,4,8 for element types byte, char, short, int, long, float, double correspondingly.
      Specified by:
      maxSupportedLength in interface MemoryModel
      Specified by:
      maxSupportedLength in class AbstractMemoryModel
      Parameters:
      elementType - the type of array elements.
      Returns:
      maximal possible length of arrays supported by this memory model.
      Throws:
      NullPointerException - if elementType is null.

    • isCreatedBy

      public boolean isCreatedBy(Array array)
      Description copied from interface: MemoryModel
      Returns true if the passed array was created by this (or identical) memory model.

      For SimpleMemoryModel and BufferMemoryModel, "identical" means the same memory model.

      For LargeMemoryModel, "identical" means that the memory model is also large and was created with the same instance of the data file factory.

      For CombinedMemoryModel, "identical" means that the memory model is also combined and was created with the same instance of the combiner.

      Returns false if the passed argument is null.

      Specified by:
      isCreatedBy in interface MemoryModel
      Specified by:
      isCreatedBy in class AbstractMemoryModel
      Parameters:
      array - the AlgART array (may be null, than the method returns false).
      Returns:
      true if the passed array was created by this memory model.

    • isBufferArray

      public static boolean isBufferArray(Array array)
      Returns true if the passed array was created by some instance of this memory model. Returns false if the passed array is null or an AlgART array created by another memory model.

      As this memory model is a singleton, this method is equivalent to isCreatedBy(Array).

      Parameters:
      array - the checked array.
      Returns:
      true if this array is an array created by the buffer memory model.

    • getByteBuffer

      public static ByteBuffer getByteBuffer(Array bufferArray)
      Returns the underlying ByteBuffer instance where all elements of the passed array are stored. More precisely, if the backed ByteBuffer is bb, this method returns 
       bufferArray.isImmutable() ? bb.asReadOnlyBuffer().order(o) : bb.duplicate().order(o);
      where o is the byte order of the original bb, which is usually the native order. So, the returned buffer does not allow to violate immutability of the passed array, and in any case you may freely change the position and limit in the returned buffer.

      The returned object is ByteBuffer, even if the AlgART array consists of elements of another primitive type: for example, int or float. The buffer, which elements really correspond to the elements of the passed array, may be got by the following operators (where byteBuffer is a result of this method):

      • just this byteBuffer if the passed array is a ByteArray;
      • byteBuffer.asCharBuffer() if the passed array is a CharArray;
      • byteBuffer.asShortBuffer() if the passed array is a ShortArray;
      • byteBuffer.asIntBuffer() if the passed array is a IntArray;
      • byteBuffer.asLongBuffer() if the passed array is a LongArray;
      • byteBuffer.asFloatBuffer() if the passed array is a FloatArray;
      • byteBuffer.asDoubleBuffer() if the passed array is a DoubleArray;
      • byteBuffer.asLongBuffer() if the passed array is a BitArray; in this case, the bits are packed into long values as specified in PackedBitBuffers class.

      The ByteBuffer and the specific buffer, returned by the conversion operators, listed above, may contain extra elements besides the content of the passed AlgART array. Really, the elements of the AlgART array correspond to elements #offset..#offset+bufferArray.Array.length()-1 of the buffer returned by the conversion operator (or the ByteBuffer in a case of a byte array), where offset is getBufferOffset(bufferArray). Changes to this range of the returned buffer "write through" to the AlgART array. For bit arrays, this range is specified in terms of PackedBitBuffers class; so, all elements of the AlgART array may be get and set via getBit(src,offset+k) and setBit(dest,offset+k,value) methods of that class, where k=0,1,...,bufferArray.length()-1.

      If modifications of this AlgART array characteristics lead to reallocation of the internal storage, then the returned ByteBuffer ceases to be a view of this array. The only possible reasons for reallocation are the following: calling MutableArray.length(long), MutableArray.ensureCapacity(long) or MutableArray.trim() methods for this array, or any modification of this array in a case when this array is copy-on-next-write.

      The passed argument must be created by the buffer memory model: isBufferArray(Array) must return true. In other case, IllegalArgumentException will be thrown.

      Parameters:
      bufferArray - the AlgART array created by this memory model.
      Returns:
      the underlying ByteBuffer.
      Throws:
      NullPointerException - if bufferArray is null.
      IllegalArgumentException - if bufferArray is not created by the buffer memory model.

    • getBufferOffset

      public static long getBufferOffset(Array bufferArray)
      Returns the start offset in the buffer returned by getByteBuffer(Array) call, corresponding to the first element of the passed AlgART array. The returned offset is specified in terms of array elements (bits, bytes, shorts, etc.)
      Parameters:
      bufferArray - the AlgART array created by this memory model.
      Returns:
      the start offset in the buffer returned returned by getByteBuffer(Array) call.
      Throws:
      NullPointerException - if bufferArray is null.
      IllegalArgumentException - if bufferArray is not created by the buffer memory model.

    • asUpdatableArray

      public static UpdatableArray asUpdatableArray(ByteBuffer byteBuffer, Class<?> elementType)
      Returns an unresizable AlgART array backed by a duplicate of the specified ByteBuffer (more precisely, byteBuffer.duplicate().order(byteBuffer.order())), excluding a case of boolean element type. For boolean elements (BitArray) please use the method asUpdatableBitArray(ByteBuffer, long).

      If elementType is not byte.class, the passed byte buffer is automatically converted to a buffer of corresponding type (CharBuffer, ShortBuffer, etc.) via ((ByteBuffer)byteBuffer.duplicate().order(byteBuffer.order()).rewind()).asTypeBuffer() call, where Type is the passed element type. The result AlgART array contains all elements of the converted NIO buffer, and changes in the returned array "write through" to byteBuffer argument. The length and capacity of the returned array are equal to byteBuffer.limit()/size, where size is 1,2,2,4,8,4,8 for element types byte, char, short, int, long, float, double correspondingly.

      Parameters:
      byteBuffer - the source NIO ByteBuffer.
      elementType - the required primitive element type.
      Returns:
      an unresizable AlgART array backed by the specified byte buffer.
      Throws:
      NullPointerException - if byteBuffer or elementType argument is null.
      IllegalArgumentException - if elementType is boolean.class or non-primitive type.

    • asUpdatableBitArray

      public static UpdatableBitArray asUpdatableBitArray(ByteBuffer byteBuffer, long length)
      Returns an unresizable AlgART bit array backed by a duplicate of the specified ByteBuffer (more precisely, byteBuffer.duplicate().order(byteBuffer.order())), according the packing rules, describing in PackedBitBuffers class, applied to asLongBuffer() representation of the duplicate. Changes in the returned buffer "write through" to byteBuffer argument. The length and capacity of the returned array are equal to the specified length argument.
      Parameters:
      byteBuffer - the source NIO ByteBuffer.
      length - the length of the returned bit array.
      Returns:
      an unresizable AlgART array backed by the specified byte buffer.
      Throws:
      NullPointerException - if byteBuffer or elementType argument is null.
      IllegalArgumentException - if length<0 or if the passed byteBuffer is too short to store (length+63)/64 full 64-bit long values.

    • asUpdatableCharArray

      public static UpdatableCharArray asUpdatableCharArray(ByteBuffer byteBuffer)
      Equivalent to (UpdatableCharArray)asUpdatableArray(byteBuffer, char.class).
      Parameters:
      byteBuffer - the source NIO ByteBuffer.
      Returns:
      an unresizable AlgART array backed by the specified byte buffer.
      Throws:
      NullPointerException - if byteBuffer argument is null.

    • asUpdatableByteArray

      public static UpdatableByteArray asUpdatableByteArray(ByteBuffer byteBuffer)
      Equivalent to (UpdatableByteArray)asUpdatableArray(byteBuffer, byte.class).
      Parameters:
      byteBuffer - the source NIO ByteBuffer.
      Returns:
      an unresizable AlgART array backed by the specified byte buffer.
      Throws:
      NullPointerException - if byteBuffer argument is null.

    • asUpdatableShortArray

      public static UpdatableShortArray asUpdatableShortArray(ByteBuffer byteBuffer)
      Equivalent to (UpdatableShortArray)asUpdatableArray(byteBuffer, short.class).
      Parameters:
      byteBuffer - the source NIO ByteBuffer.
      Returns:
      an unresizable AlgART array backed by the specified byte buffer.
      Throws:
      NullPointerException - if byteBuffer argument is null.

    • asUpdatableIntArray

      public static UpdatableIntArray asUpdatableIntArray(ByteBuffer byteBuffer)
      Equivalent to (UpdatableIntArray)asUpdatableArray(byteBuffer, int.class).
      Parameters:
      byteBuffer - the source NIO ByteBuffer.
      Returns:
      an unresizable AlgART array backed by the specified byte buffer.
      Throws:
      NullPointerException - if byteBuffer argument is null.

    • asUpdatableLongArray

      public static UpdatableLongArray asUpdatableLongArray(ByteBuffer byteBuffer)
      Equivalent to (UpdatableLongArray)asUpdatableArray(byteBuffer, long.class).
      Parameters:
      byteBuffer - the source NIO ByteBuffer.
      Returns:
      an unresizable AlgART array backed by the specified byte buffer.
      Throws:
      NullPointerException - if byteBuffer argument is null.

    • asUpdatableFloatArray

      public static UpdatableFloatArray asUpdatableFloatArray(ByteBuffer byteBuffer)
      Equivalent to (UpdatableFloatArray)asUpdatableArray(byteBuffer, float.class).
      Parameters:
      byteBuffer - the source NIO ByteBuffer.
      Returns:
      an unresizable AlgART array backed by the specified byte buffer.
      Throws:
      NullPointerException - if byteBuffer argument is null.

    • asUpdatableDoubleArray

      public static UpdatableDoubleArray asUpdatableDoubleArray(ByteBuffer byteBuffer)
      Equivalent to (UpdatableDoubleArray)asUpdatableArray(byteBuffer, double.class).
      Parameters:
      byteBuffer - the source NIO ByteBuffer.
      Returns:
      an unresizable AlgART array backed by the specified byte buffer.
      Throws:
      NullPointerException - if byteBuffer argument is null.

    • toString

      public String toString()
      Returns a brief string description of this memory model.

      The result of this method may depend on implementation.

      Overrides:
      toString in class Object
      Returns:
      a brief string description of this object.