Package org.apache.datasketches.memory

Interface Resource

All Superinterfaces:
AutoCloseable
All Known Subinterfaces:
Buffer, Memory, WritableBuffer, WritableMemory
public interface Resource extends AutoCloseable
The base class for Memory and Buffer plus some common static variables and check methods.
Author:
Lee Rhodes

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final MemoryRequestServer
    defaultMemReqSvr
    The default MemoryRequestServer used primarily by test.

  • Method Summary

    Modifier and Type
    Method
    Description
    ByteBuffer
    asByteBufferView(ByteOrder order)
    Returns a ByteBuffer view of this Memory object with the given ByteOrder.
    void
    close()
    From Java 17 ResourceScope::close():
    boolean
    equalTo(long thisOffsetBytes, Resource that, long thatOffsetBytes, long lengthBytes)
    Returns true if the given object is an instance of this class and has equal contents to this object in the given range of bytes.
    default boolean
    equalTo(Resource that)
    Returns true if the given object is an instance of this class and has equal contents to this object.
    void
    force()
    Forces any changes made to the contents of this mapped segment to be written to the storage device described by the mapped segment's file descriptor.
    long
    getCapacity()
    Gets the capacity of this object in bytes
    MemoryRequestServer
    getMemoryRequestServer()
    Gets the MemoryRequestServer to request additional memory for writable resources that are not file-memory-mapped.
    Thread
    getOwnerThread()
    Return the owner thread of the underlying ResourceScope, or null.
    long
    getRelativeOffset(Resource that)
    Gets the relative base offset of this with respect to that, defined as: this - that.
    ByteOrder
    getTypeByteOrder()
    Gets the current Type ByteOrder.
    boolean
    hasByteBuffer()
    Returns true if this Memory is backed by a ByteBuffer.
    boolean
    hasMemoryRequestServer()
    Returns true if the MemoryRequestServer has been configured by the user.
    boolean
    isAlive()
    Is the underlying resource scope alive?
    boolean
    isBuffer()
    Returns true if this instance is a Buffer or WritableBuffer instance.
    boolean
    isByteOrderCompatible(ByteOrder byteOrder)
    Returns true if the Native ByteOrder is the same as the ByteOrder of the current Buffer or Memory and the same ByteOrder as the given byteOrder.
    boolean
    isCloseable()
    Return true if this resource is closeable.
    boolean
    isDirect()
    Returns true if the backing resource is direct (off-heap) memory.
    boolean
    isDuplicate()
    Returns true if this instance is a duplicate of a Buffer instance.
    boolean
    isHeap()
    Returns true if the backing resource is on the Java heap.
    boolean
    isLoaded()
    Tells whether or not the contents of this mapped segment is resident in physical memory.
    boolean
    isMapped()
    Returns true if this instance is of a memory mapped file.
    boolean
    isMemory()
    Returns true if this instance is of a Memory or WritableMemory instance
    boolean
    isReadOnly()
    Returns true if this object or the backing resource is read-only.
    boolean
    isRegion()
    Returns true if this instance is a region view of another Memory or Buffer
    boolean
    isSameResource(Resource that)
    Returns true if the underlying resource is the same underlying resource as that.
    void
    load()
    Loads the contents of this mapped segment into physical memory.
    long
    mismatch(Resource that)
    See mismatch(...)
    long
    nativeOverlap(Resource that)
    Returns a positive number if this overlaps that and this base address is ≤ that base address.
    ResourceScope
    scope()
    Returns the resource scope associated with this memory segment.
    void
    setMemoryRequestServer(MemoryRequestServer memReqSvr)
    Sets the MemoryRequestServer to be used in case of capacity overflow of on-heap or off-heap allocated Memory.
    ByteBuffer
    toByteBuffer(ByteOrder order)
    Returns a new ByteBuffer with a copy of the data from this Memory object.
    MemorySegment
    toMemorySegment()
    Returns a copy of the underlying MemorySegment.
    String
    toString()
    Returns a brief description of this object.
    String
    toString(String comment, long offsetBytes, int lengthBytes, boolean withData)
    Returns a description of this object with an optional formatted hex string of the data for the specified a range.
    void
    unload()
    Unloads the contents of this mapped segment from physical memory.
    long
    xxHash64(long in, long seed)
    Returns a 64-bit hash from a single long.
    long
    xxHash64(long offsetBytes, long lengthBytes, long seed)
    Returns the 64-bit hash of the sequence of bytes in this object specified by offsetBytes, lengthBytes and a seed.

  • Field Details

    • defaultMemReqSvr

      static final MemoryRequestServer defaultMemReqSvr
      The default MemoryRequestServer used primarily by test.

  • Method Details

    • getMemoryRequestServer

      MemoryRequestServer getMemoryRequestServer()
      Gets the MemoryRequestServer to request additional memory for writable resources that are not file-memory-mapped. Read-only, file-memory-mapped resources will return null.

      The user can customize the actions of the MemoryRequestServer by implementing the MemoryRequestServer interface and set it using the setMemoryRequestServer(MemoryRequestServer) method or optionally with the WritableMemory.allocateDirect(long, long, ByteOrder, MemoryRequestServer) method.

      If the MemoryRequestServer is not set by the user and additional memory is needed by the sketch, null will be returned and the sketch will abort. Simple implementation examples include the DefaultMemoryRequestServer in the main tree, as well as the ExampleMemoryRequestServerTest and the use with ByteBuffer documented in the DruidIssue11544Test in the test tree.

      Returns:
      a MemoryRequestServer object or null.

    • hasMemoryRequestServer

      boolean hasMemoryRequestServer()
      Returns true if the MemoryRequestServer has been configured by the user.
      Returns:
      true if the MemoryRequestServer has been configured by the user..

    • setMemoryRequestServer

      void setMemoryRequestServer(MemoryRequestServer memReqSvr)
      Sets the MemoryRequestServer to be used in case of capacity overflow of on-heap or off-heap allocated Memory.
      Parameters:
      memReqSvr - the given MemoryRequestServer

    • asByteBufferView

      ByteBuffer asByteBufferView(ByteOrder order)
      Returns a ByteBuffer view of this Memory object with the given ByteOrder. Some of the properties of the returned buffer are linked to the properties of this Memory object. For instance, if this Memory object is immutable (i.e., read-only, see isReadOnly()), then the resulting buffer is read-only (see Buffer.isReadOnly(). Additionally, if this is a native memory segment, the resulting buffer is direct (see ByteBuffer.isDirect()). The endianness of the returned buffer will be set to the given ByteOrder.
      Parameters:
      order - the given ByteOrder.
      Returns:
      a ByteBuffer view of this Memory object with the given ByteOrder.
      Throws:
      UnsupportedOperationException - - if this segment cannot be mapped onto a ByteBuffer instance, e.g. because it models an heap-based segment that is not based on a byte[]), or if its size is greater than Integer.MAX_VALUE.

    • close

      void close()
      From Java 17 ResourceScope::close():

      Closes this resource scope. As a side-effect, if this operation completes without exceptions, this scope will be marked as not alive, and subsequent operations on resources associated with this scope will fail with IllegalStateException. Additionally, upon successful closure, all direct (native) resources associated with this resource scope will be released.

      API Note This operation is not idempotent; that is, closing an already closed resource scope always results in an exception being thrown. This reflects a deliberate design choice: resource scope state transitions should be manifest in the client code; a failure in any of these transitions reveals a bug in the underlying application logic.

      Specified by:
      close in interface AutoCloseable
      Throws:
      IllegalStateException - if one of the following condition is met:
      • this resource scope is not alive
      • this resource scope is confined, and this method is called from a thread other than the thread owning this resource scope
      • this resource scope is shared and a resource associated with this scope is accessed while this method is called
      UnsupportedOperationException - if this resource scope is implicit}.

    • isCloseable

      boolean isCloseable()
      Return true if this resource is closeable.
      Returns:
      true if this resource is closeable.

    • equalTo

      default boolean equalTo(Resource that)
      Returns true if the given object is an instance of this class and has equal contents to this object.
      Parameters:
      that - the given Resource object
      Returns:
      true if the given object has equal contents to this object.

    • equalTo

      boolean equalTo(long thisOffsetBytes, Resource that, long thatOffsetBytes, long lengthBytes)
      Returns true if the given object is an instance of this class and has equal contents to this object in the given range of bytes. This will also check two distinct ranges within the same object for equals.
      Parameters:
      thisOffsetBytes - the starting offset in bytes for this object.
      that - the given Resource object
      thatOffsetBytes - the starting offset in bytes for the given object
      lengthBytes - the size of the range in bytes
      Returns:
      true if the given object has equal contents to this object in the given range of bytes.

    • force

      void force()
      Forces any changes made to the contents of this mapped segment to be written to the storage device described by the mapped segment's file descriptor.
      See Also:

    • getCapacity

      long getCapacity()
      Gets the capacity of this object in bytes
      Returns:
      the capacity of this object in bytes

    • getOwnerThread

      Thread getOwnerThread()
      Return the owner thread of the underlying ResourceScope, or null.
      Returns:
      the owner thread of the underlying ResourceScope, or null.

    • getRelativeOffset

      long getRelativeOffset(Resource that)
      Gets the relative base offset of this with respect to that, defined as: this - that. This method is only valid for native (off-heap) allocated resources.
      Parameters:
      that - the given resource.
      Returns:
      this - that offset
      Throws:
      IllegalArgumentException - if one of the resources is on-heap.

    • getTypeByteOrder

      ByteOrder getTypeByteOrder()
      Gets the current Type ByteOrder. This may be different from the ByteOrder of the backing resource and of the Native Byte Order.
      Returns:
      the current Type ByteOrder.

    • hasByteBuffer

      boolean hasByteBuffer()
      Returns true if this Memory is backed by a ByteBuffer.
      Returns:
      true if this Memory is backed by a ByteBuffer.

    • isAlive

      boolean isAlive()
      Is the underlying resource scope alive?
      Returns:
      true, if the underlying resource scope is alive.

    • isBuffer

      boolean isBuffer()
      Returns true if this instance is a Buffer or WritableBuffer instance.
      Returns:
      true if this instance is a Buffer or WritableBuffer instance.

    • isByteOrderCompatible

      boolean isByteOrderCompatible(ByteOrder byteOrder)
      Returns true if the Native ByteOrder is the same as the ByteOrder of the current Buffer or Memory and the same ByteOrder as the given byteOrder.
      Parameters:
      byteOrder - the given ByteOrder
      Returns:
      true if the Native ByteOrder is the same as the ByteOrder of the current Buffer or Memory and the same ByteOrder as the given byteOrder.

    • isDirect

      boolean isDirect()
      Returns true if the backing resource is direct (off-heap) memory. This can be true for allocated direct memory, memory mapped files, or from a wrapped ByteBuffer that was allocated direct.
      Returns:
      true if the backing resource is direct (off-heap) memory.

    • isDuplicate

      boolean isDuplicate()
      Returns true if this instance is a duplicate of a Buffer instance.
      Returns:
      true if this instance is a duplicate of a Buffer instance.

    • isHeap

      boolean isHeap()
      Returns true if the backing resource is on the Java heap. This can be true for wrapped heap primitive arrays or from a wrapped ByteBuffer that was allocated on the Java heap.
      Returns:
      true if the backing resource is on the Java heap.

    • isLoaded

      boolean isLoaded()
      Tells whether or not the contents of this mapped segment is resident in physical memory. Please refer to isLoaded().
      Returns:
      true if it is likely that the contents of this segment is resident in physical memory.

    • isMapped

      boolean isMapped()
      Returns true if this instance is of a memory mapped file.
      Returns:
      true if this instance is of a memory mapped file.

    • isMemory

      boolean isMemory()
      Returns true if this instance is of a Memory or WritableMemory instance
      Returns:
      true if this instance is of a Memory or WritableMemory instance

    • isReadOnly

      boolean isReadOnly()
      Returns true if this object or the backing resource is read-only.
      Returns:
      true if this object or the backing resource is read-only.

    • isRegion

      boolean isRegion()
      Returns true if this instance is a region view of another Memory or Buffer
      Returns:
      true if this instance is a region view of another Memory or Buffer

    • isSameResource

      boolean isSameResource(Resource that)
      Returns true if the underlying resource is the same underlying resource as that.
      Parameters:
      that - the other Resource object
      Returns:
      a long value representing the ordering and size of overlap between this and that

    • load

      void load()
      Loads the contents of this mapped segment into physical memory. Please refer to load()

    • nativeOverlap

      long nativeOverlap(Resource that)
      Returns a positive number if this overlaps that and this base address is ≤ that base address. Returns a negative number if this overlaps that and this base address is > that base address. Returns a zero if there is no overlap or if one or both objects are null, not active or on heap.
      Parameters:
      that - the other Resource object
      Returns:
      a long value representing the ordering and size of overlap between this and that.

    • mismatch

      long mismatch(Resource that)
      See mismatch(...)
      Parameters:
      that - the other Resource
      Returns:
      the relative offset, in bytes, of the first mismatch between this and the given other Resource object, otherwise -1 if no mismatch

    • scope

      ResourceScope scope()
      Returns the resource scope associated with this memory segment.
      Returns:
      the resource scope associated with this memory segment.

    • toByteBuffer

      ByteBuffer toByteBuffer(ByteOrder order)
      Returns a new ByteBuffer with a copy of the data from this Memory object. This new ByteBuffer will be writable, on heap, and with the endianness specified by the given ByteOrder.
      Parameters:
      order - the given ByteOrder. It must be non-null.
      Returns:
      a new ByteBuffer with a copy of the data from this Memory object.

    • toString

      String toString()
      Returns a brief description of this object.
      Overrides:
      toString in class Object
      Returns:
      a brief description of this object.

    • toString

      String toString(String comment, long offsetBytes, int lengthBytes, boolean withData)
      Returns a description of this object with an optional formatted hex string of the data for the specified a range. Used primarily for testing.
      Parameters:
      comment - a description
      offsetBytes - offset bytes relative to this object start
      lengthBytes - number of bytes to convert to a hex string
      withData - include output listing of byte data in the given range
      Returns:
      a description and hex output in a human readable format.

    • toMemorySegment

      MemorySegment toMemorySegment()
      Returns a copy of the underlying MemorySegment. The size is limited to Integer.MAX_VALUE.
      Returns:
      a copy of the underlying MemorySegment

    • unload

      void unload()
      Unloads the contents of this mapped segment from physical memory. Please refer to unload()

    • xxHash64

      long xxHash64(long in, long seed)
      Returns a 64-bit hash from a single long. This method has been optimized for speed when only a single hash of a long is required.
      Parameters:
      in - A long.
      seed - A long valued seed.
      Returns:
      the hash.

    • xxHash64

      long xxHash64(long offsetBytes, long lengthBytes, long seed)
      Returns the 64-bit hash of the sequence of bytes in this object specified by offsetBytes, lengthBytes and a seed. Note that the sequence of bytes is always processed in the same order independent of endianness.
      Parameters:
      offsetBytes - the given offset in bytes to the first byte of the byte sequence.
      lengthBytes - the given length in bytes of the byte sequence.
      seed - the given long seed.
      Returns:
      the 64-bit hash of the sequence of bytes in this object specified by offsetBytes and lengthBytes.