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:
  - force()

### 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.