Package com.sun.jna

Class Memory

java.lang.Object

com.sun.jna.Pointer

com.sun.jna.Memory

Direct Known Subclasses:

StringArray

public class Memory
extends Pointer

A Pointer to memory obtained from the native heap via a call to malloc.

In some cases it might be necessary to use memory obtained from malloc. For example, Memory helps accomplish the following idiom:

        void *buf = malloc(BUF_LEN * sizeof(char));
        call_some_function(buf);
        free(buf);
 

The finalize() method will free allocated memory when this object is no longer referenced.

Author:

Sheng Liang, originator, Todd Fast, suitability modifications, Timothy Wall

See Also:

Pointer

Field Summary

Fields

Modifier and Type	Field	Description
protected long	size

Fields inherited from class com.sun.jna.Pointer

NULL, peer

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Memory()
	Memory(long size)	Allocate space in the native heap via a call to C's malloc.

Method Summary

Modifier and Type	Method	Description
Memory	align(int byteBoundary)	Provide a view onto this structure with the given alignment.
protected void	boundsCheck(long off, long sz)	Check that indirection won't cause us to write outside the malloc'ed space.
void	clear()	Zero the full extent of this memory region.
protected void	dispose()	Free the native memory and set peer to zero
static void	disposeAll()	Dispose of all allocated memory.
String	dump()	Dumps the contents of this memory object.
protected void	finalize()	Properly dispose of native memory when this object is GC'd.
protected static void	free(long p)
byte	getByte(long offset)	Indirect the native pointer to malloc space, a la Pointer.getByte.
ByteBuffer	getByteBuffer(long offset, long length)	Get a ByteBuffer mapped to a portion of this memory.
char	getChar(long offset)	Indirect the native pointer to malloc space, a la Pointer.getByte.
double	getDouble(long offset)	Indirect the native pointer to malloc space, a la Pointer.getDouble.
float	getFloat(long offset)	Indirect the native pointer to malloc space, a la Pointer.getFloat.
int	getInt(long offset)	Indirect the native pointer to malloc space, a la Pointer.getInt.
long	getLong(long offset)	Indirect the native pointer to malloc space, a la Pointer.getLong.
Pointer	getPointer(long offset)	Indirect the native pointer to malloc space, a la Pointer.getPointer.
short	getShort(long offset)	Indirect the native pointer to malloc space, a la Pointer.getShort.
String	getString(long offset, String encoding)	Copy native memory to a Java String using the requested encoding.
String	getWideString(long offset)	Read a wide (const wchar_t *) string from memory.
protected static long	malloc(long size)
static void	purge()	Force cleanup of memory that has associated NIO Buffers which have been GC'd.
void	read(long bOff, byte[] buf, int index, int length)	Indirect the native pointer to malloc space, a la Pointer.read.
void	read(long bOff, char[] buf, int index, int length)	Indirect the native pointer to malloc space, a la Pointer.read.
void	read(long bOff, double[] buf, int index, int length)	Indirect the native pointer to malloc space, a la Pointer.read.
void	read(long bOff, float[] buf, int index, int length)	Indirect the native pointer to malloc space, a la Pointer.read.
void	read(long bOff, int[] buf, int index, int length)	Indirect the native pointer to malloc space, a la Pointer.read.
void	read(long bOff, long[] buf, int index, int length)	Indirect the native pointer to malloc space, a la Pointer.read.
void	read(long bOff, short[] buf, int index, int length)	Indirect the native pointer to malloc space, a la Pointer.read.
void	setByte(long offset, byte value)	Indirect the native pointer to malloc space, a la Pointer.setByte.
void	setChar(long offset, char value)	Indirect the native pointer to malloc space, a la Pointer.setChar.
void	setDouble(long offset, double value)	Indirect the native pointer to malloc space, a la Pointer.setDouble.
void	setFloat(long offset, float value)	Indirect the native pointer to malloc space, a la Pointer.setFloat.
void	setInt(long offset, int value)	Indirect the native pointer to malloc space, a la Pointer.setInt.
void	setLong(long offset, long value)	Indirect the native pointer to malloc space, a la Pointer.setLong.
void	setPointer(long offset, Pointer value)	Indirect the native pointer to malloc space, a la Pointer.setPointer.
void	setShort(long offset, short value)	Indirect the native pointer to malloc space, a la Pointer.setShort.
void	setString(long offset, String value, String encoding)	Copy string value to the location being pointed to, using the requested encoding.
void	setWideString(long offset, String value)	Copy string value to the location being pointed to as a wide string (wchar_t*).
Pointer	share(long offset)	Provide a view of this memory using the given offset as the base address.
Pointer	share(long offset, long sz)	Provide a view of this memory using the given offset as the base address, bounds-limited with the given size.
long	size()
String	toString()
boolean	valid()	Returns false if the memory has been freed.
void	write(long bOff, byte[] buf, int index, int length)	Indirect the native pointer to malloc space, a la Pointer.write.
void	write(long bOff, char[] buf, int index, int length)	Indirect the native pointer to malloc space, a la Pointer.write.
void	write(long bOff, double[] buf, int index, int length)	Indirect the native pointer to malloc space, a la Pointer.write.
void	write(long bOff, float[] buf, int index, int length)	Indirect the native pointer to malloc space, a la Pointer.write.
void	write(long bOff, int[] buf, int index, int length)	Indirect the native pointer to malloc space, a la Pointer.write.
void	write(long bOff, long[] buf, int index, int length)	Indirect the native pointer to malloc space, a la Pointer.write.
void	write(long bOff, short[] buf, int index, int length)	Indirect the native pointer to malloc space, a la Pointer.write.

