Package org.apache.datasketches.memory

Interface WritableMemory

All Superinterfaces:

AutoCloseable, Memory, Resource

public interface WritableMemory
extends Memory

Defines the writable API for offset access to a resource.

Author:

Lee Rhodes

Field Summary

Fields inherited from interface org.apache.datasketches.memory.Resource

defaultMemReqSvr

Method Summary

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, long alignmentBytes, ByteOrder byteOrder, MemoryRequestServer memReqSvr)	Allocates and provides access to capacityBytes directly in native (off-heap) memory.
static WritableMemory	allocateDirect(long capacityBytes, long alignmentBytes, ResourceScope scope, ByteOrder byteOrder, MemoryRequestServer memReqSvr)	Allocates and provides access to capacityBytes directly in native (off-heap) memory with a ResourceScope.
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 zero
void	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 bitMask
void	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.
byte[]	getArray()	Returns a copy of the primitive backing array as a byte array.
void	putBoolean(long offsetBytes, boolean value)	Puts the boolean value at the given offset
void	putByte(long offsetBytes, byte value)	Puts the byte value at the given offset
void	putByteArray(long offsetBytes, byte[] srcArray, int srcOffsetBytes, int lengthBytes)	Puts the byte array at the given offset
void	putChar(long offsetBytes, char value)	Puts the char value at the given offset
void	putCharArray(long offsetBytes, char[] srcArray, int srcOffsetChars, int lengthChars)	Puts the char array at the given offset
void	putDouble(long offsetBytes, double value)	Puts the double value at the given offset
void	putDoubleArray(long offsetBytes, double[] srcArray, int srcOffsetDoubles, int lengthDoubles)	Puts the double array at the given offset
void	putFloat(long offsetBytes, float value)	Puts the float value at the given offset
void	putFloatArray(long offsetBytes, float[] srcArray, int srcOffsetFloats, int lengthFloats)	Puts the float array at the given offset
void	putInt(long offsetBytes, int value)	Puts the int value at the given offset
void	putIntArray(long offsetBytes, int[] srcArray, int srcOffsetInts, int lengthInts)	Puts the int array at the given offset
void	putLong(long offsetBytes, long value)	Puts the long value at the given offset
void	putLongArray(long offsetBytes, long[] srcArray, int srcOffsetLongs, int lengthLongs)	Puts the long array at the given offset
void	putShort(long offsetBytes, short value)	Puts the short value at the given offset
void	putShortArray(long offsetBytes, short[] srcArray, int srcOffsetShorts, int lengthShorts)	Puts the short array at the given offset
void	setBits(long offsetBytes, byte bitMask)	Sets the bits defined by the bitMask
static WritableMemory	writableMap(File file)	Maps the entire given file into native-ordered WritableMemory for write operations Calling this method is equivalent to calling writableMap(file, 0, file.length(), scope, 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.
static WritableMemory	writableMap(File file, long fileOffsetBytes, long capacityBytes, ResourceScope scope, ByteOrder byteOrder)	Maps the specified portion of the given file into Memory for write operations with a ResourceScope.
default WritableMemory	writableRegion(long offsetBytes, 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(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)	Provides a view of the given ByteBuffer for write operations.
static WritableMemory	writableWrap(ByteBuffer byteBuffer, ByteOrder byteOrder, MemoryRequestServer memReqSvr)	Provides a view of the given ByteBuffer for write operations.

Methods inherited from interface org.apache.datasketches.memory.Memory

asBuffer, asBuffer, compareTo, copyTo, getBoolean, getByte, getByteArray, getChar, getCharArray, getDouble, getDoubleArray, getFloat, getFloatArray, getInt, getIntArray, getLong, getLongArray, getShort, getShortArray, region, region, writeToByteStream

Methods inherited from interface org.apache.datasketches.memory.Resource

asByteBufferView, close, equalTo, equalTo, force, getCapacity, getMemoryRequestServer, getOwnerThread, getRelativeOffset, getTypeByteOrder, hasByteBuffer, hasMemoryRequestServer, isAlive, isBuffer, isByteOrderCompatible, isCloseable, isDirect, isDuplicate, isHeap, isLoaded, isMapped, isMemory, isReadOnly, isRegion, isSameResource, load, mismatch, nativeOverlap, scope, setMemoryRequestServer, toByteBuffer, toMemorySegment, toString, toString, unload, xxHash64, xxHash64

Method Details

writableWrap

static WritableMemory writableWrap(ByteBuffer byteBuffer)

Provides a view of the given ByteBuffer for write operations. The view is of the entire ByteBuffer independent of position and limit. The returned WritableMemory will assume the ByteOrder of the given ByteBuffer.

Parameters:

byteBuffer - the given ByteBuffer. It must be non-null and writable.

Returns:

a new WritableMemory for write operations on the given ByteBuffer.

writableWrap

static WritableMemory writableWrap(ByteBuffer byteBuffer,
 ByteOrder byteOrder,
 MemoryRequestServer memReqSvr)

Provides a view of the given ByteBuffer for write operations. The view is of the entire ByteBuffer independent of position and limit. The returned WritableMemory will assume the given ByteOrder, independent of the ByteOrder of the given ByteBuffer. This does not affect the ByteOrder of data already in the ByteBuffer.

Parameters:

byteBuffer - the given ByteBuffer. It must be non-null 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.

Throws:

IllegalArgumentException - if ByteBuffer is not writable.

writableMap

static WritableMemory writableMap(File file)
                           throws IOException

Maps the entire given file into native-ordered WritableMemory for write operations Calling this method is equivalent to calling writableMap(file, 0, file.length(), scope, ByteOrder.nativeOrder()).

Parameters:

file - the given file to map. It must be non-null and writable.

Returns:

a file-mapped WritableMemory

Throws:

IllegalArgumentException - if file is not readable or not writable.

IOException - if the specified path does not point to an existing file, or if some other I/O error occurs.

SecurityException - If a security manager is installed and it denies an unspecified permission required by the implementation.

writableMap

static WritableMemory writableMap(File file,
 long fileOffsetBytes,
 long capacityBytes,
 ByteOrder byteOrder)
                           throws IOException

Maps the specified portion of the given file into Memory for write operations.

Parameters:

file - the given file to map. It must be non-null and writable.

fileOffsetBytes - the position in the given file in bytes. It must not be negative.

capacityBytes - the size of the mapped Memory.

byteOrder - the given ByteOrder. It must be non-null.

Returns:

a file-mapped WritableMemory.

Throws:

IllegalArgumentException - if file is not readable or not writable.

IOException - if the specified path does not point to an existing file, or if some other I/O error occurs.

SecurityException - If a security manager is installed and it denies an unspecified permission required by the implementation.

writableMap

static WritableMemory writableMap(File file,
 long fileOffsetBytes,
 long capacityBytes,
 ResourceScope scope,
 ByteOrder byteOrder)
                           throws IOException

Maps the specified portion of the given file into Memory for write operations with a ResourceScope.

Parameters:

file - the given file to map. It must be non-null with a non-negative length and writable.

fileOffsetBytes - the position in the given file in bytes. It must not be negative.

capacityBytes - the size of the mapped Memory. It must be ≥ 0.

scope - the given ResourceScope.

byteOrder - the byte order to be used. It must be non-null.

Returns:

mapped WritableMemory.

Throws:

IllegalArgumentException - -- if file is not readable or writable.

IllegalArgumentException - -- if file is not writable.

IOException - - if the specified path does not point to an existing file, or if some other I/O error occurs.

SecurityException - - If a security manager is installed and it denies an unspecified permission required by the implementation.

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.

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.

Returns:

WritableMemory for this off-heap, native resource.

allocateDirect

static WritableMemory allocateDirect(long capacityBytes,
 long alignmentBytes,
 ByteOrder byteOrder,
 MemoryRequestServer memReqSvr)

Allocates and provides access to capacityBytes directly in native (off-heap) memory. The allocated memory will be aligned to the given alignmentBytes.

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.

alignmentBytes - requested segment alignment. Typically 1, 2, 4 or 8.

byteOrder - the given ByteOrder. 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:

a WritableMemory for this off-heap resource.

allocateDirect

static WritableMemory allocateDirect(long capacityBytes,
 long alignmentBytes,
 ResourceScope scope,
 ByteOrder byteOrder,
 MemoryRequestServer memReqSvr)

Allocates and provides access to capacityBytes directly in native (off-heap) memory with a ResourceScope. The allocated memory will be aligned to the given alignmentBytes.

NOTICE: It is the responsibility of the using application to call close() when done.

Parameters:

capacityBytes - the size of the desired memory in bytes.

alignmentBytes - requested segment alignment. Typically 1, 2, 4 or 8.

scope - the given ResourceScope.

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 of direct memory to request more memory.

Returns:

WritableMemory

writableRegion

default WritableMemory writableRegion(long offsetBytes,
 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:

offsetBytes - the starting offset with respect to this object.

capacityBytes - the capacity of the returned object in bytes.

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.

capacityBytes - the capacity of the returned object in bytes.

byteOrder - the given ByteOrder. 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 ByteOrder. It must be non-null.

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.

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.

byteOrder - the given ByteOrder. 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.

byteOrder - the given ByteOrder. 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.

lengthBytes - the number of bytes to include from the given array.

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.

lengthBytes - the number of bytes to include from the given array.

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(char[] 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(short[] 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(int[] 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(long[] 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(float[] 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(double[] 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.

putBoolean

void putBoolean(long offsetBytes,
 boolean value)

Puts the boolean value at the given offset

Parameters:

offsetBytes - offset bytes relative to this WritableMemory start

value - the value to put

putByte

void putByte(long offsetBytes,
 byte value)

Puts the byte value at the given offset

Parameters:

offsetBytes - offset bytes relative to this WritableMemory start

value - 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 start

srcArray - The source array.

srcOffsetBytes - offset in array units

lengthBytes - 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 start

value - 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 start

srcArray - The source array.

srcOffsetChars - offset in array units

lengthChars - number of array units to transfer

putDouble

void putDouble(long offsetBytes,
 double value)

Puts the double value at the given offset

Parameters:

offsetBytes - offset bytes relative to this WritableMemory start

value - 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 start

srcArray - The source array.

srcOffsetDoubles - offset in array units

lengthDoubles - 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 start

value - 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 start

srcArray - The source array.

srcOffsetFloats - offset in array units

lengthFloats - 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 start

value - 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 start

srcArray - The source array.

srcOffsetInts - offset in array units

lengthInts - 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 start

value - 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 start

srcArray - The source array.

srcOffsetLongs - offset in array units

lengthLongs - 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 start

value - 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 start

srcArray - The source array.

srcOffsetShorts - offset in array units

lengthShorts - 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 start

lengthBytes - 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 start

lengthBytes - the length in bytes

value - 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 start

bitMask - the bits set to one will be set

getArray

byte[] getArray()

Returns a copy of the primitive backing array as a byte array.

Returns:

a copy of the primitive backing array as a byte array.