com.yahoo.memory

Interface Memory

All Known Implementing Classes:

AllocMemory, MemoryMappedFile, MemoryRegion, 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
int	addAndGetInt(long offsetBytes, int delta) Atomically adds the given value to the integer located at offsetBytes.
long	addAndGetLong(long offsetBytes, long delta) Atomically adds the given value to the long located at offsetBytes.
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
boolean	compareAndSwapInt(long offsetBytes, int expect, int update) Atomically sets the current value at the memory location to the given updated value if and only if the current value == the expected value.
boolean	compareAndSwapLong(long offsetBytes, long expect, long update) Atomically sets the current value at the memory location to the given updated value if and only if the current value == the expected value.
void	copy(long srcOffsetBytes, long dstOffsetBytes, long lengthBytes) Deprecated. Use copy(long, Memory, long, long) instead.
void	copy(long srcOffsetBytes, Memory destination, long dstOffsetBytes, long lengthBytes) Copies bytes from a source range of this Memory to a destination range of the given Memory using the same low-level system copy function as found in System.arraycopy(Object, int, Object, int, int).
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.
void	freeMemory() Because the Memory classes now use the JVM Cleaner, calling freeMemory(), which also calls Cleaner, is optional.
long	getAddress(long offsetBytes) Returns the start address of this Memory relative to its parent plus the offset in bytes.
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 root of the Memory hierarchy including the given offsetBytes.
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
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

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 preallocated destination array.

dstOffset - offset in array units

length - number of array units to transfer

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 preallocated destination array.

dstOffset - offset in array units

length - number of array units to transfer

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 preallocated destination array.

dstOffset - offset in array units

length - number of array units to transfer

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 preallocated destination array.

dstOffset - offset in array units

length - number of array units to transfer

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 preallocated destination array.

dstOffset - offset in array units

length - number of array units to transfer

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 preallocated destination array.

dstOffset - offset in array units

length - number of array units to transfer

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 preallocated destination array.

dstOffset - offset in array units

length - number of array units to transfer

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 preallocated destination array.

dstOffset - offset in array units

length - number of array units to transfer

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

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

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

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

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

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

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

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

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

addAndGetInt

int addAndGetInt(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

addAndGetLong

long addAndGetLong(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

compareAndSwapInt

boolean compareAndSwapInt(long offsetBytes,
                          int expect,
                          int update)

Atomically sets the current value at the memory location to the given updated value if and only if the current value == the expected value.

Parameters:

offsetBytes - offset bytes relative to this Memory start

expect - the expected value

update - the new value

Returns:

true if successful. False return indicates that the current value at the memory location was not equal to the expected value.

compareAndSwapLong

boolean compareAndSwapLong(long offsetBytes,
                           long expect,
                           long update)

Atomically sets the current value at the memory location to the given updated value if and only if the current value == the expected value.

Parameters:

offsetBytes - offset bytes relative to this Memory start

expect - the expected value

update - the new value

Returns:

true if successful. False return indicates that the current value at the memory location was not equal to the expected 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

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

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

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

Deprecated. Use copy(long, Memory, long, long) instead.

Copies bytes from a source range of this Memory to a destination range of the given Memory using the same low-level system copy function as found in System.arraycopy(Object, int, Object, int, int). 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

copy

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

Copies bytes from a source range of this Memory to a destination range of the given Memory using the same low-level system copy function as found in System.arraycopy(Object, int, Object, int, int).

Parameters:

srcOffsetBytes - the source offset for this Memory

destination - the destination Memory, which may not be Read-Only.

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

getAddress

long getAddress(long offsetBytes)

Returns the start address of this Memory relative to its parent plus the offset in bytes. Note that the parent could be native memory or some backing object.

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.

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 root of the Memory hierarchy including the given offsetBytes.

Parameters:

offsetBytes - the given offset in bytes

Returns:

the cumulative offset in bytes of this Memory from the root of the Memory hierarchy including the given offsetBytes.

getMemoryRequest

MemoryRequest getMemoryRequest()

Returns a MemoryRequest or null

Returns:

a MemoryRequest or null

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 - descriptive 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

freeMemory

void freeMemory()

Because the Memory classes now use the JVM Cleaner, calling freeMemory(), which also calls Cleaner, is optional. In any case, calling freeMemory() is only relevant for Memory objects that have actually allocated native memory, which are those that have been allocated using AllocMemory or MemoryMappedFile.

Preemptively calling freeMemory() may reduce the load on the JVM GarbageCollector, but the significance of this will have to be verified in the target system environment. Calling freeMemory() always disables the current instance by setting the capacity to zero.