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
APointerto memory obtained from the native heap via a call tomalloc.In some cases it might be necessary to use memory obtained from
malloc. For example,Memoryhelps 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
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description Memoryalign(int byteBoundary)Provide a view onto this structure with the given alignment.protected voidboundsCheck(long off, long sz)Check that indirection won't cause us to write outside the malloc'ed space.voidclear()Zero the full extent of this memory region.protected voiddispose()Free the native memory and set peer to zerostatic voiddisposeAll()Dispose of all allocated memory.java.lang.Stringdump()Dumps the contents of this memory object.protected voidfinalize()Properly dispose of native memory when this object is GC'd.protected static voidfree(long p)bytegetByte(long offset)Indirect the native pointer tomallocspace, a laPointer.getByte.java.nio.ByteBuffergetByteBuffer(long offset, long length)Get a ByteBuffer mapped to a portion of this memory.chargetChar(long offset)Indirect the native pointer tomallocspace, a laPointer.getByte.doublegetDouble(long offset)Indirect the native pointer tomallocspace, a laPointer.getDouble.floatgetFloat(long offset)Indirect the native pointer tomallocspace, a laPointer.getFloat.intgetInt(long offset)Indirect the native pointer tomallocspace, a laPointer.getInt.longgetLong(long offset)Indirect the native pointer tomallocspace, a laPointer.getLong.PointergetPointer(long offset)Indirect the native pointer tomallocspace, a laPointer.getPointer.shortgetShort(long offset)Indirect the native pointer tomallocspace, a laPointer.getShort.java.lang.StringgetString(long offset, java.lang.String encoding)Copy native memory to a Java String using the requested encoding.java.lang.StringgetWideString(long offset)Read a wide (const wchar_t *) string from memory.(package private) static intintegrityCheck()Unit-testing only, ensure the doubly linked list is in a good shape.protected static longmalloc(long size)static voidpurge()Force cleanup of memory that has associated NIO Buffers which have been GC'd.voidread(long bOff, byte[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.read.voidread(long bOff, char[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.read.voidread(long bOff, double[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.read.voidread(long bOff, float[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.read.voidread(long bOff, int[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.read.voidread(long bOff, long[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.read.voidread(long bOff, short[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.read.voidread(long bOff, Pointer[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.read.voidsetByte(long offset, byte value)Indirect the native pointer tomallocspace, a laPointer.setByte.voidsetChar(long offset, char value)Indirect the native pointer tomallocspace, a laPointer.setChar.voidsetDouble(long offset, double value)Indirect the native pointer tomallocspace, a laPointer.setDouble.voidsetFloat(long offset, float value)Indirect the native pointer tomallocspace, a laPointer.setFloat.voidsetInt(long offset, int value)Indirect the native pointer tomallocspace, a laPointer.setInt.voidsetLong(long offset, long value)Indirect the native pointer tomallocspace, a laPointer.setLong.voidsetPointer(long offset, Pointer value)Indirect the native pointer tomallocspace, a laPointer.setPointer.voidsetShort(long offset, short value)Indirect the native pointer tomallocspace, a laPointer.setShort.voidsetString(long offset, java.lang.String value, java.lang.String encoding)Copy stringvalueto the location being pointed to, using the requested encoding.voidsetWideString(long offset, java.lang.String value)Copy stringvalueto the location being pointed to as a wide string (wchar_t*).Pointershare(long offset)Provide a view of this memory using the given offset as the base address.Pointershare(long offset, long sz)Provide a view of this memory using the given offset as the base address, bounds-limited with the given size.longsize()java.lang.StringtoString()booleanvalid()Returns false if the memory has been freed.voidwrite(long bOff, byte[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.write.voidwrite(long bOff, char[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.write.voidwrite(long bOff, double[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.write.voidwrite(long bOff, float[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.write.voidwrite(long bOff, int[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.write.voidwrite(long bOff, long[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.write.voidwrite(long bOff, short[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.write.voidwrite(long bOff, Pointer[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.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, setMemory, setNativeLong, setString, setString, setValue
-
-
-
-
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.
-
integrityCheck
static int integrityCheck()
Unit-testing only, ensure the doubly linked list is in a good shape.- Returns:
- the number of tracked instances
-
share
public Pointer share(long offset)
Provide a view of this memory using the given offset as the base address. The returnedPointerwill have a size equal to that of the original minus the offset.
-
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 originalMemoryobject to avoid GC as long as the shared memory is referenced.
-
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:
java.lang.IndexOutOfBoundsException- if the requested alignment can not be met.java.lang.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:
finalizein classjava.lang.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 tomallocspace, a laPointer.read. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
readin classPointer- Parameters:
bOff- byte offset from pointer from which data is copiedbuf-bytearray into which data is copiedindex- array index to which data is copiedlength- 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 tomallocspace, a laPointer.read. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
readin classPointer- Parameters:
bOff- byte offset from pointer from which data is copiedbuf-shortarray into which data is copiedindex- array index to which data is copiedlength- 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 tomallocspace, a laPointer.read. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
readin classPointer- Parameters:
bOff- byte offset from pointer from which data is copiedbuf-chararray into which data is copiedindex- array index to which data is copiedlength- 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 tomallocspace, a laPointer.read. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
readin classPointer- Parameters:
bOff- byte offset from pointer from which data is copiedbuf-intarray into which data is copiedindex- array index to which data is copiedlength- 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 tomallocspace, a laPointer.read. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
readin classPointer- Parameters:
bOff- byte offset from pointer from which data is copiedbuf-longarray into which data is copiedindex- array index to which data is copiedlength- 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 tomallocspace, a laPointer.read. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
readin classPointer- Parameters:
bOff- byte offset from pointer from which data is copiedbuf-floatarray into which data is copiedindex- array index to which data is copiedlength- 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 tomallocspace, a laPointer.read. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
readin classPointer- Parameters:
bOff- byte offset from pointer from which data is copiedbuf-doublearray into which data is copiedindex- array index to which data is copiedlength- number of elements from native pointer that must be copied- See Also:
Pointer.read(long,double[],int,int)
-
read
public void read(long bOff, Pointer[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.read. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
readin classPointer- Parameters:
bOff- byte offset from pointer from which data is copiedbuf-Pointerarray into which data is copiedindex- array index to which data is copiedlength- number of elements from native pointer that must be copied- See Also:
Pointer.read(long,Pointer[],int,int)
-
write
public void write(long bOff, byte[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.write. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
writein classPointer- Parameters:
bOff- byte offset from pointer into which data is copiedbuf-bytearray from which to copyindex- array index from which to start copyinglength- number of elements frombufthat 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 tomallocspace, a laPointer.write. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
writein classPointer- Parameters:
bOff- byte offset from pointer into which data is copiedbuf-shortarray from which to copyindex- array index from which to start copyinglength- number of elements frombufthat 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 tomallocspace, a laPointer.write. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
writein classPointer- Parameters:
bOff- byte offset from pointer into which data is copiedbuf-chararray from which to copyindex- array index from which to start copyinglength- number of elements frombufthat 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 tomallocspace, a laPointer.write. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
writein classPointer- Parameters:
bOff- byte offset from pointer into which data is copiedbuf-intarray from which to copyindex- array index from which to start copyinglength- number of elements frombufthat 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 tomallocspace, a laPointer.write. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
writein classPointer- Parameters:
bOff- byte offset from pointer into which data is copiedbuf-longarray from which to copyindex- array index from which to start copyinglength- number of elements frombufthat 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 tomallocspace, a laPointer.write. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
writein classPointer- Parameters:
bOff- byte offset from pointer into which data is copiedbuf-floatarray from which to copyindex- array index from which to start copyinglength- number of elements frombufthat 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 tomallocspace, a laPointer.write. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
writein classPointer- Parameters:
bOff- byte offset from pointer into which data is copiedbuf-doublearray from which to copyindex- array index from which to start copyinglength- number of elements frombufthat must be copied- See Also:
Pointer.write(long,double[],int,int)
-
write
public void write(long bOff, Pointer[] buf, int index, int length)Indirect the native pointer tomallocspace, a laPointer.write. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
writein classPointer- Parameters:
bOff- byte offset from pointer into which data is copiedbuf-Pointerarray from which to copyindex- array index from which to start copyinglength- number of elements frombufthat must be copied- See Also:
Pointer.write(long,Pointer[],int,int)
-
getByte
public byte getByte(long offset)
Indirect the native pointer tomallocspace, a laPointer.getByte. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
getBytein classPointer- Parameters:
offset- offset from pointer to perform the indirection- Returns:
- the
bytevalue being pointed to - See Also:
Pointer.getByte(long)
-
getChar
public char getChar(long offset)
Indirect the native pointer tomallocspace, a laPointer.getByte. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
getCharin classPointer- Parameters:
offset- offset from pointer to perform the indirection- Returns:
- the
wchar_tvalue being pointed to - See Also:
Pointer.getByte(long)
-
getShort
public short getShort(long offset)
Indirect the native pointer tomallocspace, a laPointer.getShort. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
getShortin classPointer- Parameters:
offset- byte offset from pointer to perform the indirection- Returns:
- the
shortvalue being pointed to - See Also:
Pointer.getShort(long)
-
getInt
public int getInt(long offset)
Indirect the native pointer tomallocspace, a laPointer.getInt. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
getIntin classPointer- Parameters:
offset- byte offset from pointer to perform the indirection- Returns:
- the
intvalue being pointed to - See Also:
Pointer.getInt(long)
-
getLong
public long getLong(long offset)
Indirect the native pointer tomallocspace, a laPointer.getLong. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
getLongin classPointer- Parameters:
offset- byte offset from pointer to perform the indirection- Returns:
- the
longvalue being pointed to - See Also:
Pointer.getLong(long)
-
getFloat
public float getFloat(long offset)
Indirect the native pointer tomallocspace, a laPointer.getFloat. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
getFloatin classPointer- Parameters:
offset- byte offset from pointer to perform the indirection- Returns:
- the
floatvalue being pointed to - See Also:
Pointer.getFloat(long)
-
getDouble
public double getDouble(long offset)
Indirect the native pointer tomallocspace, a laPointer.getDouble. But this method performs a bounds check to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
getDoublein classPointer- Parameters:
offset- byte offset from pointer to perform the indirection- Returns:
- the
doublevalue being pointed to - See Also:
Pointer.getDouble(long)
-
getPointer
public Pointer getPointer(long offset)
Indirect the native pointer tomallocspace, a laPointer.getPointer. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
getPointerin classPointer- Parameters:
offset- byte offset from pointer to perform the indirection- Returns:
- a
Pointerequivalent of the pointer value being pointed to, ornullif the pointer value isNULL; - See Also:
Pointer.getPointer(long)
-
getByteBuffer
public java.nio.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:
getByteBufferin classPointer- Parameters:
offset- byte offset from pointer to start the bufferlength- Length of ByteBuffer- Returns:
- a direct ByteBuffer that accesses the memory being pointed to,
-
getString
public java.lang.String getString(long offset, java.lang.String encoding)Description copied from class:PointerCopy native memory to a Java String using the requested encoding.
-
getWideString
public java.lang.String getWideString(long offset)
Description copied from class:PointerRead a wide (const wchar_t *) string from memory.- Overrides:
getWideStringin classPointer
-
setByte
public void setByte(long offset, byte value)Indirect the native pointer tomallocspace, a laPointer.setByte. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
setBytein classPointer- Parameters:
offset- byte offset from pointer at whichvaluemust be setvalue-bytevalue to set- See Also:
Pointer.setByte(long, byte)
-
setChar
public void setChar(long offset, char value)Indirect the native pointer tomallocspace, a laPointer.setChar. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
setCharin classPointer- Parameters:
offset- byte offset from pointer at whichvaluemust be setvalue-charvalue to set- See Also:
Pointer.setChar(long, char)
-
setShort
public void setShort(long offset, short value)Indirect the native pointer tomallocspace, a laPointer.setShort. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
setShortin classPointer- Parameters:
offset- byte offset from pointer at whichvaluemust be setvalue-shortvalue to set- See Also:
Pointer.setShort(long, short)
-
setInt
public void setInt(long offset, int value)Indirect the native pointer tomallocspace, a laPointer.setInt. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
setIntin classPointer- Parameters:
offset- byte offset from pointer at whichvaluemust be setvalue-intvalue to set- See Also:
Pointer.setInt(long, int)
-
setLong
public void setLong(long offset, long value)Indirect the native pointer tomallocspace, a laPointer.setLong. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
setLongin classPointer- Parameters:
offset- byte offset from pointer at whichvaluemust be setvalue-longvalue to set- See Also:
Pointer.setLong(long, long)
-
setFloat
public void setFloat(long offset, float value)Indirect the native pointer tomallocspace, a laPointer.setFloat. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
setFloatin classPointer- Parameters:
offset- byte offset from pointer at whichvaluemust be setvalue-floatvalue to set- See Also:
Pointer.setFloat(long, float)
-
setDouble
public void setDouble(long offset, double value)Indirect the native pointer tomallocspace, a laPointer.setDouble. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
setDoublein classPointer- Parameters:
offset- byte offset from pointer at whichvaluemust be setvalue-doublevalue to set- See Also:
Pointer.setDouble(long, double)
-
setPointer
public void setPointer(long offset, Pointer value)Indirect the native pointer tomallocspace, a laPointer.setPointer. But this method performs a bounds checks to ensure that the indirection does not cause memory outside themalloced space to be accessed.- Overrides:
setPointerin classPointer- Parameters:
offset- byte offset from pointer at whichvaluemust be setvalue-Pointerholding the actual pointer value to set, which may benullto indicate aNULLpointer.- See Also:
Pointer.setPointer(long, com.sun.jna.Pointer)
-
setString
public void setString(long offset, java.lang.String value, java.lang.String encoding)Description copied from class:PointerCopy stringvalueto the location being pointed to, using the requested encoding.
-
setWideString
public void setWideString(long offset, java.lang.String value)Description copied from class:PointerCopy stringvalueto the location being pointed to as a wide string (wchar_t*).- Overrides:
setWideStringin classPointer- Parameters:
offset- byte offset from pointer at which characters invaluemust be setvalue-java.lang.Stringvalue to set
-
free
protected static void free(long p)
-
malloc
protected static long malloc(long size)
-
dump
public java.lang.String dump()
Dumps the contents of this memory object.
-
-