com.yahoo.memory

Interface Memory

All Known Implementing Classes:

AllocMemory, MemoryMappedFile, MemoryRegion, MemoryRegionR, NativeMemory

public interface Memory

The Memory interface defines get and put methods for all Java primitive and primitive array types to/from a byte offset that is relative to the base address of some object or region of native memory defined by the implementing class. The methods of this interface leverage the capabilities of the sun.misc.Unsafe class.

In contrast to the java.nio.ByteBuffer classes, which were designed for native streaming I/O and include concepts such as position, limit, mark, flip and rewind, this interface specifically bypasses these concepts and instead provides a rich collection of primitive, bit, array and copy methods that access the data directly from a single byte offset.

Author:

Lee Rhodes

Method Summary

Modifier and Type	Method and Description
Object	array() Returns the backing on-heap primitive array if there is one, otherwise returns null
Memory	asReadOnlyMemory() Returns a read-only version of this memory
ByteBuffer	byteBuffer() Returns the backing ByteBuffer if there is one, otherwise returns null
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	copy(long srcOffsetBytes, long dstOffsetBytes, long lengthBytes) Copies bytes from a source region of this Memory to a destination region of this Memory.
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.
long	getAddress(long offsetBytes) Returns the start address of this Memory relative to its parent plus the offset in bytes.
int	getAndAddInt(long offsetBytes, int delta) Atomically adds the given value to the integer located at offsetBytes.
long	getAndAddLong(long offsetBytes, long delta) Atomically adds the given value to the long located at offsetBytes.
int	getAndSetInt(long offsetBytes, int newValue) Atomically exchanges the given value with the current value located at offsetBytes.
long	getAndSetLong(long offsetBytes, long newValue) Atomically exchanges the given value with the current value located at offsetBytes.
boolean	getBoolean(long offsetBytes) Gets the boolean value at the given offset
void	getBooleanArray(long offsetBytes, boolean[] dstArray, int dstOffset, int length) Gets the boolean array at the given offset
byte	getByte(long offsetBytes) Gets the byte at the given offset
void	getByteArray(long offsetBytes, byte[] dstArray, int dstOffset, int length) Gets the byte array at the given offset
long	getCapacity() Gets the capacity of this Memory in bytes
char	getChar(long offsetBytes) Gets the char at the given offset
void	getCharArray(long offsetBytes, char[] dstArray, int dstOffset, int length) Gets the char array at the given offset
long	getCumulativeOffset(long offsetBytes) Returns the cumulative offset in bytes of this Memory from the base Memory including the given offset.
double	getDouble(long offsetBytes) Gets the double at the given offset
void	getDoubleArray(long offsetBytes, double[] dstArray, int dstOffset, int length) Gets the double array at the given offset
float	getFloat(long offsetBytes) Gets the float at the given offset
void	getFloatArray(long offsetBytes, float[] dstArray, int dstOffset, int length) Gets the float array at the given offset
int	getInt(long offsetBytes) Gets the int at the given offset
void	getIntArray(long offsetBytes, int[] dstArray, int dstOffset, int length) Gets the int array at the given offset
long	getLong(long offsetBytes) Gets the long at the given offset
void	getLongArray(long offsetBytes, long[] dstArray, int dstOffset, int length) Gets the long array at the given offset
MemoryRequest	getMemoryRequest() Returns a MemoryRequest or null
NativeMemory	getNativeMemory() Returns the root NativeMemory, which could also be the derived MemoryMappedFile or AllocMemory.
Object	getParent() Gets the parent Memory or backing array.
short	getShort(long offsetBytes) Gets the short at the given offset
void	getShortArray(long offsetBytes, short[] dstArray, int dstOffset, int length) Gets the short array at the given offset
boolean	hasArray() Returns true if this Memory is backed by an on-heap primitive array
boolean	hasByteBuffer() Returns true if this Memory is backed by a ByteBuffer
boolean	isAllBitsClear(long offsetBytes, byte bitMask) Returns true if all bits defined by the bitMask are clear
boolean	isAllBitsSet(long offsetBytes, byte bitMask) Returns true if all bits defined by the bitMask are set
boolean	isAllocated() Returns true if this Memory has a capacity greater than zero
boolean	isAnyBitsClear(long offsetBytes, byte bitMask) Returns true if any bits defined by the bitMask are clear
boolean	isAnyBitsSet(long offsetBytes, byte bitMask) Returns true if any bits defined by the bitMask are set
boolean	isDirect() Returns true if the backing memory is direct (off-heap) memory.
boolean	isReadOnly() Returns true if this Memory is read only
void	putBoolean(long offsetBytes, boolean value) Puts the boolean value at the given offset
void	putBooleanArray(long offsetBytes, boolean[] srcArray, int srcOffset, int length) Puts the boolean array 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 srcOffset, int length) 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 srcOffset, int length) 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 srcOffset, int length) 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 srcOffset, int length) 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 srcOffset, int length) 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 srcOffset, int length) 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 srcOffset, int length) Puts the short array at the given offset
void	setBits(long offsetBytes, byte bitMask) Sets the bits defined by the bitMask
void	setMemoryRequest(MemoryRequest memReq) Sets a MemoryRequest
String	toHexString(String header, long offsetBytes, int lengthBytes) Returns a formatted hex string of an area of this Memory.

