Package org.apache.datasketches.memory

Interface Memory

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

  • Field Summary

    Fields inherited from interface org.apache.datasketches.memory.Resource

    defaultMemReqSvr

  • Method Summary

    Modifier and Type
    Method
    Description
    default Buffer
    asBuffer()
    Returns a new Buffer view of this object.
    Buffer
    asBuffer(ByteOrder byteOrder)
    Returns a new Buffer view of this object, with the given byte order.
    int
    compareTo(long thisOffsetBytes, long thisLengthBytes, Memory that, long thatOffsetBytes, long thatLengthBytes)
    Compares the bytes of this Memory to that Memory.
    void
    copyTo(long srcOffsetBytes, WritableMemory destination, long dstOffsetBytes, long lengthBytes)
    Copies bytes from a source range of this Memory to a destination range of the given Memory with the same semantics when copying between overlapping ranges of bytes as method System.arraycopy(Object, int, Object, int, int) has.
    boolean
    getBoolean(long offsetBytes)
    Gets the boolean value at the given offset
    byte
    getByte(long offsetBytes)
    Gets the byte value at the given offset
    void
    getByteArray(long offsetBytes, byte[] dstArray, int dstOffsetBytes, int lengthBytes)
    Gets the byte array at the given offset
    char
    getChar(long offsetBytes)
    Gets the char value at the given offset
    void
    getCharArray(long offsetBytes, char[] dstArray, int dstOffsetChars, int lengthChars)
    Gets the char array at the given offset
    double
    getDouble(long offsetBytes)
    Gets the double value at the given offset
    void
    getDoubleArray(long offsetBytes, double[] dstArray, int dstOffsetDoubles, int lengthDoubles)
    Gets the double array at the given offset
    float
    getFloat(long offsetBytes)
    Gets the float value at the given offset
    void
    getFloatArray(long offsetBytes, float[] dstArray, int dstOffsetFloats, int lengthFloats)
    Gets the float array at the given offset
    int
    getInt(long offsetBytes)
    Gets the int value at the given offset
    void
    getIntArray(long offsetBytes, int[] dstArray, int dstOffsetInts, int lengthInts)
    Gets the int array at the given offset
    long
    getLong(long offsetBytes)
    Gets the long value at the given offset
    void
    getLongArray(long offsetBytes, long[] dstArray, int dstOffsetLongs, int lengthLongs)
    Gets the long array at the given offset
    short
    getShort(long offsetBytes)
    Gets the short value at the given offset
    void
    getShortArray(long offsetBytes, short[] dstArray, int dstOffsetShorts, int lengthShorts)
    Gets the short array at the given offset
    static Memory
    map(File file)
    Maps the given file into Memory for read operations Calling this method is equivalent to calling map(file, 0, file.length(), scope, ByteOrder.nativeOrder()).
    static Memory
    map(File file, long fileOffsetBytes, long capacityBytes, ByteOrder byteOrder)
    Maps the specified portion of the given file into Memory for read operations.
    static Memory
    map(File file, long fileOffsetBytes, long capacityBytes, ResourceScope scope, ByteOrder byteOrder)
    Maps the specified portion of the given file into Memory for read operations with a ResourceScope.
    default Memory
    region(long offsetBytes, long capacityBytes)
    A region is a read-only view of this object.
    Memory
    region(long offsetBytes, long capacityBytes, ByteOrder byteOrder)
    A region is a read-only view of this object.
    static Memory
    wrap(byte[] array)
    Wraps the given primitive array for read operations assuming native byte order.
    static Memory
    wrap(byte[] array, int offsetBytes, int lengthBytes, ByteOrder byteOrder)
    Wraps the given primitive array for read operations with the given byte order.
    static Memory
    wrap(byte[] array, ByteOrder byteOrder)
    Wraps the given primitive array for read operations with the given byte order.
    static Memory
    wrap(char[] array)
    Wraps the given primitive array for read operations assuming native byte order.
    static Memory
    wrap(double[] array)
    Wraps the given primitive array for read operations assuming native byte order.
    static Memory
    wrap(float[] array)
    Wraps the given primitive array for read operations assuming native byte order.
    static Memory
    wrap(int[] array)
    Wraps the given primitive array for read operations assuming native byte order.
    static Memory
    wrap(long[] array)
    Wraps the given primitive array for read operations assuming native byte order.
    static Memory
    wrap(short[] array)
    Wraps the given primitive array for read operations assuming native byte order.
    static Memory
    wrap(ByteBuffer byteBuffer)
    Provides a view of the given ByteBuffer for read-only operations.
    static Memory
    wrap(ByteBuffer byteBuffer, ByteOrder byteOrder)
    Provides a view of the given ByteBuffer for read-only operations.
    void
    writeToByteStream(long offsetBytes, int lengthBytes, ByteArrayOutputStream out)
    Writes bytes from a source range of this Memory to the given WritableByteChannel.

    Methods inherited from interface org.apache.datasketches.memory.Resource

    asByteBufferView, close, equalTo, equalTo, force, getCapacity, getMemoryRequestServer, getOwnerThread, getRelativeOffset, getTypeByteOrder, hasByteBuffer, hasMemoryRequestServer, isAlive, isBuffer, isByteOrderCompatible, isCloseable, isDirect, isDuplicate, isHeap, isLoaded, isMapped, isMemory, isReadOnly, isRegion, isSameResource, load, mismatch, nativeOverlap, scope, setMemoryRequestServer, toByteBuffer, toMemorySegment, toString, toString, unload, xxHash64, xxHash64

  • Method Details

    • wrap

      static Memory wrap(ByteBuffer byteBuffer)
      Provides a view of the given ByteBuffer for read-only operations. The view is of the entire ByteBuffer independent of position and limit. The returned WritableMemory will use the native 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.
      Returns:
      a new Memory for read-only operations on the given ByteBuffer.

    • wrap

      static Memory wrap(ByteBuffer byteBuffer, ByteOrder byteOrder)
      Provides a view of the given ByteBuffer for read-only operations. The view is of the entire ByteBuffer independent of position and limit. The returned WritableMemory will use the native 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.
      byteOrder - the byte order to be used. It must be non-null.
      Returns:
      a new Memory for read-only operations on the given ByteBuffer.

    • map

      static Memory map(File file) throws IOException
      Maps the given file into Memory for read operations Calling this method is equivalent to calling map(file, 0, file.length(), scope, ByteOrder.nativeOrder()).
      Parameters:
      file - the given file to map. It must be non-null with a non-negative length and readable.
      Returns:
      Memory for managing the mapped memory.
      Throws:
      IllegalArgumentException - if path is not associated with the default file system.
      IllegalStateException - if scope has been already closed, or if access occurs from a thread other than the thread owning scope.
      IOException - if the specified path does not point to an existing file, or if some other I/O error occurs.
      SecurityException - If a security manager is installed and it denies an unspecified permission required by the implementation.

    • map

      static Memory map(File file, long fileOffsetBytes, long capacityBytes, ByteOrder byteOrder) throws IOException
      Maps the specified portion of the given file into Memory for read operations.
      Parameters:
      file - the given file to map. It must be non-null,readable and length ≥ 0.
      fileOffsetBytes - the position in the given file in bytes. It must not be negative.
      capacityBytes - the size of the mapped memory. It must not be negative..
      byteOrder - the byte order to be used. It must be non-null.
      Returns:
      Memory for managing the mapped memory.
      Throws:
      IllegalArgumentException - if path is not associated with the default file system.
      IllegalStateException - if scope has been already closed, or if access occurs from a thread other than the thread owning scope.
      IOException - if the specified path does not point to an existing file, or if some other I/O error occurs.
      SecurityException - If a security manager is installed and it denies an unspecified permission required by the implementation.

    • map

      static Memory map(File file, long fileOffsetBytes, long capacityBytes, ResourceScope scope, ByteOrder byteOrder) throws IOException
      Maps the specified portion of the given file into Memory for read operations with a ResourceScope.
      Parameters:
      file - the given file to map. It must be non-null, readable and length ≥ 0.
      fileOffsetBytes - the position in the given file in bytes. It must not be negative.
      capacityBytes - the size of the mapped memory. It must not be negative.
      scope - the given ResourceScope. It must be non-null. Typically use ResourceScope.newConfinedScope(). Warning: specifying a newSharedScope() is not supported.
      byteOrder - the byte order to be used. It must be non-null.
      Returns:
      Memory for managing the mapped memory.
      Throws:
      IllegalArgumentException - if path is not associated with the default file system.
      IllegalStateException - - if scope has been already closed, or if access occurs from a thread other than the thread owning scope.
      IOException - - if the specified path does not point to an existing file, or if some other I/O error occurs.
      SecurityException - - If a security manager is installed and it denies an unspecified permission required by the implementation.

    • region

      default Memory region(long offsetBytes, long capacityBytes)
      A region is a read-only view of this object.
      • Returned object's origin = this object's origin + offsetBytes
      • Returned object's capacity = capacityBytes
      Parameters:
      offsetBytes - the starting offset with respect to the origin of this Memory. It must be ≥ 0.
      capacityBytes - the capacity of the region in bytes. It must be ≥ 0.
      Returns:
      a new Memory representing the defined region based on the given offsetBytes and capacityBytes.

    • region

      Memory region(long offsetBytes, long capacityBytes, ByteOrder byteOrder)
      A region is a read-only view of this object.
      • Returned object's origin = this object's origin + offsetBytes
      • Returned object's capacity = capacityBytes
      • Returned object's byte order = byteOrder
      Parameters:
      offsetBytes - the starting offset with respect to the origin of this Memory. It must be ≥ 0.
      capacityBytes - the capacity of the region in bytes. It must be ≥ 0.
      byteOrder - the given byte order. It must be non-null.
      Returns:
      a new Memory representing the defined region based on the given offsetBytes, capacityBytes and byteOrder.

    • asBuffer

      default Buffer asBuffer()
      Returns a new Buffer 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 Buffer

    • asBuffer

      Buffer asBuffer(ByteOrder byteOrder)
      Returns a new Buffer 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 byte order. It must be non-null.
      Returns:
      a new Buffer with the given byteOrder.

    • wrap

      static Memory wrap(byte[] array)
      Wraps the given primitive array for read operations assuming native byte order.
      Parameters:
      array - the given primitive array. It must be non-null.
      Returns:
      a new Memory for read operations

    • wrap

      static Memory wrap(byte[] array, ByteOrder byteOrder)
      Wraps the given primitive array for read operations with the given byte order.
      Parameters:
      array - the given primitive array.
      byteOrder - the byte order to be used
      Returns:
      a new Memory for read operations

    • wrap

      static Memory wrap(byte[] array, int offsetBytes, int lengthBytes, ByteOrder byteOrder)
      Wraps the given primitive array for read operations with the given byte order.
      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 Memory for read operations

    • wrap

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

    • wrap

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

    • wrap

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

    • wrap

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

    • wrap

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

    • wrap

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

    • getBoolean

      boolean getBoolean(long offsetBytes)
      Gets the boolean value at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this Memory start
      Returns:
      the boolean at the given offset

    • getByte

      byte getByte(long offsetBytes)
      Gets the byte value at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this Memory start
      Returns:
      the byte at the given offset

    • getByteArray

      void getByteArray(long offsetBytes, byte[] dstArray, int dstOffsetBytes, int lengthBytes)
      Gets the byte array at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this Memory start
      dstArray - The preallocated destination array.
      dstOffsetBytes - offset in array units
      lengthBytes - number of array units to transfer

    • getChar

      char getChar(long offsetBytes)
      Gets the char value at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this Memory start
      Returns:
      the char at the given offset

    • getCharArray

      void getCharArray(long offsetBytes, char[] dstArray, int dstOffsetChars, int lengthChars)
      Gets the char array at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this Memory start
      dstArray - The preallocated destination array.
      dstOffsetChars - offset in array units
      lengthChars - number of array units to transfer

    • getDouble

      double getDouble(long offsetBytes)
      Gets the double value at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this Memory start
      Returns:
      the double at the given offset

    • getDoubleArray

      void getDoubleArray(long offsetBytes, double[] dstArray, int dstOffsetDoubles, int lengthDoubles)
      Gets the double array at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this Memory start
      dstArray - The preallocated destination array.
      dstOffsetDoubles - offset in array units
      lengthDoubles - number of array units to transfer

    • getFloat

      float getFloat(long offsetBytes)
      Gets the float value at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this Memory start
      Returns:
      the float at the given offset

    • getFloatArray

      void getFloatArray(long offsetBytes, float[] dstArray, int dstOffsetFloats, int lengthFloats)
      Gets the float array at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this Memory start
      dstArray - The preallocated destination array.
      dstOffsetFloats - offset in array units
      lengthFloats - number of array units to transfer

    • getInt

      int getInt(long offsetBytes)
      Gets the int value at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this Memory start
      Returns:
      the int at the given offset

    • getIntArray

      void getIntArray(long offsetBytes, int[] dstArray, int dstOffsetInts, int lengthInts)
      Gets the int array at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this Memory start
      dstArray - The preallocated destination array.
      dstOffsetInts - offset in array units
      lengthInts - number of array units to transfer

    • getLong

      long getLong(long offsetBytes)
      Gets the long value at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this Memory start
      Returns:
      the long at the given offset

    • getLongArray

      void getLongArray(long offsetBytes, long[] dstArray, int dstOffsetLongs, int lengthLongs)
      Gets the long array at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this Memory start
      dstArray - The preallocated destination array.
      dstOffsetLongs - offset in array units
      lengthLongs - number of array units to transfer

    • getShort

      short getShort(long offsetBytes)
      Gets the short value at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this Memory start
      Returns:
      the short at the given offset

    • getShortArray

      void getShortArray(long offsetBytes, short[] dstArray, int dstOffsetShorts, int lengthShorts)
      Gets the short array at the given offset
      Parameters:
      offsetBytes - offset bytes relative to this Memory start
      dstArray - The preallocated destination array.
      dstOffsetShorts - offset in array units
      lengthShorts - number of array units to transfer

    • compareTo

      int compareTo(long thisOffsetBytes, long thisLengthBytes, Memory that, long thatOffsetBytes, long thatLengthBytes)
      Compares the bytes of this Memory to that Memory. Returns (this < that) ? (some negative value) : (this > that) ? (some positive value) : 0;. If all bytes are equal up to the shorter of the two lengths, the shorter length is considered to be less than the other.
      Parameters:
      thisOffsetBytes - the starting offset for this Memory
      thisLengthBytes - the length of the region to compare from this Memory
      that - the other Memory to compare with
      thatOffsetBytes - the starting offset for that Memory
      thatLengthBytes - the length of the region to compare from that Memory
      Returns:
      (this < that) ? (some negative value) : (this > that) ? (some positive value) : 0;

    • copyTo

      void copyTo(long srcOffsetBytes, WritableMemory destination, long dstOffsetBytes, long lengthBytes)
      Copies bytes from a source range of this Memory to a destination range of the given Memory with the same semantics when copying between overlapping ranges of bytes as method System.arraycopy(Object, int, Object, int, int) has. However, if the source and the destination ranges are exactly the same, this method throws IllegalArgumentException, because it should never be needed in real-world scenarios and therefore indicates a bug.
      Parameters:
      srcOffsetBytes - the source offset for this Memory
      destination - the destination Memory, which may not be Read-Only.
      dstOffsetBytes - the destination offset
      lengthBytes - the number of bytes to copy

    • writeToByteStream

      void writeToByteStream(long offsetBytes, int lengthBytes, ByteArrayOutputStream out) throws IOException
      Writes bytes from a source range of this Memory to the given WritableByteChannel.
      Parameters:
      offsetBytes - the source offset for this Memory
      lengthBytes - the number of bytes to copy
      out - the destination ByteArrayOutputStream
      Throws:
      IOException - may occur while writing to the ByteArrayOutputStream.