Interface WritableMemory
-
- All Superinterfaces:
AutoCloseable
,Memory
,Resource
public interface WritableMemory extends Memory
Defines the writable API for offset access to a resource.The classes in this package are not thread-safe.
- Author:
- Lee Rhodes
-
-
Field Summary
-
Fields inherited from interface org.apache.datasketches.memory.Resource
defaultMemReqSvr
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description static WritableMemory
allocate(int capacityBytes)
Creates on-heap WritableMemory with the given capacity and the native byte order.static WritableMemory
allocate(int capacityBytes, ByteOrder byteOrder)
Creates on-heap WritableMemory with the given capacity and the given byte order.static WritableMemory
allocate(int capacityBytes, ByteOrder byteOrder, MemoryRequestServer memReqSvr)
Creates on-heap WritableMemory with the given capacity and the given byte order.static WritableMemory
allocateDirect(long capacityBytes)
Allocates and provides access to capacityBytes directly in native (off-heap) memory.static WritableMemory
allocateDirect(long capacityBytes, ByteOrder byteOrder, MemoryRequestServer memReqSvr)
Allocates and provides access to capacityBytes directly in native (off-heap) memory.default WritableBuffer
asWritableBuffer()
Returns a new WritableBuffer with a writable view of this object.WritableBuffer
asWritableBuffer(ByteOrder byteOrder)
Returns a new WritableBuffer with a writable view of this object with the given byte order.void
clear()
Clears all bytes of this Memory to zerovoid
clear(long offsetBytes, long lengthBytes)
Clears a portion of this Memory to zero.void
clearBits(long offsetBytes, byte bitMask)
Clears the bits defined by the bitMaskvoid
fill(byte value)
Fills all bytes of this Memory region to the given byte value.void
fill(long offsetBytes, long lengthBytes, byte value)
Fills a portion of this Memory region to the given byte value.void
putBoolean(long offsetBytes, boolean value)
Puts the boolean value at the given offsetvoid
putBooleanArray(long offsetBytes, boolean[] srcArray, int srcOffsetBooleans, int lengthBooleans)
Puts the boolean array at the given offsetvoid
putByte(long offsetBytes, byte value)
Puts the byte value at the given offsetvoid
putByteArray(long offsetBytes, byte[] srcArray, int srcOffsetBytes, int lengthBytes)
Puts the byte array at the given offsetvoid
putChar(long offsetBytes, char value)
Puts the char value at the given offsetvoid
putCharArray(long offsetBytes, char[] srcArray, int srcOffsetChars, int lengthChars)
Puts the char array at the given offsetlong
putCharsToUtf8(long offsetBytes, CharSequence src)
Encodes characters from the given CharSequence into UTF-8 bytes and puts them into this WritableMemory beginning at the given offsetBytes.void
putDouble(long offsetBytes, double value)
Puts the double value at the given offsetvoid
putDoubleArray(long offsetBytes, double[] srcArray, int srcOffsetDoubles, int lengthDoubles)
Puts the double array at the given offsetvoid
putFloat(long offsetBytes, float value)
Puts the float value at the given offsetvoid
putFloatArray(long offsetBytes, float[] srcArray, int srcOffsetFloats, int lengthFloats)
Puts the float array at the given offsetvoid
putInt(long offsetBytes, int value)
Puts the int value at the given offsetvoid
putIntArray(long offsetBytes, int[] srcArray, int srcOffsetInts, int lengthInts)
Puts the int array at the given offsetvoid
putLong(long offsetBytes, long value)
Puts the long value at the given offsetvoid
putLongArray(long offsetBytes, long[] srcArray, int srcOffsetLongs, int lengthLongs)
Puts the long array at the given offsetvoid
putShort(long offsetBytes, short value)
Puts the short value at the given offsetvoid
putShortArray(long offsetBytes, short[] srcArray, int srcOffsetShorts, int lengthShorts)
Puts the short array at the given offsetvoid
setBits(long offsetBytes, byte bitMask)
Sets the bits defined by the bitMaskstatic WritableMemory
writableMap(File file)
Maps the entire given file into native-ordered WritableMemory for write operations Calling this method is equivalent to callingwritableMap(file, 0, file.length(), ByteOrder.nativeOrder())
.static WritableMemory
writableMap(File file, long fileOffsetBytes, long capacityBytes, ByteOrder byteOrder)
Maps the specified portion of the given file into Memory for write operations.default WritableMemory
writableRegion(long regionOffsetBytes, long capacityBytes)
A writable region is a writable view of this object.WritableMemory
writableRegion(long offsetBytes, long capacityBytes, ByteOrder byteOrder)
A writable region is a writable view of this object.static WritableMemory
writableWrap(boolean[] array)
Wraps the given primitive array for write operations assuming native byte order.static WritableMemory
writableWrap(byte[] array)
Wraps the given primitive array for write operations assuming native byte order.static WritableMemory
writableWrap(byte[] array, int offsetBytes, int lengthBytes, ByteOrder byteOrder)
Wraps the given primitive array for write operations with the given byte order.static WritableMemory
writableWrap(byte[] array, int offsetBytes, int lengthBytes, ByteOrder byteOrder, MemoryRequestServer memReqSvr)
Wraps the given primitive array for write operations with the given byte order.static WritableMemory
writableWrap(byte[] array, ByteOrder byteOrder)
Wraps the given primitive array for write operations with the given byte order.static WritableMemory
writableWrap(char[] array)
Wraps the given primitive array for write operations assuming native byte order.static WritableMemory
writableWrap(double[] array)
Wraps the given primitive array for write operations assuming native byte order.static WritableMemory
writableWrap(float[] array)
Wraps the given primitive array for write operations assuming native byte order.static WritableMemory
writableWrap(int[] array)
Wraps the given primitive array for write operations assuming native byte order.static WritableMemory
writableWrap(long[] array)
Wraps the given primitive array for write operations assuming native byte order.static WritableMemory
writableWrap(short[] array)
Wraps the given primitive array for write operations assuming native byte order.static WritableMemory
writableWrap(ByteBuffer byteBuffer)
Accesses the given ByteBuffer for write operations.static WritableMemory
writableWrap(ByteBuffer byteBuffer, ByteOrder byteOrder)
Accesses the given ByteBuffer for write operations.static WritableMemory
writableWrap(ByteBuffer byteBuffer, ByteOrder byteOrder, MemoryRequestServer memReqSvr)
Accesses the given ByteBuffer for write operations.-
Methods inherited from interface org.apache.datasketches.memory.Memory
asBuffer, asBuffer, compareTo, copyTo, getBoolean, getBooleanArray, getByte, getByteArray, getChar, getCharArray, getCharsFromUtf8, getCharsFromUtf8, getDouble, getDoubleArray, getFloat, getFloatArray, getInt, getIntArray, getLong, getLongArray, getShort, getShortArray, region, region, writeTo
-
Methods inherited from interface org.apache.datasketches.memory.Resource
close, equalTo, equalTo, force, getByteOrder, getCapacity, getMemoryRequestServer, getTotalOffset, isByteBufferResource, isByteOrderCompatible, isDirectResource, isDuplicateBufferView, isHeapResource, isLoaded, isMemoryApi, isMemoryMappedResource, isNonNativeOrder, isReadOnly, isRegionView, isSameResource, isValid, load, setMemoryRequestServer, toHexString, xxHash64, xxHash64
-
-
-
-
Method Detail
-
writableWrap
static WritableMemory writableWrap(ByteBuffer byteBuffer)
Accesses the given ByteBuffer for write operations. The returned WritableMemory object has the same byte order, as the given ByteBuffer.- Parameters:
byteBuffer
- the given ByteBuffer. It must be non-null, with capacity ≥ 0, and writable.- Returns:
- a new WritableMemory for write operations on the given ByteBuffer.
-
writableWrap
static WritableMemory writableWrap(ByteBuffer byteBuffer, ByteOrder byteOrder)
Accesses the given ByteBuffer for write operations. The returned WritableMemory object has the given byte order, ignoring the byte order of the given ByteBuffer for future writes and following reads. However, this does not change the byte order of data already in the ByteBuffer.- Parameters:
byteBuffer
- the given ByteBuffer. It must be non-null, with capacity ≥ 0, and writable.byteOrder
- the byte order to be used. It must be non-null.- Returns:
- a new WritableMemory for write operations on the given ByteBuffer.
-
writableWrap
static WritableMemory writableWrap(ByteBuffer byteBuffer, ByteOrder byteOrder, MemoryRequestServer memReqSvr)
Accesses the given ByteBuffer for write operations. The returned WritableMemory object has the given byte order, ignoring the byte order of the given ByteBuffer for future reads and writes. However, this does not change the byte order of data already in the ByteBuffer.- Parameters:
byteBuffer
- the given ByteBuffer. It must be non-null, with capacity ≥ 0, and writable.byteOrder
- the byte order to be used. It must be non-null.memReqSvr
- A user-specified MemoryRequestServer, which may be null. This is a callback mechanism for a user client to request a larger WritableMemory.- Returns:
- a new WritableMemory for write operations on the given ByteBuffer.
-
writableMap
static WritableMemory writableMap(File file)
Maps the entire given file into native-ordered WritableMemory for write operations Calling this method is equivalent to callingwritableMap(file, 0, file.length(), ByteOrder.nativeOrder())
.- Parameters:
file
- the given file to map. It must be non-null, with length ≥ 0, and writable.- Returns:
- WritableMemory for managing the mapped Memory.
-
writableMap
static WritableMemory writableMap(File file, long fileOffsetBytes, long capacityBytes, ByteOrder byteOrder)
Maps the specified portion of the given file into Memory for write operations.Note: Always qualify this method with the class name, e.g., WritableMemory.map(...).
- Parameters:
file
- the given file to map. It must be non-null, writable 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 for the given file. It must be non-null.- Returns:
- WritableMemory for managing the mapped Memory.
-
allocateDirect
static WritableMemory allocateDirect(long capacityBytes)
Allocates and provides access to capacityBytes directly in native (off-heap) memory. Native byte order is assumed. The allocated memory will be 8-byte aligned, but may not be page aligned.NOTE: Native/Direct memory acquired may have garbage in it. It is the responsibility of the using application to clear this memory, if required, and to call close() when done.
- Parameters:
capacityBytes
- the size of the desired memory in bytes. It must be ≥ 0.- Returns:
- WritableMemory for this off-heap resource.
-
allocateDirect
static WritableMemory allocateDirect(long capacityBytes, ByteOrder byteOrder, MemoryRequestServer memReqSvr)
Allocates and provides access to capacityBytes directly in native (off-heap) memory. The allocated memory will be 8-byte aligned, but may not be page aligned.NOTE: Native/Direct memory acquired may have garbage in it. It is the responsibility of the using application to clear this memory, if required, and to call close() when done.
- Parameters:
capacityBytes
- the size of the desired memory in bytes. It must be ≥ 0.byteOrder
- the given byte order. It must be non-null.memReqSvr
- A user-specified MemoryRequestServer, which may be null. This is a callback mechanism for a user client of direct memory to request more memory.- Returns:
- WritableMemory for this off-heap resource.
-
writableRegion
default WritableMemory writableRegion(long regionOffsetBytes, long capacityBytes)
A writable region is a writable view of this object. This returns a new WritableMemory representing the defined writable region with the given offsetBytes and capacityBytes.- Returned object's origin = this objects' origin + offsetBytes
- Returned object's capacity = capacityBytes
- Parameters:
regionOffsetBytes
- the starting offset with respect to this object. It must be ≥ 0.capacityBytes
- the capacity of the returned object in bytes. It must be ≥ 0.- Returns:
- a new WritableMemory representing the defined writable region.
-
writableRegion
WritableMemory writableRegion(long offsetBytes, long capacityBytes, ByteOrder byteOrder)
A writable region is a writable view of this object. This returns a new WritableMemory representing the defined writable region with the given offsetBytes, capacityBytes and byte order.- Returned object's origin = this objects' origin + offsetBytes
- Returned object's capacity = capacityBytes
- Returned object's byte order = byteOrder
- Parameters:
offsetBytes
- the starting offset with respect to this object. It must be ≥ 0.capacityBytes
- the capacity of the returned object in bytes. It must be ≥ 0.byteOrder
- the given byte order. It must be non-null.- Returns:
- a new WritableMemory representing the defined writable region.
-
asWritableBuffer
default WritableBuffer asWritableBuffer()
Returns a new WritableBuffer with a writable 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 WritableBuffer with a view of this WritableMemory
-
asWritableBuffer
WritableBuffer asWritableBuffer(ByteOrder byteOrder)
Returns a new WritableBuffer with a writable 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- Returns:
- a new WritableBuffer with a view of this WritableMemory
-
allocate
static WritableMemory allocate(int capacityBytes)
Creates on-heap WritableMemory with the given capacity and the native byte order.- Parameters:
capacityBytes
- the given capacity in bytes. It must be ≥ 0.- Returns:
- a new WritableMemory for write operations on a new byte array.
-
allocate
static WritableMemory allocate(int capacityBytes, ByteOrder byteOrder)
Creates on-heap WritableMemory with the given capacity and the given byte order.- Parameters:
capacityBytes
- the given capacity in bytes. It must be ≥ 0.byteOrder
- the given byte order to allocate new Memory object with. It must be non-null.- Returns:
- a new WritableMemory for write operations on a new byte array.
-
allocate
static WritableMemory allocate(int capacityBytes, ByteOrder byteOrder, MemoryRequestServer memReqSvr)
Creates on-heap WritableMemory with the given capacity and the given byte order.- Parameters:
capacityBytes
- the given capacity in bytes. It must be ≥ 0.byteOrder
- the given byte order to allocate new Memory object with. It must be non-null.memReqSvr
- A user-specified MemoryRequestServer, which may be null. This is a callback mechanism for a user client to request a larger WritableMemory.- Returns:
- a new WritableMemory for write operations on a new byte array.
-
writableWrap
static WritableMemory writableWrap(byte[] array)
Wraps the given primitive array for write operations assuming native byte order.Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).
- Parameters:
array
- the given primitive array. It must be non-null.- Returns:
- a new WritableMemory for write operations on the given primitive array.
-
writableWrap
static WritableMemory writableWrap(byte[] array, ByteOrder byteOrder)
Wraps the given primitive array for write operations with the given byte order.Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).
- Parameters:
array
- the given primitive array. It must be non-null.byteOrder
- the byte order to be used. It must be non-null.- Returns:
- a new WritableMemory for write operations on the given primitive array.
-
writableWrap
static WritableMemory writableWrap(byte[] array, int offsetBytes, int lengthBytes, ByteOrder byteOrder)
Wraps the given primitive array for write operations with the given byte order.Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).
- Parameters:
array
- the given primitive array. It must be non-null.offsetBytes
- the byte offset into the given array. It must be ≥ 0.lengthBytes
- the number of bytes to include from the given array. It must be ≥ 0.byteOrder
- the byte order to be used. It must be non-null.- Returns:
- a new WritableMemory for write operations on the given primitive array.
-
writableWrap
static WritableMemory writableWrap(byte[] array, int offsetBytes, int lengthBytes, ByteOrder byteOrder, MemoryRequestServer memReqSvr)
Wraps the given primitive array for write operations with the given byte order. If the given lengthBytes is zero, backing storage, byte order and read-only status of the returned WritableMemory object are unspecified.Note: Always qualify this method with the class name, e.g., WritableMemory.wrap(...).
- Parameters:
array
- the given primitive array. It must be non-null.offsetBytes
- the byte offset into the given array. It must be ≥ 0.lengthBytes
- the number of bytes to include from the given array. It must be ≥ 0.byteOrder
- the byte order to be used. It must be non-null.memReqSvr
- A user-specified MemoryRequestServer, which may be null. This is a callback mechanism for a user client to request a larger WritableMemory.- Returns:
- a new WritableMemory for write operations on the given primitive array.
-
writableWrap
static WritableMemory writableWrap(boolean[] array)
Wraps the given primitive array for write operations assuming native byte order.- Parameters:
array
- the given primitive array. It must be non-null.- Returns:
- a new WritableMemory for write operations on the given primitive array.
-
writableWrap
static WritableMemory writableWrap(char[] array)
Wraps the given primitive array for write operations assuming native byte order.- Parameters:
array
- the given primitive array.- Returns:
- a new WritableMemory for write operations on the given primitive array.
-
writableWrap
static WritableMemory writableWrap(short[] array)
Wraps the given primitive array for write operations assuming native byte order.- Parameters:
array
- the given primitive array.- Returns:
- a new WritableMemory for write operations on the given primitive array.
-
writableWrap
static WritableMemory writableWrap(int[] array)
Wraps the given primitive array for write operations assuming native byte order.- Parameters:
array
- the given primitive array.- Returns:
- a new WritableMemory for write operations on the given primitive array.
-
writableWrap
static WritableMemory writableWrap(long[] array)
Wraps the given primitive array for write operations assuming native byte order.- Parameters:
array
- the given primitive array.- Returns:
- a new WritableMemory for write operations on the given primitive array.
-
writableWrap
static WritableMemory writableWrap(float[] array)
Wraps the given primitive array for write operations assuming native byte order.- Parameters:
array
- the given primitive array.- Returns:
- a new WritableMemory for write operations on the given primitive array.
-
writableWrap
static WritableMemory writableWrap(double[] array)
Wraps the given primitive array for write operations assuming native byte order.- Parameters:
array
- the given primitive array.- Returns:
- a new WritableMemory for write operations on the given primitive array.
-
putBoolean
void putBoolean(long offsetBytes, boolean value)
Puts the boolean value at the given offset- Parameters:
offsetBytes
- offset bytes relative to this WritableMemory startvalue
- the value to put
-
putBooleanArray
void putBooleanArray(long offsetBytes, boolean[] srcArray, int srcOffsetBooleans, int lengthBooleans)
Puts the boolean array at the given offset- Parameters:
offsetBytes
- offset bytes relative to this WritableMemory startsrcArray
- The source array.srcOffsetBooleans
- offset in array unitslengthBooleans
- number of array units to transfer
-
putByte
void putByte(long offsetBytes, byte value)
Puts the byte value at the given offset- Parameters:
offsetBytes
- offset bytes relative to this WritableMemory startvalue
- the value to put
-
putByteArray
void putByteArray(long offsetBytes, byte[] srcArray, int srcOffsetBytes, int lengthBytes)
Puts the byte array at the given offset- Parameters:
offsetBytes
- offset bytes relative to this WritableMemory startsrcArray
- The source array.srcOffsetBytes
- offset in array unitslengthBytes
- number of array units to transfer
-
putChar
void putChar(long offsetBytes, char value)
Puts the char value at the given offset- Parameters:
offsetBytes
- offset bytes relative to this WritableMemory startvalue
- the value to put
-
putCharArray
void putCharArray(long offsetBytes, char[] srcArray, int srcOffsetChars, int lengthChars)
Puts the char array at the given offset- Parameters:
offsetBytes
- offset bytes relative to this WritableMemory startsrcArray
- The source array.srcOffsetChars
- offset in array unitslengthChars
- number of array units to transfer
-
putCharsToUtf8
long putCharsToUtf8(long offsetBytes, CharSequence src)
Encodes characters from the given CharSequence into UTF-8 bytes and puts them into this WritableMemory beginning at the given offsetBytes. This is specifically designed to reduce the production of intermediate objects (garbage), thus significantly reducing pressure on the JVM Garbage Collector.- Parameters:
offsetBytes
- offset bytes relative to this WritableMemory startsrc
- The source CharSequence to be encoded and put into this WritableMemory. It is the responsibility of the caller to provide sufficient capacity in this WritableMemory for the encoded Utf8 bytes. Characters outside the ASCII range can require 2, 3 or 4 bytes per character to encode.- Returns:
- the number of bytes encoded
-
putDouble
void putDouble(long offsetBytes, double value)
Puts the double value at the given offset- Parameters:
offsetBytes
- offset bytes relative to this WritableMemory startvalue
- the value to put
-
putDoubleArray
void putDoubleArray(long offsetBytes, double[] srcArray, int srcOffsetDoubles, int lengthDoubles)
Puts the double array at the given offset- Parameters:
offsetBytes
- offset bytes relative to this WritableMemory startsrcArray
- The source array.srcOffsetDoubles
- offset in array unitslengthDoubles
- number of array units to transfer
-
putFloat
void putFloat(long offsetBytes, float value)
Puts the float value at the given offset- Parameters:
offsetBytes
- offset bytes relative to this WritableMemory startvalue
- the value to put
-
putFloatArray
void putFloatArray(long offsetBytes, float[] srcArray, int srcOffsetFloats, int lengthFloats)
Puts the float array at the given offset- Parameters:
offsetBytes
- offset bytes relative to this WritableMemory startsrcArray
- The source array.srcOffsetFloats
- offset in array unitslengthFloats
- number of array units to transfer
-
putInt
void putInt(long offsetBytes, int value)
Puts the int value at the given offset- Parameters:
offsetBytes
- offset bytes relative to this WritableMemory startvalue
- the value to put
-
putIntArray
void putIntArray(long offsetBytes, int[] srcArray, int srcOffsetInts, int lengthInts)
Puts the int array at the given offset- Parameters:
offsetBytes
- offset bytes relative to this WritableMemory startsrcArray
- The source array.srcOffsetInts
- offset in array unitslengthInts
- number of array units to transfer
-
putLong
void putLong(long offsetBytes, long value)
Puts the long value at the given offset- Parameters:
offsetBytes
- offset bytes relative to this WritableMemory startvalue
- the value to put
-
putLongArray
void putLongArray(long offsetBytes, long[] srcArray, int srcOffsetLongs, int lengthLongs)
Puts the long array at the given offset- Parameters:
offsetBytes
- offset bytes relative to this WritableMemory startsrcArray
- The source array.srcOffsetLongs
- offset in array unitslengthLongs
- number of array units to transfer
-
putShort
void putShort(long offsetBytes, short value)
Puts the short value at the given offset- Parameters:
offsetBytes
- offset bytes relative to this WritableMemory startvalue
- the value to put
-
putShortArray
void putShortArray(long offsetBytes, short[] srcArray, int srcOffsetShorts, int lengthShorts)
Puts the short array at the given offset- Parameters:
offsetBytes
- offset bytes relative to this WritableMemory startsrcArray
- The source array.srcOffsetShorts
- offset in array unitslengthShorts
- number of array units to transfer
-
clear
void clear()
Clears all bytes of this Memory to zero
-
clear
void clear(long offsetBytes, long lengthBytes)
Clears a portion of this Memory to zero.- Parameters:
offsetBytes
- offset bytes relative to this Memory startlengthBytes
- the length in bytes
-
clearBits
void clearBits(long offsetBytes, byte bitMask)
Clears the bits defined by the bitMask- Parameters:
offsetBytes
- offset bytes relative to this Memory start.bitMask
- the bits set to one will be cleared
-
fill
void fill(byte value)
Fills all bytes of this Memory region to the given byte value.- Parameters:
value
- the given byte value
-
fill
void fill(long offsetBytes, long lengthBytes, byte value)
Fills a portion of this Memory region to the given byte value.- Parameters:
offsetBytes
- offset bytes relative to this Memory startlengthBytes
- the length in bytesvalue
- the given byte value
-
setBits
void setBits(long offsetBytes, byte bitMask)
Sets the bits defined by the bitMask- Parameters:
offsetBytes
- offset bytes relative to this Memory startbitMask
- the bits set to one will be set
-
-