Method Detail

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

copy

void copy(long srcOffsetBytes,
          long dstOffsetBytes,
          long lengthBytes)

Copies bytes from a source region of this Memory to a destination region of this Memory. These regions may not overlap. This will be checked if asserts are enabled in the JVM.

Parameters:

srcOffsetBytes - the source offset

dstOffsetBytes - the destintaion offset

lengthBytes - the number of bytes to copy

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

getAndAddInt

int getAndAddInt(long offsetBytes,
                 int delta)

Atomically adds the given value to the integer located at offsetBytes.

Parameters:

offsetBytes - offset bytes relative to this Memory start

delta - the amount to add

Returns:

the modified value

getAndAddLong

long getAndAddLong(long offsetBytes,
                   long delta)

Atomically adds the given value to the long located at offsetBytes.

Parameters:

offsetBytes - offset bytes relative to this Memory start

delta - the amount to add

Returns:

the modified value

getAndSetInt

int getAndSetInt(long offsetBytes,
                 int newValue)

Atomically exchanges the given value with the current value located at offsetBytes.

Parameters:

offsetBytes - offset bytes relative to this Memory start

newValue - new value

Returns:

the previous value

getAndSetLong

long getAndSetLong(long offsetBytes,
                   long newValue)

Atomically exchanges the given value with the current value located at offsetBytes.

Parameters:

offsetBytes - offset bytes relative to this Memory start

newValue - new value

Returns:

the previous value

getBoolean

boolean getBoolean(long offsetBytes)

Gets the boolean value at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

Returns:

the boolean at the given offset

getBooleanArray

void getBooleanArray(long offsetBytes,
                     boolean[] dstArray,
                     int dstOffset,
                     int length)

Gets the boolean array at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

dstArray - The destination array.

dstOffset - offset in array units

length - number of array units to transfer The size of this array determines the bytes transferred.

getByte

byte getByte(long offsetBytes)

Gets the byte at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

Returns:

the byte at the given offset

getByteArray

void getByteArray(long offsetBytes,
                  byte[] dstArray,
                  int dstOffset,
                  int length)

Gets the byte array at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

dstArray - The destination array.

dstOffset - offset in array units

length - number of array units to transfer The size of this array determines the bytes transferred.

getChar

char getChar(long offsetBytes)

Gets the char at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

Returns:

the char at the given offset

getCharArray

void getCharArray(long offsetBytes,
                  char[] dstArray,
                  int dstOffset,
                  int length)

Gets the char array at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

dstArray - The destination array.

dstOffset - offset in array units

length - number of array units to transfer The size of this array determines the bytes transferred.

getDouble

double getDouble(long offsetBytes)

Gets the double at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

Returns:

the double at the given offset

getDoubleArray

void getDoubleArray(long offsetBytes,
                    double[] dstArray,
                    int dstOffset,
                    int length)

Gets the double array at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

dstArray - The destination array.

dstOffset - offset in array units

length - number of array units to transfer The size of this array determines the bytes transferred.

getFloat

float getFloat(long offsetBytes)

Gets the float at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

Returns:

the float at the given offset

getFloatArray

void getFloatArray(long offsetBytes,
                   float[] dstArray,
                   int dstOffset,
                   int length)