Methods inherited from class com.sun.jna.Pointer

clear, createConstant, createConstant, dump, equals, getByteArray, getCharArray, getDoubleArray, getFloatArray, getIntArray, getLongArray, getNativeLong, getPointerArray, getPointerArray, getShortArray, getString, getStringArray, getStringArray, getStringArray, getStringArray, getValue, getWideStringArray, getWideStringArray, hashCode, indexOf, nativeValue, nativeValue, read, setMemory, setNativeLong, setString, setString, setValue, write

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, wait, wait, wait

Field Detail

size

protected long size

Constructor Detail

Memory

public Memory(long size)

Allocate space in the native heap via a call to C's malloc.

Parameters:

size - number of bytes of space to allocate

Memory

protected Memory()

Method Detail

purge

public static void purge()

Force cleanup of memory that has associated NIO Buffers which have been GC'd.

disposeAll

public static void disposeAll()

Dispose of all allocated memory.

share

public Pointer share(long offset)

Provide a view of this memory using the given offset as the base address. The returned Pointer will have a size equal to that of the original minus the offset.

Overrides:

share in class Pointer

Throws:

IndexOutOfBoundsException - if the requested memory is outside the allocated bounds.

share

public Pointer share(long offset,
                     long sz)

Provide a view of this memory using the given offset as the base address, bounds-limited with the given size. Maintains a reference to the original Memory object to avoid GC as long as the shared memory is referenced.

Overrides:

share in class Pointer

Throws:

IndexOutOfBoundsException - if the requested memory is outside the allocated bounds.

align

public Memory align(int byteBoundary)

Provide a view onto this structure with the given alignment.

Parameters:

byteBoundary - Align memory to this number of bytes; should be a power of two.

Throws:

IndexOutOfBoundsException - if the requested alignment can not be met.

IllegalArgumentException - if the requested alignment is not a positive power of two.

finalize

protected void finalize()

Properly dispose of native memory when this object is GC'd.

Overrides:

finalize in class Object

dispose

protected void dispose()

Free the native memory and set peer to zero

clear

public void clear()

Zero the full extent of this memory region.

valid

public boolean valid()

Returns false if the memory has been freed.

size

public long size()

boundsCheck

protected void boundsCheck(long off,
                           long sz)

Check that indirection won't cause us to write outside the malloc'ed space.

read

