Interface Resource
- All Known Subinterfaces:
Buffer,Memory,WritableBuffer,WritableMemory
Resource relies on preview features of the Java platform:
Resourcerefers to one or more preview APIs:Arena,MemorySegment,Scope.
- Author:
- Lee Rhodes
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final MemoryRequestServerThe default MemoryRequestServer used primarily by test. -
Method Summary
Modifier and TypeMethodDescriptionasByteBufferView(ByteOrder order) Returns a ByteBuffer view of this Memory object with the given ByteOrder.intcompareTo(long thisOffsetBytes, long thisLengthBytes, Resource that, long thatOffsetBytes, long thatLengthBytes) Compares the bytes of this Resource to that Resource.booleanReturns 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 booleanReturns true if the given object is an instance of this class and has equal contents to this object.voidforce()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.getArena()Returns the arena used to create this resource and possibly other resources.longGets the capacity of this object in bytesGets theMemoryRequestServerto request additional memory for writable resources that are not file-memory-mapped.Gets the MemorySegment that backs this resource as a read-only MemorySegment.longgetRelativeOffset(Resource that) Gets the relative base offset of this resource with respect to that resource, defined as: this - that.Gets the current Type ByteOrder.booleanReturns true if this Memory is backed by a ByteBuffer.booleanReturns true if the MemoryRequestServer has been configured by the user.booleanisAlive()Is the underlying resource scope alive?booleanisBuffer()Returns true if this instance is a Buffer or WritableBuffer instance.booleanisByteOrderCompatible(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.booleanisDirect()Returns true if the backing resource is direct (off-heap) memory.booleanReturns true if this instance is a duplicate of a Buffer instance.booleanisHeap()Returns true if the backing resource is on the Java heap.booleanisLoaded()Returns true if it is likely that the contents of this segment is resident in physical memory.booleanisMapped()Returns true if this instance is of a memory mapped file.booleanisMemory()Returns true if this instance is of a Memory or WritableMemory instancebooleanReturns true if this object or the backing resource is read-only.booleanisRegion()Returns true if this instance is a region view of another Memory or BufferbooleanisSameResource(Resource that) Returns true if the underlying resource is the same resource as that.voidload()Loads the contents of this mapped segment into physical memory.longFinds the first byte mismatch with that.longmismatch(Resource src, long srcFromOffset, long srcToOffset, Resource dst, long dstFromOffset, long dstToOffset) Finds the first byte mismatch based on the given offsetslongnativeOverlap(Resource that) Returns a positive number if this overlaps that and this base address is ≤ that base address.scope()Returns the resource scope associated with this memory segment.voidsetMemoryRequestServer(MemoryRequestServer memReqSvr) Sets the MemoryRequestServer to be used in case of capacity overflow of on-heap or off-heap allocated Memory.toByteBuffer(ByteOrder order) Returns a new ByteBuffer with a copy of the data from this Memory object.toMemorySegment(ArenaPREVIEW arena, long alignment) Returns a copy of the underlying MemorySegment in the given arena.toString()Returns a brief description of this object.Returns a description of this object with an optional formatted hex string of the data for the specified a range.voidunload()Unloads the contents of this mapped segment from physical memory.longxxHash64(long in, long seed) Returns a 64-bit hash from a single long.longxxHash64(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
The default MemoryRequestServer used primarily by test. Do not allocate requested memory off-heap.
-
-
Method Details
-
getMemoryRequestServer
MemoryRequestServer getMemoryRequestServer()Gets theMemoryRequestServerto 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 theWritableMemory.allocateDirect(long, long, ByteOrder, MemoryRequestServer, Arena)PREVIEW 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
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
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.
-
compareTo
int compareTo(long thisOffsetBytes, long thisLengthBytes, Resource that, long thatOffsetBytes, long thatLengthBytes) Compares the bytes of this Resource to that Resource. 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 ResourcethisLengthBytes- the length of the region to compare from this Resourcethat- the other Memory to compare withthatOffsetBytes- the starting offset for that ResourcethatLengthBytes- the length of the region to compare from that Resource- Returns:
- (this < that) ? (some negative value) : (this > that) ? (some positive value) : 0;
-
equalTo
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
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 objectthatOffsetBytes- the starting offset in bytes for the given objectlengthBytes- 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:
-
getArena
Returns the arena used to create this resource and possibly other resources. Be careful when you close the returned Arena, you may be closing other resources as well.- Returns:
- the arena used to create this resource and possibly other resources. It may be null.
-
getCapacity
long getCapacity()Gets the capacity of this object in bytes- Returns:
- the capacity of this object in bytes
-
getMemorySegment
MemorySegmentPREVIEW getMemorySegment()Gets the MemorySegment that backs this resource as a read-only MemorySegment.- Returns:
- the MemorySegment that back this resource as a read-only MemorySegment.
-
getRelativeOffset
Gets the relative base offset of this resource with respect to that resource, defined as: this - that.- Parameters:
that- the given resource.- Returns:
- this - that offset
- Throws:
UnsupportedOperationException- if the two resources cannot be compared, e.g. because they are of different kinds, or because they are backed by different Java arrays.
-
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
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()Returns true if it is likely that the contents of this segment is resident in physical memory.- Returns:
- true if it is likely that the contents of this segment is resident in physical memory.
- See Also:
-
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
Returns true if the underlying resource is the same resource as that.Two resources are considered the same if one were to write a value at offset A in one resource and that same value appears in the other resource at the same offset A. In other words, if two regions (or slices) are derived from the same underlying resource they both must have the same starting offset with respect to the resource and the same size in order to be considered to be the same resource.
Note: for on-heap resources neither this nor that can be read-only.
- Parameters:
that- the other Resource.- Returns:
- true if the underlying resource is the same underlying resource as that.
-
load
void load()Loads the contents of this mapped segment into physical memory.- See Also:
-
mismatch
Finds the first byte mismatch with that.- 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.
- See Also:
-
mismatch
long mismatch(Resource src, long srcFromOffset, long srcToOffset, Resource dst, long dstFromOffset, long dstToOffset) Finds the first byte mismatch based on the given offsets- Parameters:
src- the given source ResourcesrcFromOffset- the given start offset of the source region, inclusive.srcToOffset- the given end offset of the source region, exclusive.dst- the given destination ResourcedstFromOffset- the given start of the destination destination region, inclusive.dstToOffset- the given end offset of the destination destination region, exclusive.- Returns:
- the byte offset of the first mismatch relative to the start of each of the above two regions.
- See Also:
-
nativeOverlap
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.
-
scope
MemorySegment.ScopePREVIEW scope()Returns the resource scope associated with this memory segment.- Returns:
- the resource scope associated with this memory segment.
-
toByteBuffer
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.
-
toMemorySegment
Returns a copy of the underlying MemorySegment in the given arena.- Parameters:
arena- the given arena. If the desired result is to be off-heap, the arena must not be null. Otherwise, the result will be on-heap. Warning: This class is not thread-safe. Specifying an Arena that allows multiple threads is not recommended.alignment- requested segment alignment. Typically 1, 2, 4 or 8.- Returns:
- a copy of the underlying MemorySegment in the given arena.
-
toString
String toString()Returns a brief description of this object. -
toString
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 descriptionoffsetBytes- offset bytes relative to this object startlengthBytes- number of bytes to convert to a hex stringwithData- include output listing of byte data in the given range- Returns:
- a description and hex output in a human readable format.
-
unload
void unload()Unloads the contents of this mapped segment from physical memory.- See Also:
-
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.
-
Resourcewhen preview features are enabled.