Gets the float array at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

dstArray - The destination array.

dstOffset - offset in array units

length - number of array units to transfer The size of this array determines the bytes transferred.

getInt

int getInt(long offsetBytes)

Gets the int at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

Returns:

the int at the given offset

getIntArray

void getIntArray(long offsetBytes,
                 int[] dstArray,
                 int dstOffset,
                 int length)

Gets the int array at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

dstArray - The destination array.

dstOffset - offset in array units

length - number of array units to transfer The size of this array determines the bytes transferred.

getLong

long getLong(long offsetBytes)

Gets the long at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

Returns:

the long at the given offset

getLongArray

void getLongArray(long offsetBytes,
                  long[] dstArray,
                  int dstOffset,
                  int length)

Gets the long array at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

dstArray - The destination array.

dstOffset - offset in array units

length - number of array units to transfer The size of this array determines the bytes transferred.

getShort

short getShort(long offsetBytes)

Gets the short at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

Returns:

the short at the given offset

getShortArray

void getShortArray(long offsetBytes,
                   short[] dstArray,
                   int dstOffset,
                   int length)

Gets the short array at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

dstArray - The destination array.

dstOffset - offset in array units

length - number of array units to transfer The size of this array determines the bytes transferred.

isAllBitsClear

boolean isAllBitsClear(long offsetBytes,
                       byte bitMask)

Returns true if all bits defined by the bitMask are clear

Parameters:

offsetBytes - offset bytes relative to this Memory start

bitMask - bits set to one will be checked

Returns:

true if all bits defined by the bitMask are clear

isAllBitsSet

boolean isAllBitsSet(long offsetBytes,
                     byte bitMask)

Returns true if all bits defined by the bitMask are set

Parameters:

offsetBytes - offset bytes relative to this Memory start

bitMask - bits set to one will be checked

Returns:

true if all bits defined by the bitMask are set

isAnyBitsClear

boolean isAnyBitsClear(long offsetBytes,
                       byte bitMask)

Returns true if any bits defined by the bitMask are clear

Parameters:

offsetBytes - offset bytes relative to this Memory start

bitMask - bits set to one will be checked

Returns:

true if any bits defined by the bitMask are clear

isAnyBitsSet

boolean isAnyBitsSet(long offsetBytes,
                     byte bitMask)

Returns true if any bits defined by the bitMask are set

Parameters:

offsetBytes - offset bytes relative to this Memory start

bitMask - bits set to one will be checked

Returns:

true if any bits defined by the bitMask are set

putBoolean

void putBoolean(long offsetBytes,
                boolean value)

Puts the boolean value at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

value - the value to put

putBooleanArray

void putBooleanArray(long offsetBytes,
                     boolean[] srcArray,
                     int srcOffset,
                     int length)

Puts the boolean array at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

srcArray - The source array.

srcOffset - offset in array units

length - number of array units to transfer The size of this array determines the bytes transferred.

putByte

void putByte(long offsetBytes,
             byte value)

Puts the byte value at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

value - the value to put

putByteArray

void putByteArray(long offsetBytes,
                  byte[] srcArray,
                  int srcOffset,
                  int length)

Puts the byte array at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

srcArray - The source array.

srcOffset - offset in array units

length - number of array units to transfer The size of this array determines the bytes transferred.

putChar

void putChar(long offsetBytes,
             char value)

Puts the char value at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

value - the value to put

putCharArray

void putCharArray(long offsetBytes,
                  char[] srcArray,
                  int srcOffset,
                  int length)

Puts the char array at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

srcArray - The source array.

srcOffset - offset in array units

length - number of array units to transfer The size of this array determines the bytes transferred.

putDouble

void putDouble(long offsetBytes,
               double value)

Puts the double value at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

value - the value to put

putDoubleArray

void putDoubleArray(long offsetBytes,
                    double[] srcArray,
                    int srcOffset,
                    int length)

Puts the double array at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

srcArray - The source array.

srcOffset - offset in array units

length - number of array units to transfer The size of this array determines the bytes transferred.

putFloat

void putFloat(long offsetBytes,
              float value)

Puts the float value at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

value - the value to put

putFloatArray

void putFloatArray(long offsetBytes,
                   float[] srcArray,
                   int srcOffset,
                   int length)

Puts the float array at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