public void read(long bOff,
                 byte[] buf,
                 int index,
                 int length)

Indirect the native pointer to malloc space, a la Pointer.read. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

read in class Pointer

Parameters:

bOff - byte offset from pointer from which data is copied

buf - byte array into which data is copied

index - array index to which data is copied

length - number of elements from native pointer that must be copied

See Also:

Pointer.read(long,byte[],int,int)

read

public void read(long bOff,
                 short[] buf,
                 int index,
                 int length)

Indirect the native pointer to malloc space, a la Pointer.read. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

read in class Pointer

Parameters:

bOff - byte offset from pointer from which data is copied

buf - short array into which data is copied

index - array index to which data is copied

length - number of elements from native pointer that must be copied

See Also:

Pointer.read(long,short[],int,int)

read

public void read(long bOff,
                 char[] buf,
                 int index,
                 int length)

Indirect the native pointer to malloc space, a la Pointer.read. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

read in class Pointer

Parameters:

bOff - byte offset from pointer from which data is copied

buf - char array into which data is copied

index - array index to which data is copied

length - number of elements from native pointer that must be copied

See Also:

Pointer.read(long,char[],int,int)

read

public void read(long bOff,
                 int[] buf,
                 int index,
                 int length)

Indirect the native pointer to malloc space, a la Pointer.read. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

read in class Pointer

Parameters:

bOff - byte offset from pointer from which data is copied

buf - int array into which data is copied

index - array index to which data is copied

length - number of elements from native pointer that must be copied

See Also:

Pointer.read(long,int[],int,int)

read

public void read(long bOff,
                 long[] buf,
                 int index,
                 int length)

Indirect the native pointer to malloc space, a la Pointer.read. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

read in class Pointer

Parameters:

bOff - byte offset from pointer from which data is copied

buf - long array into which data is copied

index - array index to which data is copied

length - number of elements from native pointer that must be copied

See Also:

Pointer.read(long,long[],int,int)

read

public void read(long bOff,
                 float[] buf,
                 int index,
                 int length)

Indirect the native pointer to malloc space, a la Pointer.read. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

read in class Pointer

Parameters:

bOff - byte offset from pointer from which data is copied

buf - float array into which data is copied

index - array index to which data is copied

length - number of elements from native pointer that must be copied

See Also:

Pointer.read(long,float[],int,int)

read

public void read(long bOff,
                 double[] buf,
                 int index,
                 int length)

Indirect the native pointer to malloc space, a la Pointer.read. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

read in class Pointer

Parameters:

bOff - byte offset from pointer from which data is copied

buf - double array into which data is copied

index - array index to which data is copied

length - number of elements from native pointer that must be copied

See Also:

Pointer.read(long,double[],int,int)

write

public void write(long bOff,
                  byte[] buf,
                  int index,
                  int length)

Indirect the native pointer to malloc space, a la Pointer.write. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

write in class Pointer

Parameters:

bOff - byte offset from pointer into which data is copied

buf - byte array from which to copy

index - array index from which to start copying

length - number of elements from buf that must be copied

See Also:

Pointer.write(long,byte[],int,int)

write

public void write(long bOff,
                  short[] buf,
                  int index,
                  int length)

Indirect the native pointer to malloc space, a la Pointer.write. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

write in class Pointer

Parameters:

bOff - byte offset from pointer into which data is copied

buf - short array from which to copy

index - array index from which to start copying

length - number of elements from buf that must be copied

See Also:

Pointer.write(long,short[],int,int)

write

public void write(long bOff,
                  char[] buf,
                  int index,
                  int length)

Indirect the native pointer to malloc space, a la Pointer.write. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

write in class Pointer

Parameters:

bOff - byte offset from pointer into which data is copied

buf - char array from which to copy

index - array index from which to start copying

length - number of elements from buf that must be copied

See Also:

Pointer.write(long,char[],int,int)

write

public void write(long bOff,
                  int[] buf,
                  int index,
                  int length)

Indirect the native pointer to malloc space, a la Pointer.write. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

