public interface Resource extends AutoCloseable
Modifier and Type | Field and Description |
---|---|
static MemoryRequestServer |
defaultMemReqSvr
The default MemoryRequestServer is used if not specified by the user.
|
Modifier and Type | Method and Description |
---|---|
void |
close()
Closes this resource if this can be closed via AutoCloseable.
|
boolean |
equalTo(long thisOffsetBytes,
Resource that,
long thatOffsetBytes,
long lengthBytes)
Returns true if the given Resource has equal contents to
this object in the given range of bytes.
|
default boolean |
equalTo(Resource that)
Returns true if the given object (that) is an instance of this class and has contents equal to
this object.
|
void |
force()
Forces any changes made to the contents of this memory-mapped Resource to be written to the storage
device described by the configured file descriptor.
|
long |
getCapacity()
Gets the capacity of this object in bytes
|
default long |
getCumulativeOffset()
Gets the cumulative offset in bytes of this object from the backing resource.
|
long |
getCumulativeOffset(long offsetBytes)
Gets the cumulative offset in bytes of this object from the backing resource including the given
offsetBytes.
|
MemoryRequestServer |
getMemoryRequestServer()
Gets the MemoryRequestServer object, if set, for the below resources to request additional memory.
|
long |
getRelativeOffset()
Returns the offset of address zero of this object relative to the base address of the
backing resource.
|
ByteOrder |
getTypeByteOrder()
Gets the current 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()
Returns true if this object is alive and has not been closed.
|
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()
If true, the backing resource is off-heap memory.
|
boolean |
isDuplicate()
Returns true if this instance is a duplicate of a Buffer instance.
|
boolean |
isHeap()
Returns true if this object is backed by an on-heap primitive array or an on-heap ByteBuffer.
|
boolean |
isLoaded()
Tells whether or not the contents of this memory-mapped Resource is resident in physical memory.
|
boolean |
isMapped()
Returns true if the backing resource is a memory-mapped file.
|
boolean |
isMemory()
If true, this is a Memory or WritableMemory instance, which provides the Memory API.
|
boolean |
isNonNativeOrder()
If true, all put and get operations will assume the non-native ByteOrder.
|
boolean |
isReadOnly()
Returns true if this object or the backing resource is read-only.
|
boolean |
isRegionView()
Returns true if this instance is a region view of another Memory or Buffer
|
boolean |
isSameResource(Resource that)
Returns true if the backing resource of this is identical with the backing resource
of that.
|
void |
load()
Loads the contents of this memory-mapped Resource into physical memory.
|
void |
setMemoryRequestServer(MemoryRequestServer memReqSvr)
Sets the Default MemoryRequestServer
|
String |
toString()
Returns a brief description of this object.
|
String |
toString(String header,
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.
|
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.
|
static final MemoryRequestServer defaultMemReqSvr
MemoryRequestServer getMemoryRequestServer()
WritableMemory enables this for ByteBuffer, Heap and Off-heap Memory backed resources.
WritableBuffer enables this for ByteBuffer backed resources. However, the object returned is in the form of a WritableMemory. To convert to WritableBuffer use asWritableBuffer(). To enable for Heap and Off-heap Buffer resources, use the WritableMemory to configure and then call asWritableBuffer().
Map backed resources will always return null.
The user must customize the actions of the MemoryRequestServer by implementing the MemoryRequestServer interface.
For WritableMemory, to enable at runtime set your custom MemoryRequestServer using one of these methods:
WritableMemory.allocateDirect(long, ByteOrder, MemoryRequestServer)
WritableMemory.allocate(int, ByteOrder, MemoryRequestServer)
WritableMemory.writableWrap(ByteBuffer, ByteOrder, MemoryRequestServer)
ForWritableBuffer, to enable at runtime set your custom MemoryRequestServer using the following method:
Simple implementation examples include the DefaultMemoryRequestServer in the main source tree, as well as the ExampleMemoryRequestServerTest and the use with ByteBuffer documented in the DruidIssue11544Test in the test source tree.
boolean hasMemoryRequestServer()
void setMemoryRequestServer(MemoryRequestServer memReqSvr)
memReqSvr
- the given MemoryRequestServer.void close()
IllegalStateException
.
This operation is not idempotent; that is, closing an already closed resource always results in an exception being thrown. This reflects a deliberate design choice: resource state transitions should be manifest in the client code; a failure in any of these transitions reveals a bug in the underlying application logic.
close
in interface AutoCloseable
IllegalStateException
- if this Resource is not alive.IllegalStateException
- if this method is not accessed from the owning thread.UnsupportedOperationException
- if this resource is not AutoCloseable
.boolean isCloseable()
default boolean equalTo(Resource that)
that
- the given Resource objectequalTo(long, Resource, long, long)
boolean equalTo(long thisOffsetBytes, Resource that, long thatOffsetBytes, long lengthBytes)
thisOffsetBytes
- the starting offset in bytes for this object.that
- the given ResourcethatOffsetBytes
- the starting offset in bytes for the given Resource objectlengthBytes
- the size of the range in bytesIllegalStateException
- if either resource is not alive.MemoryBoundsException
- if there is a bounds violation.void force()
If the file descriptor associated with this memory-mapped Resource resides on a local storage device then when this method returns, it is guaranteed that all changes made to this mapped Resource since it was created, or since this method was last invoked, will have been written to that device.
If the file descriptor associated with this memory-mapped Resource does not reside on a local device then no such guarantee is made.
If this memory-mapped Resource was not mapped in read/write mode
(FileChannel.MapMode.READ_WRITE
) then invoking this method may have no effect.
In particular, this method has no effect for files mapped in read-only or private
mapping modes. This method may or may not have an effect for implementation-specific mapping modes.
IllegalStateException
- if this Resource is not alive.IllegalStateException
- if this method is not accessed from the owning thread.UnsupportedOperationException
- if this Resource is not memory-mapped, e.g. if isMapped() == false
.ReadOnlyException
- if this Resource is read-only.RuntimeException
- if there is some other error writing the contents of this
memory-mapped Resource to the associated storage device.long getCapacity()
default long getCumulativeOffset()
long getCumulativeOffset(long offsetBytes)
offsetBytes
- offset to be added to the cumulative offset.long getRelativeOffset()
ByteOrder getTypeByteOrder()
ByteOrder.nativeOrder()
boolean hasByteBuffer()
boolean isByteOrderCompatible(ByteOrder byteOrder)
byteOrder
- the given ByteOrderboolean isDirect()
boolean isDuplicate()
boolean isHeap()
boolean isLoaded()
A return value of true
implies that it is highly likely that all of the data in this memory-mapped
Resource is resident in physical memory and may therefore be accessed without incurring any virtual-memory page
faults or I/O operations.
A return value of false
does not necessarily imply that all of the data in this memory-mapped Resource
is not resident in physical memory.
The returned value is a hint, rather than a guarantee, because the underlying operating system may have paged out some of this Resource's data by the time that an invocation of this method returns.
IllegalStateException
- if this Resource is not alive.IllegalStateException
- if this method is not accessed from the owning thread.UnsupportedOperationException
- if this Resource is not memory-mapped, e.g. if isMapped() == false
.boolean isMemory()
The Buffer API is largely parallel to the Memory API except that it adds a positional API similar to that in ByteBuffer. The positional API is a convenience when iterating over structured arrays, or buffering input or output streams (thus the name).
boolean isMapped()
boolean isNonNativeOrder()
boolean isReadOnly()
boolean isRegionView()
boolean isSameResource(Resource that)
that
- A different non-null Resourceboolean isAlive()
void load()
This method makes a best effort to ensure that, when it returns, this contents of the memory-mapped Resource is resident in physical memory. Invoking this method may cause some number of page faults and I/O operations to occur.
IllegalStateException
- if this Resource is not alive.IllegalStateException
- if this method is not accessed from the owning thread.UnsupportedOperationException
- if this Resource is not memory-mapped, e.g. if isMapped() == false
.String toString(String header, long offsetBytes, int lengthBytes, boolean withData)
header
- a descriptive headeroffsetBytes
- 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 rangeString toString()
long xxHash64(long offsetBytes, long lengthBytes, long seed)
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.long xxHash64(long in, long seed)
in
- A long.seed
- A long valued seed.Copyright © 2015–2024. All rights reserved.