srcArray - The source array.

srcOffset - offset in array units

length - number of array units to transfer The size of this array determines the bytes transferred.

putInt

void putInt(long offsetBytes,
            int value)

Puts the int value at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

value - the value to put

putIntArray

void putIntArray(long offsetBytes,
                 int[] srcArray,
                 int srcOffset,
                 int length)

Puts the int array at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

srcArray - The source array.

srcOffset - offset in array units

length - number of array units to transfer The size of this array determines the bytes transferred.

putLong

void putLong(long offsetBytes,
             long value)

Puts the long value at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

value - the value to put

putLongArray

void putLongArray(long offsetBytes,
                  long[] srcArray,
                  int srcOffset,
                  int length)

Puts the long array at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

srcArray - The source array.

srcOffset - offset in array units

length - number of array units to transfer The size of this array determines the bytes transferred.

putShort

void putShort(long offsetBytes,
              short value)

Puts the short value at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

value - the value to put

putShortArray

void putShortArray(long offsetBytes,
                   short[] srcArray,
                   int srcOffset,
                   int length)

Puts the short array at the given offset

Parameters:

offsetBytes - offset bytes relative to this Memory start

srcArray - The source array.

srcOffset - offset in array units

length - number of array units to transfer The size of this array determines the bytes transferred.

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

array

Object array()

Returns the backing on-heap primitive array if there is one, otherwise returns null

Returns:

the backing on-heap primitive array if there is one, otherwise returns null

asReadOnlyMemory

Memory asReadOnlyMemory()

Returns a read-only version of this memory

Returns:

a read-only version of this memory

byteBuffer

ByteBuffer byteBuffer()

Returns the backing ByteBuffer if there is one, otherwise returns null

Returns:

the backing ByteBuffer if there is one, otherwise returns null

getAddress

long getAddress(long offsetBytes)

Returns the start address of this Memory relative to its parent plus the offset in bytes.

Note that the precise definition of the returned address is slightly different for NativeMemory.getAddress(long) as it is the root of the Memory hierarchy and has no parent.

Parameters:

offsetBytes - the given offset in bytes from the start address of this Memory relative to its parent.

Returns:

the start address of this Memory relative to its parent plus the offset in bytes.

See Also:

NativeMemory.getAddress(long)

getCapacity

long getCapacity()

Gets the capacity of this Memory in bytes

Returns:

the capacity of this Memory in bytes

getCumulativeOffset

long getCumulativeOffset(long offsetBytes)

Returns the cumulative offset in bytes of this Memory from the base Memory including the given offset. If this Memory is derived from Direct memory it will include the raw native address. If this Memory is derived from a byte or long array it will include the ARRAY_<TYPE>_BASE_OFFSET.

Parameters:

offsetBytes - the given offset in bytes

Returns:

the cumulative offset in bytes of this Memory from the base Memory including the given offset.

getMemoryRequest

MemoryRequest getMemoryRequest()

Returns a MemoryRequest or null

Returns:

a MemoryRequest or null

getNativeMemory

NativeMemory getNativeMemory()

Returns the root NativeMemory, which could also be the derived MemoryMappedFile or AllocMemory.

Returns:

the root NativeMemory.

getParent

Object getParent()

Gets the parent Memory or backing array. Used internally.

Returns:

the parent Memory.

hasArray

boolean hasArray()

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

Returns:

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

hasByteBuffer

boolean hasByteBuffer()

Returns true if this Memory is backed by a ByteBuffer

Returns:

true if this Memory is backed by a ByteBuffer

isAllocated

boolean isAllocated()

Returns true if this Memory has a capacity greater than zero

Returns:

true if this Memory has a capacity greater than zero

isDirect

boolean isDirect()

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

Returns:

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

isReadOnly

boolean isReadOnly()

Returns true if this Memory is read only

Returns:

true if this Memory is read only

setMemoryRequest

void setMemoryRequest(MemoryRequest memReq)

Sets a MemoryRequest

Parameters:

memReq - the MemoryRequest

toHexString

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

Returns a formatted hex string of an area of this Memory. Used primarily for testing.

Parameters:

header - decriptive header

offsetBytes - offset bytes relative to this Memory start

lengthBytes - number of bytes to convert to a hex string

Returns:

a formatted hex string in a human readable array