write in class Pointer

Parameters:

bOff - byte offset from pointer into which data is copied

buf - int array from which to copy

index - array index from which to start copying

length - number of elements from buf that must be copied

See Also:

Pointer.write(long,int[],int,int)

write

public void write(long bOff,
                  long[] buf,
                  int index,
                  int length)

Indirect the native pointer to malloc space, a la Pointer.write. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

write in class Pointer

Parameters:

bOff - byte offset from pointer into which data is copied

buf - long array from which to copy

index - array index from which to start copying

length - number of elements from buf that must be copied

See Also:

Pointer.write(long,long[],int,int)

write

public void write(long bOff,
                  float[] buf,
                  int index,
                  int length)

Indirect the native pointer to malloc space, a la Pointer.write. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

write in class Pointer

Parameters:

bOff - byte offset from pointer into which data is copied

buf - float array from which to copy

index - array index from which to start copying

length - number of elements from buf that must be copied

See Also:

Pointer.write(long,float[],int,int)

write

public void write(long bOff,
                  double[] buf,
                  int index,
                  int length)

Indirect the native pointer to malloc space, a la Pointer.write. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

write in class Pointer

Parameters:

bOff - byte offset from pointer into which data is copied

buf - double array from which to copy

index - array index from which to start copying

length - number of elements from buf that must be copied

See Also:

Pointer.write(long,double[],int,int)

getByte

public byte getByte(long offset)

Indirect the native pointer to malloc space, a la Pointer.getByte. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

getByte in class Pointer

Parameters:

offset - offset from pointer to perform the indirection

Returns:

the byte value being pointed to

See Also:

Pointer.getByte(long)

getChar

public char getChar(long offset)

Indirect the native pointer to malloc space, a la Pointer.getByte. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

getChar in class Pointer

Parameters:

offset - offset from pointer to perform the indirection

Returns:

the wchar_t value being pointed to

See Also:

Pointer.getByte(long)

getShort

public short getShort(long offset)

Indirect the native pointer to malloc space, a la Pointer.getShort. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

getShort in class Pointer

Parameters:

offset - byte offset from pointer to perform the indirection

Returns:

the short value being pointed to

See Also:

Pointer.getShort(long)

getInt

public int getInt(long offset)

Indirect the native pointer to malloc space, a la Pointer.getInt. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

getInt in class Pointer

Parameters:

offset - byte offset from pointer to perform the indirection

Returns:

the int value being pointed to

See Also:

Pointer.getInt(long)

getLong

public long getLong(long offset)

Indirect the native pointer to malloc space, a la Pointer.getLong. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

getLong in class Pointer

Parameters:

offset - byte offset from pointer to perform the indirection

Returns:

the long value being pointed to

See Also:

Pointer.getLong(long)

getFloat

public float getFloat(long offset)

Indirect the native pointer to malloc space, a la Pointer.getFloat. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

getFloat in class Pointer

Parameters:

offset - byte offset from pointer to perform the indirection

Returns:

the float value being pointed to

See Also:

Pointer.getFloat(long)

getDouble

public double getDouble(long offset)

Indirect the native pointer to malloc space, a la Pointer.getDouble. But this method performs a bounds check to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

getDouble in class Pointer

Parameters:

offset - byte offset from pointer to perform the indirection

Returns:

the double value being pointed to

See Also:

Pointer.getDouble(long)

getPointer

public Pointer getPointer(long offset)

Indirect the native pointer to malloc space, a la Pointer.getPointer. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

getPointer in class Pointer

Parameters:

offset - byte offset from pointer to perform the indirection

Returns:

a Pointer equivalent of the pointer value being pointed to, or null if the pointer value is NULL;

See Also:

Pointer.getPointer(long)

getByteBuffer

public ByteBuffer getByteBuffer(long offset,
                                long length)

Get a ByteBuffer mapped to a portion of this memory. We keep a weak reference to all ByteBuffers provided so that this memory object is not GC'd while there are still implicit outstanding references to it (it'd be nice if we could attach our own reference to the ByteBuffer, but the VM generates the object so we have no control over it).

