com.yahoo.memory

Class WritableBuffer

java.lang.Object

com.yahoo.memory.BaseBuffer

com.yahoo.memory.Buffer

com.yahoo.memory.WritableBuffer

public abstract class WritableBuffer
extends Buffer

Provides read and write, positional primitive and primitive array access to any of the four resources mentioned at the package level.

Author:

Roman Leventov, Lee Rhodes

Method Summary

Modifier and Type	Method and Description
abstract WritableMemory	asWritableMemory() Convert this WritableBuffer to a WritableMemory.
void	checkValidAndBounds(long offsetBytes, long lengthBytes) Checks that the specified range of bytes is within bounds of this object, throws IllegalArgumentException if it's not: i.
abstract void	clear() Clears all bytes of this Buffer from position to end to zero.
boolean	equals(Object that) Returns true if the given object is an instance of this class and has equal data contents.
boolean	equalTo(long thisOffsetBytes, Object 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.
abstract void	fill(byte value) Fills this Buffer from position to end with the given byte value.
abstract Object	getArray() Returns the primitive backing array, otherwise null.
ByteBuffer	getByteBuffer() Gets the backing ByteBuffer if it exists, otherwise returns null.
ByteOrder	getByteOrder() Gets the current ByteOrder.
long	getCapacity() Gets the capacity of this object in bytes
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.
static long	getCurrentDirectMemoryAllocated() Gets the current size of active direct memory allocated.
static long	getCurrentDirectMemoryAllocations() Gets the current number of active direct memory allocations.
static long	getCurrentDirectMemoryMapAllocated() Gets the current size of active direct memory map allocated.
static long	getCurrentDirectMemoryMapAllocations() Gets the current number of active direct memory map allocations.
MemoryRequestServer	getMemoryRequestServer() For Direct Memory only.
long	getRegionOffset() Returns the offset of address zero of this object relative to the address zero of the backing resource but not including the size of any Java object header.
long	getRegionOffset(long offsetBytes) Returns the offset of address zero of this object relative to the address zero of the backing resource plus the given offsetBytes but not including the size of any Java object header.
boolean	hasArray() Returns true if this object is backed by an on-heap primitive array
boolean	hasByteBuffer() Returns true if this Memory is backed by a ByteBuffer.
int	hashCode() Returns the hashCode of this object.
boolean	isDirect() Returns true if the backing resource is direct (off-heap) memory.
boolean	isNativeOrder() Returns true if the current byte order is native order.
boolean	isReadOnly() Returns true if this object or the backing resource is read-only.
boolean	isSameResource(Object that) Returns true if the backing resource of this is identical with the backing resource of that.
boolean	isValid() Returns true if this object is valid and has not been closed.
abstract void	putBoolean(boolean value) Puts the boolean value at the current position.
abstract void	putBoolean(long offsetBytes, boolean value) Puts the boolean value at the given offset.
abstract void	putBooleanArray(boolean[] srcArray, int srcOffsetBooleans, int lengthBooleans) Puts the boolean array at the current position.
abstract void	putByte(byte value) Puts the byte value at the current position.
abstract void	putByte(long offsetBytes, byte value) Puts the byte value at the given offset.
abstract void	putByteArray(byte[] srcArray, int srcOffsetBytes, int lengthBytes) Puts the byte array at the current position.
abstract void	putChar(char value) Puts the char value at the current position.
abstract void	putChar(long offsetBytes, char value) Puts the char value at the given offset.
abstract void	putCharArray(char[] srcArray, int srcOffsetChars, int lengthChars) Puts the char array at the current position.
abstract void	putDouble(double value) Puts the double value at the current position.
abstract void	putDouble(long offsetBytes, double value) Puts the double value at the given offset.
abstract void	putDoubleArray(double[] srcArray, int srcOffsetDoubles, int lengthDoubles) Puts the double array at the current position.
abstract void	putFloat(float value) Puts the float value at the current position.
abstract void	putFloat(long offsetBytes, float value) Puts the float value at the given offset.
abstract void	putFloatArray(float[] srcArray, int srcOffsetFloats, int lengthFloats) Puts the float array at the current position.
abstract void	putInt(int value) Puts the int value at the current position.
abstract void	putInt(long offsetBytes, int value) Puts the int value at the given offset.
abstract void	putIntArray(int[] srcArray, int srcOffsetInts, int lengthInts) Puts the int array at the current position.
abstract void	putLong(long value) Puts the long value at the current position.
abstract void	putLong(long offsetBytes, long value) Puts the long value at the given offset.
abstract void	putLongArray(long[] srcArray, int srcOffsetLongs, int lengthLongs) Puts the long array at the current position.
abstract void	putShort(long offsetBytes, short value) Puts the short value at the given offset.
abstract void	putShort(short value) Puts the short value at the current position.
abstract void	putShortArray(short[] srcArray, int srcOffsetShorts, int lengthShorts) Puts the short array at the current position.
String	toHexString(String header, long offsetBytes, int lengthBytes) Returns a formatted hex string of a range of this object.
static WritableBuffer	wrap(ByteBuffer byteBuf) Accesses the given ByteBuffer for write operations.
static WritableBuffer	wrap(ByteBuffer byteBuf, ByteOrder byteOrder) Accesses the given ByteBuffer for write operations.
abstract WritableBuffer	writableDuplicate() Returns a duplicate writable view of this Buffer with the same but independent values of start, position and end.
abstract WritableBuffer	writableDuplicate(ByteOrder byteOrder) Returns a duplicate writable view of this Buffer with the same but independent values of start, position and end, but with the specified byteOrder.
abstract WritableBuffer	writableRegion() A writable region is a writable view of this object.
abstract WritableBuffer	writableRegion(long offsetBytes, long capacityBytes, ByteOrder byteOrder) A writable region is a writable view of this object.
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.

Methods inherited from class com.yahoo.memory.Buffer

asMemory, compareTo, duplicate, duplicate, getBoolean, getBoolean, getBooleanArray, getByte, getByte, getByteArray, getChar, getChar, getCharArray, getDouble, getDouble, getDoubleArray, getFloat, getFloat, getFloatArray, getInt, getInt, getIntArray, getLong, getLong, getLongArray, getShort, getShort, getShortArray, region, region

Methods inherited from class com.yahoo.memory.BaseBuffer

getEnd, getPosition, getRemaining, getStart, hasRemaining, incrementAndCheckPosition, incrementPosition, resetPosition, setAndCheckPosition, setAndCheckStartPositionEnd, setPosition, setStartPositionEnd

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

wrap

public static WritableBuffer wrap(ByteBuffer byteBuf)

Accesses the given ByteBuffer for write operations. The returned WritableBuffer object has the same byte order, as the given ByteBuffer, unless the capacity of the given ByteBuffer is zero, then byte order of the returned WritableBuffer object, as well as backing storage and read-only status are unspecified.

Parameters:

byteBuf - the given ByteBuffer, must not be null.

Returns:

a new WritableBuffer for write operations on the given ByteBuffer.

wrap

public static WritableBuffer wrap(ByteBuffer byteBuf,
                                  ByteOrder byteOrder)

Accesses the given ByteBuffer for write operations. The returned WritableBuffer object has the given byte order, ignoring the byte order of the given ByteBuffer. If the capacity of the given ByteBuffer is zero the byte order of the returned WritableBuffer object (as well as backing storage) is unspecified.

Parameters:

byteBuf - the given ByteBuffer, must not be null

byteOrder - the byte order to be used, which may be independent of the byte order state of the given ByteBuffer

Returns:

a new WritableBuffer for write operations on the given ByteBuffer.

writableDuplicate

public abstract WritableBuffer writableDuplicate()

Returns a duplicate writable view of this Buffer with the same but independent values of start, position and end.

• Returned object's origin = this object's origin
• Returned object's start = this object's start
• Returned object's position = this object's position
• Returned object's end = this object's end
• Returned object's capacity = this object' capacityBytes
• Returned object's start, position and end are mutable and independent of this object's start, position and end

If this object's capacity is zero, the returned object is effectively immutable and the backing storage and byte order are unspecified.

Returns:

a duplicate writable view of this Buffer with the same but independent values of start, position and end.

writableDuplicate

public abstract WritableBuffer writableDuplicate(ByteOrder byteOrder)

Returns a duplicate writable view of this Buffer with the same but independent values of start, position and end, but with the specified byteOrder.

• Returned object's origin = this object's origin
• Returned object's start = this object's start
• Returned object's position = this object's position
• Returned object's end = this object's end
• Returned object's capacity = this object' capacityBytes
• Returned object's start, position and end are mutable and independent of this object's start, position and end

If this object's capacity is zero, the returned object is effectively immutable and the backing storage and byte order are unspecified.

Parameters:

byteOrder - the given ByteOrder.

Returns:

a duplicate writable view of this Buffer with the same but independent values of start, position and end.

writableRegion

public abstract WritableBuffer writableRegion()

A writable region is a writable view of this object.

• Returned object's origin = this object's position
• Returned object's start = 0
• Returned object's position = 0
• Returned object's end = this object's (end - position)
• Returned object's capacity = this object's (end - position)
• Returned object's start, position and end are mutable and independent of this object's start, position and end

If this object's capacity is zero, the returned object is effectively immutable and the backing storage and byte order are unspecified.

Returns:

a new WritableBuffer representing the defined writable region.

writableRegion

public abstract WritableBuffer writableRegion(long offsetBytes,
                                              long capacityBytes,
                                              ByteOrder byteOrder)

A writable region is a writable view of this object.

• Returned object's origin = this objects' origin + offsetBytes
• Returned object's start = 0
• Returned object's position = 0
• Returned object's end = capacityBytes
• Returned object's capacity = capacityBytes
• Returned object's start, position and end are mutable and independent of this object's start, position and end
• Returned object's byte order = byteOrder

If this object's capacity is zero, the returned object is effectively immutable and the backing storage and byte order are unspecified.

Note: asWritableMemory() and asMemory() will return the originating Memory byte order.

Parameters:

offsetBytes - the starting offset with respect to the origin of this WritableBuffer

capacityBytes - the capacity of the returned region in bytes

byteOrder - the given byte order

Returns:

a new WritableBuffer representing the defined writable region with the given offsetBytes, capacityBytes and byte order.

asWritableMemory

public abstract WritableMemory asWritableMemory()

Convert this WritableBuffer to a WritableMemory. If this object's capacity is zero, the returned object is effectively immutable and the backing storage and byte order are unspecified.

Returns:

WritableMemory

putBoolean

public abstract void putBoolean(boolean value)

Puts the boolean value at the current position. Increments the position by 1.

Parameters:

value - the value to put

putBoolean

public abstract void putBoolean(long offsetBytes,
                                boolean value)

Puts the boolean value at the given offset. This does not change the position.

Parameters:

offsetBytes - offset bytes relative to this WritableMemory start.

value - the value to put

putBooleanArray

public abstract void putBooleanArray(boolean[] srcArray,
                                     int srcOffsetBooleans,
                                     int lengthBooleans)

Puts the boolean array at the current position. Increments the position by lengthBooleans - srcOffsetBooleans.

Parameters:

srcArray - The source array.

srcOffsetBooleans - offset in array units

lengthBooleans - number of array units to transfer

putByte

public abstract void putByte(byte value)

Puts the byte value at the current position. Increments the position by Byte.BYTES.

Parameters:

value - the value to put

putByte

public abstract void putByte(long offsetBytes,
                             byte value)

Puts the byte value at the given offset. This does not change the position.

Parameters:

offsetBytes - offset bytes relative to this WritableMemory start

value - the value to put

putByteArray

public abstract void putByteArray(byte[] srcArray,
                                  int srcOffsetBytes,
                                  int lengthBytes)

Puts the byte array at the current position. Increments the position by Byte.BYTES * (lengthBytes - srcOffsetBytes).

Parameters:

srcArray - The source array.

srcOffsetBytes - offset in array units

lengthBytes - number of array units to transfer

putChar

public abstract void putChar(char value)

Puts the char value at the current position. Increments the position by Character.BYTES.

Parameters:

value - the value to put

putChar

public abstract void putChar(long offsetBytes,
                             char value)

Puts the char value at the given offset. This does not change the position.

Parameters:

offsetBytes - offset bytes relative to this WritableMemory start

value - the value to put

putCharArray

public abstract void putCharArray(char[] srcArray,
                                  int srcOffsetChars,
                                  int lengthChars)

Puts the char array at the current position. Increments the position by Character.BYTES * (lengthChars - srcOffsetChars).

Parameters:

srcArray - The source array.

srcOffsetChars - offset in array units

lengthChars - number of array units to transfer

putDouble

public abstract void putDouble(double value)

Puts the double value at the current position. Increments the position by Double.BYTES.

Parameters:

value - the value to put

putDouble

public abstract void putDouble(long offsetBytes,
                               double value)

Puts the double value at the given offset. This does not change the position.

Parameters:

offsetBytes - offset bytes relative to this WritableMemory start

value - the value to put

putDoubleArray

public abstract void putDoubleArray(double[] srcArray,
                                    int srcOffsetDoubles,
                                    int lengthDoubles)

Puts the double array at the current position. Increments the position by Double.BYTES * (lengthDoubles - srcOffsetDoubles).

Parameters:

srcArray - The source array.

srcOffsetDoubles - offset in array units

lengthDoubles - number of array units to transfer

putFloat

public abstract void putFloat(float value)

Puts the float value at the current position. Increments the position by Float.BYTES.

Parameters:

value - the value to put

putFloat

public abstract void putFloat(long offsetBytes,
                              float value)

Puts the float value at the given offset. This does not change the position.

Parameters:

offsetBytes - offset bytes relative to this WritableMemory start

value - the value to put

putFloatArray

public abstract void putFloatArray(float[] srcArray,
                                   int srcOffsetFloats,
                                   int lengthFloats)

Puts the float array at the current position. Increments the position by Float.BYTES * (lengthFloats - srcOffsetFloats).

Parameters:

srcArray - The source array.

srcOffsetFloats - offset in array units

lengthFloats - number of array units to transfer

putInt

public abstract void putInt(int value)

Puts the int value at the current position. Increments the position by Integer.BYTES.

Parameters:

value - the value to put

putInt

public abstract void putInt(long offsetBytes,
                            int value)

Puts the int value at the given offset. This does not change the position.

Parameters:

offsetBytes - offset bytes relative to this WritableMemory start

value - the value to put

putIntArray

public abstract void putIntArray(int[] srcArray,
                                 int srcOffsetInts,
                                 int lengthInts)

Puts the int array at the current position. Increments the position by Integer.BYTES * (lengthInts - srcOffsetInts).

Parameters:

srcArray - The source array.

srcOffsetInts - offset in array units

lengthInts - number of array units to transfer

putLong

public abstract void putLong(long value)

Puts the long value at the current position. Increments the position by Long.BYTES.

Parameters:

value - the value to put

putLong

public abstract void putLong(long offsetBytes,
                             long value)

Puts the long value at the given offset. This does not change the position.

Parameters:

offsetBytes - offset bytes relative to this WritableMemory start

value - the value to put

putLongArray

public abstract void putLongArray(long[] srcArray,
                                  int srcOffsetLongs,
                                  int lengthLongs)

Puts the long array at the current position. Increments the position by Long.BYTES * (lengthLongs - srcOffsetLongs).

Parameters:

srcArray - The source array.

srcOffsetLongs - offset in array units

lengthLongs - number of array units to transfer

putShort

public abstract void putShort(short value)

Puts the short value at the current position. Increments the position by Short.BYTES.

Parameters:

value - the value to put

putShort

public abstract void putShort(long offsetBytes,
                              short value)

Puts the short value at the given offset. This does not change the position.

Parameters:

offsetBytes - offset bytes relative to this WritableMemory start

value - the value to put

putShortArray

public abstract void putShortArray(short[] srcArray,
                                   int srcOffsetShorts,
                                   int lengthShorts)

Puts the short array at the current position. Increments the position by Short.BYTES * (lengthShorts - srcOffsetShorts).

Parameters:

srcArray - The source array.

srcOffsetShorts - offset in array units

lengthShorts - number of array units to transfer

getArray

public abstract Object getArray()

Returns the primitive backing array, otherwise null.

Returns:

the primitive backing array, otherwise null.

clear

public abstract void clear()

Clears all bytes of this Buffer from position to end to zero. The position will be set to end.

fill

public abstract void fill(byte value)

Fills this Buffer from position to end with the given byte value. The position will be set to end.

Parameters:

value - the given byte value

getMemoryRequestServer

public MemoryRequestServer getMemoryRequestServer()

For Direct Memory only. Other types of backing resources will return null. Gets the MemoryRequestServer object used by dynamic off-heap (Direct) memory objects to request additional memory. Set using WritableMemory.allocateDirect(long, MemoryRequestServer). If not explicity set, this returns the DefaultMemoryRequestServer.

Returns:

the MemoryRequestServer object (if direct memory) or null.

equals

public final boolean equals(Object that)

Returns true if the given object is an instance of this class and has equal data contents.

Overrides:

equals in class Object

Parameters:

that - the given object

Returns:

true if the given Object is an instance of this class and has equal data contents.

equalTo

public final boolean equalTo(long thisOffsetBytes,
                             Object 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 eauals.

Parameters:

thisOffsetBytes - the starting offset in bytes for this object.

that - the given 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.

getByteBuffer

public ByteBuffer getByteBuffer()

Gets the backing ByteBuffer if it exists, otherwise returns null.

Returns:

the backing ByteBuffer if it exists, otherwise returns null.

getByteOrder

public final ByteOrder getByteOrder()

Gets the current ByteOrder. This may be different from the ByteOrder of the backing resource.

Returns:

the current ByteOrder.

getCapacity

public final long getCapacity()

Gets the capacity of this object in bytes

Returns:

the capacity of this object in bytes

getCumulativeOffset

public final long getCumulativeOffset()

Gets the cumulative offset in bytes of this object from the backing resource. This offset may also include other offset components such as the native off-heap memory address, DirectByteBuffer split offsets, region offsets, and unsafe arrayBaseOffsets.

Returns:

the cumulative offset in bytes of this object from the backing resource.

getCumulativeOffset

public final long getCumulativeOffset(long offsetBytes)

Gets the cumulative offset in bytes of this object from the backing resource including the given offsetBytes. This offset may also include other offset components such as the native off-heap memory address, DirectByteBuffer split offsets, region offsets, and unsafe arrayBaseOffsets.

Parameters:

offsetBytes - offset to be added to the cumulative offset.

Returns:

the cumulative offset in bytes of this object from the backing resource including the given offsetBytes.

getRegionOffset

public final long getRegionOffset()

Returns the offset of address zero of this object relative to the address zero of the backing resource but not including the size of any Java object header.

Returns:

the offset of address zero of this object relative to the address zero of the backing resource but not including the size of any Java object header.

getRegionOffset

public final long getRegionOffset(long offsetBytes)

Returns the offset of address zero of this object relative to the address zero of the backing resource plus the given offsetBytes but not including the size of any Java object header.

Parameters:

offsetBytes - the given offsetBytes

Returns:

the offset of address zero of this object relative to the address zero of the backing resource plus the given offsetBytes but not including the size of any Java object header.

hasArray

public final boolean hasArray()

Returns true if this object is backed by an on-heap primitive array

Returns:

true if this object is backed by an on-heap primitive array

hashCode

public final int hashCode()

Returns the hashCode of this object.

The hash code of this object depends upon all of its contents. Because of this, it is inadvisable to use these objects as keys in hash maps or similar data structures unless it is known that their contents will not change.

If it is desirable to use these objects in a hash map depending only on object identity, than the IdentityHashMap can be used.

Overrides:

hashCode in class Object

Returns:

the hashCode of this object.

xxHash64

public final 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.

hasByteBuffer

public final boolean hasByteBuffer()

Returns true if this Memory is backed by a ByteBuffer.

Returns:

true if this Memory is backed by a ByteBuffer.

isDirect

public final boolean isDirect()

Returns true if the backing resource is direct (off-heap) memory. This is the case for allocated direct memory, memory mapped files,

Returns:

true if the backing resource is direct (off-heap) memory.

isNativeOrder

public final boolean isNativeOrder()

Returns true if the current byte order is native order.

Returns:

true if the current byte order is native order.

isReadOnly

public final 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.

isSameResource

public final boolean isSameResource(Object that)

Returns true if the backing resource of this is identical with the backing resource of that. The capacities must be the same. If this is a region, the region offset must also be the same.

Parameters:

that - A different non-null object

Returns:

true if the backing resource of this is the same as the backing resource of that.

isValid

public boolean isValid()

Returns true if this object is valid and has not been closed. This is relevant only for direct (off-heap) memory and Mapped Files.

Returns:

true if this object is valid and has not been closed.

checkValidAndBounds

public final void checkValidAndBounds(long offsetBytes,
                                      long lengthBytes)

Checks that the specified range of bytes is within bounds of this object, throws IllegalArgumentException if it's not: i. e. if offsetBytes < 0, or length < 0, or offsetBytes + length > getCapacity().

Parameters:

offsetBytes - the given offset in bytes of this object

lengthBytes - the given length in bytes of this object

getCurrentDirectMemoryAllocations

public static final long getCurrentDirectMemoryAllocations()

Gets the current number of active direct memory allocations.

Returns:

the current number of active direct memory allocations.

getCurrentDirectMemoryAllocated

public static final long getCurrentDirectMemoryAllocated()

Gets the current size of active direct memory allocated.

Returns:

the current size of active direct memory allocated.

getCurrentDirectMemoryMapAllocations

public static final long getCurrentDirectMemoryMapAllocations()

Gets the current number of active direct memory map allocations.

Returns:

the current number of active direct memory map allocations.

getCurrentDirectMemoryMapAllocated

public static final long getCurrentDirectMemoryMapAllocated()

Gets the current size of active direct memory map allocated.

Returns:

the current size of active direct memory map allocated.

toHexString

public final String toHexString(String header,
                                long offsetBytes,
                                int lengthBytes)

Returns a formatted hex string of a range of this object. Used primarily for testing.

Parameters:

header - a descriptive header

offsetBytes - offset bytes relative to this object start

lengthBytes - number of bytes to convert to a hex string

Returns:

a formatted hex string in a human readable array