Package com.sun.jna

Class 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  
    • 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

      All Methods Static Methods Instance Methods Concrete Methods 
      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.
    • 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
      • 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.