Package org.apache.datasketches.memory

Interface WritableMemory

All Superinterfaces:
AutoCloseable, Memory, Resource
public interface WritableMemory extends Memory
Defines the writable API for offset access to a resource.
Author:
Lee Rhodes

  • Method Details

    • writableWrap

      static WritableMemory writableWrap(ByteBuffer byteBuffer)
      Provides a view of the given ByteBuffer for write operations. The view is of the entire ByteBuffer independent of position and limit. The returned WritableMemory will assume the ByteOrder of the given ByteBuffer.
      Parameters:
      byteBuffer - the given ByteBuffer. It must be non-null and writable.
      Returns:
      a new WritableMemory for write operations on the given ByteBuffer.

    • writableWrap

      static WritableMemory writableWrap(ByteBuffer byteBuffer, ByteOrder byteOrder, MemoryRequestServer memReqSvr)
      Provides a view of the given ByteBuffer for write operations. The view is of the entire ByteBuffer independent of position and limit. The returned WritableMemory will use the given ByteOrder, independent of the ByteOrder of the given ByteBuffer. This does not affect the ByteOrder of data already in the ByteBuffer.
      Parameters:
      byteBuffer - the given ByteBuffer. It must be non-null and writable.
      byteOrder - the byte order to be used. It must be non-null.
      memReqSvr - A user-specified MemoryRequestServer, which may be null. This is a callback mechanism for a user client to request a larger WritableMemory.
      Returns:
      a new WritableMemory for write operations on the given ByteBuffer.
      Throws:
      IllegalArgumentException - if ByteBuffer is not writable.

    • allocateDirect

      static WritableMemory allocateDirect(long capacityBytes)
      Allocates and provides access to capacityBytes directly in off-heap memory. Native byte order is assumed. The allocated memory will be 8-byte aligned.

      NOTE: Off-heap memory acquired may have garbage in it. It is the responsibility of the using application to clear this memory, if required, and to call close() when done.

      Parameters:
      capacityBytes - the size of the desired memory in bytes.
      Returns:
      WritableMemory for this off-heap resource.

    • allocateDirect

      static WritableMemory allocateDirect(long capacityBytes, ByteOrder byteOrder, MemoryRequestServer memReqSvr)
      Allocates and provides access to capacityBytes directly in off-heap memory. The allocated memory will be 8-byte aligned.

      NOTE: Off-heap memory acquired may have garbage in it. It is the responsibility of the using application to clear this memory, if required, and to call close() when done.

      Parameters:
      capacityBytes - the size of the desired memory in bytes.
      byteOrder - the given ByteOrder. It must be non-null.
      memReqSvr - A user-specified MemoryRequestServer, which may be null. This is a callback mechanism for a user client of off-heap memory to request more memory.
      Returns:
      a WritableMemory for this off-heap resource.

    • writableRegion

      default WritableMemory writableRegion(long offsetBytes, long capacityBytes)
      A writable region is a writable view of this object. This returns a new WritableMemory representing the defined writable region with the given offsetBytes and capacityBytes.
      • Returned object's origin = this objects' origin + offsetBytes
      • Returned object's capacity = capacityBytes
      Parameters:
      offsetBytes - the starting offset with respect to this object. It must be ≥ 0.
      capacityBytes - the capacity of the returned object in bytes. It must be ≥ 0.
      Returns:
      a new WritableMemory representing the defined writable region.

    • writableRegion

      WritableMemory writableRegion(long offsetBytes, long capacityBytes, ByteOrder byteOrder)
      A writable region is a writable view of this object. This returns a new WritableMemory representing the defined writable region with the given offsetBytes, capacityBytes and byte order.
      • Returned object's origin = this objects' origin + offsetBytes
      • Returned object's capacity = capacityBytes
      • Returned object's byte order = byteOrder
      Parameters:
      offsetBytes - the starting offset with respect to this object.
      capacityBytes - the capacity of the returned object in bytes.
      byteOrder - the given ByteOrder. It must be non-null.
      Returns:
      a new WritableMemory representing the defined writable region.

    • asWritableBuffer

      default WritableBuffer asWritableBuffer()
      Returns a new WritableBuffer with a writable view of this object.
      • Returned object's origin = this object's origin
      • Returned object's start = 0
      • Returned object's position = 0
      • Returned object's end = this object's capacity
      • Returned object's capacity = this object's capacity
      • Returned object's start, position and end are mutable
      Returns:
      a new WritableBuffer with a view of this WritableMemory

    • asWritableBuffer

      WritableBuffer asWritableBuffer(ByteOrder byteOrder)
      Returns a new WritableBuffer with a writable view of this object with the given byte order.
      • Returned object's origin = this object's origin
      • Returned object's start = 0
      • Returned object's position = 0
      • Returned object's end = this object's capacity
      • Returned object's capacity = this object's capacity
      • Returned object's start, position and end are mutable
      Parameters:
      byteOrder - the given ByteOrder. It must be non-null.
      Returns:
      a new WritableBuffer with a view of this WritableMemory

    • allocate

      static WritableMemory allocate(int capacityBytes)
      Creates on-heap WritableMemory with the given capacity and the native byte order.
      Parameters:
      capacityBytes - the given capacity in bytes.
      Returns:
      a new WritableMemory for write operations on a new byte array.

    • allocate

      static WritableMemory allocate(int capacityBytes, ByteOrder byteOrder)
      Creates on-heap WritableMemory with the given capacity and the given byte order.
      Parameters:
      capacityBytes - the given capacity in bytes.
      byteOrder - the given ByteOrder. It must be non-null.
      Returns:
      a new WritableMemory for write operations on a new byte array.

    • allocate

      static WritableMemory allocate(int capacityBytes, ByteOrder byteOrder, MemoryRequestServer memReqSvr)
      Creates on-heap WritableMemory with the given capacity and the given byte order.
      Parameters:
      capacityBytes - the given capacity in bytes.
      byteOrder - the given ByteOrder. It must be non-null.
      memReqSvr - A user-specified MemoryRequestServer, which may be null. This is a callback mechanism for a user client to request a larger WritableMemory.
      Returns:
      a new WritableMemory for write operations on a new byte array.

    • writableWrap

      static WritableMemory writableWrap(byte[] array)
      Wraps the given primitive array for write operations assuming native byte order.

      Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).

      Parameters:
      array - the given primitive array. It must be non-null.
      Returns:
      a new WritableMemory for write operations on the given primitive array.

    • writableWrap

      static WritableMemory writableWrap(byte[] array, ByteOrder byteOrder)
      Wraps the given primitive array for write operations with the given byte order.

      Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).

      Parameters:
      array - the given primitive array. It must be non-null.
      byteOrder - the byte order to be used. It must be non-null.
      Returns:
      a new WritableMemory for write operations on the given primitive array.

    • writableWrap

      static WritableMemory writableWrap(byte[] array, int offsetBytes, int lengthBytes, ByteOrder byteOrder)
      Wraps the given primitive array for write operations with the given byte order.

      Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).

      Parameters:
      array - the given primitive array. It must be non-null.
      offsetBytes - the byte offset into the given array.
      lengthBytes - the number of bytes to include from the given array.
      byteOrder - the byte order to be used. It must be non-null.
      Returns:
      a new WritableMemory for write operations on the given primitive array.

    • writableWrap

      static WritableMemory writableWrap(byte[] array, int offsetBytes, int lengthBytes, ByteOrder byteOrder, MemoryRequestServer memReqSvr)
      Wraps the given primitive array for write operations with the given byte order. If the given lengthBytes is zero, backing storage, byte order and read-only status of the returned WritableMemory object are unspecified.

      Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).

      Parameters:
      array - the given primitive array. It must be non-null.
      offsetBytes - the byte offset into the given array. It must be ≥ 0.
      lengthBytes - the number of bytes to include from the given array. It must be ≥ 0.
      byteOrder - the byte order to be used. It must be non-null.
      memReqSvr - A user-specified MemoryRequestServer, which may be null. This is a callback mechanism for a user client to request a larger WritableMemory.
      Returns:
      a new WritableMemory for write operations on the given primitive array.

    • writableWrap

      static WritableMemory writableWrap(char[] array)
      Wraps the given primitive array for write operations assuming native byte order.
      Parameters:
      array - the given primitive array. It must be non-null.
      Returns:
      a new WritableMemory for write operations on the given primitive array.

    • writableWrap

      static WritableMemory writableWrap(short[] array)
      Wraps the given primitive array for write operations assuming native byte order.
      Parameters:
      array - the given primitive array. It must be non-null.
      Returns:
      a new WritableMemory for write operations on the given primitive array.

    • writableWrap

      static WritableMemory writableWrap(int[] array)
      Wraps the given primitive array for write operations assuming native byte order.
      Parameters:
      array - the given primitive array. It must be non-null.
      Returns:
      a new WritableMemory for write operations on the given primitive array.

    • writableWrap

      static WritableMemory writableWrap(long[] array)
      Wraps the given primitive array for write operations assuming native byte order.
      Parameters:
      array - the given primitive array. It must be non-null.
      Returns:
      a new WritableMemory for write operations on the given primitive array.

    • writableWrap

      static WritableMemory writableWrap(float[] array)
      Wraps the given primitive array for write operations assuming native byte order.
      Parameters:
      array - the given primitive array. It must be non-null.
      Returns:
      a new WritableMemory for write operations on the given primitive array.

    • writableWrap

      static WritableMemory writableWrap(double[] array)
      Wraps the given primitive array for write operations assuming native byte order.
      Parameters:
      array - the given primitive array. It must be non-null.
      Returns:
      a new WritableMemory for write operations on the given primitive array.

    • putBoolean

      void putBoolean(long offsetBytes, boolean value)
      Puts the boolean value at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this WritableMemory start
      value - the value to put

    • putByte

      void putByte(long offsetBytes, byte value)
      Puts the byte value at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this WritableMemory start
      value - the value to put

    • putByteArray

      void putByteArray(long offsetBytes, byte[] srcArray, int srcOffsetBytes, int lengthBytes)
      Puts the byte array at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this WritableMemory start
      srcArray - The source array.
      srcOffsetBytes - offset in array units
      lengthBytes - number of array units to transfer

    • putChar

      void putChar(long offsetBytes, char value)
      Puts the char value at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this WritableMemory start
      value - the value to put

    • putCharArray

      void putCharArray(long offsetBytes, char[] srcArray, int srcOffsetChars, int lengthChars)
      Puts the char array at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this WritableMemory start
      srcArray - The source array.
      srcOffsetChars - offset in array units
      lengthChars - number of array units to transfer

    • putDouble

      void putDouble(long offsetBytes, double value)
      Puts the double value at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this WritableMemory start
      value - the value to put

    • putDoubleArray

      void putDoubleArray(long offsetBytes, double[] srcArray, int srcOffsetDoubles, int lengthDoubles)
      Puts the double array at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this WritableMemory start
      srcArray - The source array.
      srcOffsetDoubles - offset in array units
      lengthDoubles - number of array units to transfer

    • putFloat

      void putFloat(long offsetBytes, float value)
      Puts the float value at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this WritableMemory start
      value - the value to put

    • putFloatArray

      void putFloatArray(long offsetBytes, float[] srcArray, int srcOffsetFloats, int lengthFloats)
      Puts the float array at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this WritableMemory start
      srcArray - The source array.
      srcOffsetFloats - offset in array units
      lengthFloats - number of array units to transfer

    • putInt

      void putInt(long offsetBytes, int value)
      Puts the int value at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this WritableMemory start
      value - the value to put

    • putIntArray

      void putIntArray(long offsetBytes, int[] srcArray, int srcOffsetInts, int lengthInts)
      Puts the int array at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this WritableMemory start
      srcArray - The source array.
      srcOffsetInts - offset in array units
      lengthInts - number of array units to transfer

    • putLong

      void putLong(long offsetBytes, long value)
      Puts the long value at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this WritableMemory start
      value - the value to put

    • putLongArray

      void putLongArray(long offsetBytes, long[] srcArray, int srcOffsetLongs, int lengthLongs)
      Puts the long array at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this WritableMemory start
      srcArray - The source array.
      srcOffsetLongs - offset in array units
      lengthLongs - number of array units to transfer

    • putShort

      void putShort(long offsetBytes, short value)
      Puts the short value at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this WritableMemory start
      value - the value to put

    • putShortArray

      void putShortArray(long offsetBytes, short[] srcArray, int srcOffsetShorts, int lengthShorts)
      Puts the short array at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this WritableMemory start
      srcArray - The source array.
      srcOffsetShorts - offset in array units
      lengthShorts - number of array units to transfer

    • getArray

      Object getArray()
      Returns the primitive backing array, otherwise null.
      Returns:
      the primitive backing array, otherwise null.

    • clear

      void clear()
      Clears all bytes of this Memory to zero

    • clear

      void clear(long offsetBytes, long lengthBytes)
      Clears a portion of this Memory to zero.
      Parameters:
      offsetBytes - offset bytes relative to this Memory start
      lengthBytes - the length in bytes

    • clearBits

      void clearBits(long offsetBytes, byte bitMask)
      Clears the bits defined by the bitMask
      Parameters:
      offsetBytes - offset bytes relative to this Memory start.
      bitMask - the bits set to one will be cleared

    • fill

      void fill(byte value)
      Fills all bytes of this Memory region to the given byte value.
      Parameters:
      value - the given byte value

    • fill

      void fill(long offsetBytes, long lengthBytes, byte value)
      Fills a portion of this Memory region to the given byte value.
      Parameters:
      offsetBytes - offset bytes relative to this Memory start
      lengthBytes - the length in bytes
      value - the given byte value

    • setBits

      void setBits(long offsetBytes, byte bitMask)
      Sets the bits defined by the bitMask
      Parameters:
      offsetBytes - offset bytes relative to this Memory start
      bitMask - the bits set to one will be set