Overrides:

getByteBuffer in class Pointer

Parameters:

offset - byte offset from pointer to start the buffer

length - Length of ByteBuffer

Returns:

a direct ByteBuffer that accesses the memory being pointed to,

getString

public String getString(long offset,
                        String encoding)

Description copied from class: Pointer

Copy native memory to a Java String using the requested encoding.

Overrides:

getString in class Pointer

Parameters:

offset - byte offset from pointer to obtain the native string

encoding - the desired encoding

Returns:

the String value being pointed to

getWideString

public String getWideString(long offset)

Description copied from class: Pointer

Read a wide (const wchar_t *) string from memory.

Overrides:

getWideString in class Pointer

setByte

public void setByte(long offset,
                    byte value)

Indirect the native pointer to malloc space, a la Pointer.setByte. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

setByte in class Pointer

Parameters:

offset - byte offset from pointer at which value must be set

value - byte value to set

See Also:

Pointer.setByte(long, byte)

setChar

public void setChar(long offset,
                    char value)

Indirect the native pointer to malloc space, a la Pointer.setChar. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

setChar in class Pointer

Parameters:

offset - byte offset from pointer at which value must be set

value - char value to set

See Also:

Pointer.setChar(long, char)

setShort

public void setShort(long offset,
                     short value)

Indirect the native pointer to malloc space, a la Pointer.setShort. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

setShort in class Pointer

Parameters:

offset - byte offset from pointer at which value must be set

value - short value to set

See Also:

Pointer.setShort(long, short)

setInt

public void setInt(long offset,
                   int value)

Indirect the native pointer to malloc space, a la Pointer.setInt. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

setInt in class Pointer

Parameters:

offset - byte offset from pointer at which value must be set

value - int value to set

See Also:

Pointer.setInt(long, int)

setLong

public void setLong(long offset,
                    long value)

Indirect the native pointer to malloc space, a la Pointer.setLong. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

setLong in class Pointer

Parameters:

offset - byte offset from pointer at which value must be set

value - long value to set

See Also:

Pointer.setLong(long, long)

setFloat

public void setFloat(long offset,
                     float value)

Indirect the native pointer to malloc space, a la Pointer.setFloat. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

setFloat in class Pointer

Parameters:

offset - byte offset from pointer at which value must be set

value - float value to set

See Also:

Pointer.setFloat(long, float)

setDouble

public void setDouble(long offset,
                      double value)

Indirect the native pointer to malloc space, a la Pointer.setDouble. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

setDouble in class Pointer

Parameters:

offset - byte offset from pointer at which value must be set

value - double value to set

See Also:

Pointer.setDouble(long, double)

setPointer

public void setPointer(long offset,
                       Pointer value)

Indirect the native pointer to malloc space, a la Pointer.setPointer. But this method performs a bounds checks to ensure that the indirection does not cause memory outside the malloced space to be accessed.

Overrides:

setPointer in class Pointer

Parameters:

offset - byte offset from pointer at which value must be set

value - Pointer holding the actual pointer value to set, which may be null to indicate a NULL pointer.

See Also:

Pointer.setPointer(long, com.sun.jna.Pointer)

setString

public void setString(long offset,
                      String value,
                      String encoding)

Description copied from class: Pointer

Copy string value to the location being pointed to, using the requested encoding.

Overrides:

setString in class Pointer

Parameters:

offset - byte offset from pointer at which characters in value must be set

value - java.lang.String value to set

encoding - desired encoding

setWideString

public void setWideString(long offset,
                          String value)

Description copied from class: Pointer

Copy string value to the location being pointed to as a wide string (wchar_t*).

Overrides:

setWideString in class Pointer

Parameters:

offset - byte offset from pointer at which characters in value must be set

value - java.lang.String value to set

toString

public String toString()

Overrides:

toString in class Pointer

free

protected static void free(long p)

malloc

protected static long malloc(long size)

dump

public String dump()

Dumps the contents of this memory object.