Class MemoryIO


  • public abstract class MemoryIO
    extends Object
    Provides facilities to access native memory from java.
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      long allocateMemory​(long size, boolean clear)
      Allocates native memory.
      void copyMemory​(long src, long dst, long size)
      Copies contents of a native memory location to another native memory location.
      void freeMemory​(long address)
      Releases memory allocated via allocateMemory(long, boolean) back to the system.
      abstract long getAddress​(long address)
      Reads a native memory address from a native memory location.
      abstract byte getByte​(long address)
      Reads an 8 bit integer from a native memory location.
      abstract void getByteArray​(long address, byte[] data, int offset, int length)
      Reads a java byte array from native memory.
      abstract void getCharArray​(long address, char[] data, int offset, int length)
      Reads a java char array from native memory.
      static MemoryIO getCheckedInstance()  
      long getDirectBufferAddress​(Buffer buffer)
      Gets the native memory address of a direct ByteBuffer
      abstract double getDouble​(long address)
      Reads a 64 bit floating point value from a native memory location.
      abstract void getDoubleArray​(long address, double[] data, int offset, int length)
      Reads a java double array from native memory.
      abstract float getFloat​(long address)
      Reads a 32 bit floating point value from a native memory location.
      abstract void getFloatArray​(long address, float[] data, int offset, int length)
      Reads a java float array from native memory.
      static MemoryIO getInstance()
      Gets an instance of MemoryIO that can be used to access native memory.
      abstract int getInt​(long address)
      Reads a 32 bit integer from a native memory location.
      abstract void getIntArray​(long address, int[] data, int offset, int length)
      Reads a java int array from native memory.
      abstract long getLong​(long address)
      Reads a 64 bit integer from a native memory location.
      abstract void getLongArray​(long address, long[] data, int offset, int length)
      Reads a java long array from native memory.
      abstract short getShort​(long address)
      Reads a 16 bit integer from a native memory location.
      abstract void getShortArray​(long address, short[] data, int offset, int length)
      Reads a java short array from native memory.
      abstract long getStringLength​(long address)
      Gets the length of a native ascii or utf-8 string.
      abstract byte[] getZeroTerminatedByteArray​(long address)
      Reads a byte array from native memory, stopping when a zero byte is found.
      abstract byte[] getZeroTerminatedByteArray​(long address, int maxlen)
      Reads a byte array from native memory, stopping when a zero byte is found, or the maximum length is reached.
      byte[] getZeroTerminatedByteArray​(long address, long maxlen)
      Deprecated.
      long indexOf​(long address, byte value)
      Finds the location of a byte value in a native memory region.
      long indexOf​(long address, byte value, int maxlen)
      Finds the location of a byte value in a native memory region.
      abstract long memchr​(long address, int value, long size)
      Gets the address of a byte value in a native memory region.
      abstract void memcpy​(long dst, long src, long size)
      Copies bytes from one memory location to another.
      abstract void memmove​(long dst, long src, long size)
      Copies potentially overlapping memory areas.
      void memset​(long address, int value, long size)
      Sets a region of native memory to a specific byte value.
      ByteBuffer newDirectByteBuffer​(long address, int capacity)
      Creates a new Direct ByteBuffer for a native memory region.
      abstract void putAddress​(long address, long value)
      Writes a native memory address value to a native memory location.
      abstract void putByte​(long address, byte value)
      Writes an 8 bit integer value to a native memory location.
      abstract void putByteArray​(long address, byte[] data, int offset, int length)
      Writes a java byte array to native memory.
      abstract void putCharArray​(long address, char[] data, int offset, int length)
      Writes a java char array to native memory.
      abstract void putDouble​(long address, double value)
      Writes a 64 bit floating point value to a native memory location.
      abstract void putDoubleArray​(long address, double[] data, int offset, int length)
      Writes a java double array to native memory.
      abstract void putFloat​(long address, float value)
      Writes a 32 bit floating point value to a native memory location.
      abstract void putFloatArray​(long address, float[] data, int offset, int length)
      Writes a java double array to native memory.
      abstract void putInt​(long address, int value)
      Writes a 32 bit integer value to a native memory location.
      abstract void putIntArray​(long address, int[] data, int offset, int length)
      Writes a java int array to native memory.
      abstract void putLong​(long address, long value)
      Writes a 64 bit integer value to a native memory location.
      abstract void putLongArray​(long address, long[] data, int offset, int length)
      Writes a java long array to native memory.
      abstract void putShort​(long address, short value)
      Writes a 16 bit integer value to a native memory location.
      abstract void putShortArray​(long address, short[] data, int offset, int length)
      Writes a java short array to native memory.
      abstract void putZeroTerminatedByteArray​(long address, byte[] data, int offset, int length)
      Copies a java byte array to native memory and appends a NUL terminating byte.
      abstract void setMemory​(long address, long size, byte value)
      Sets a region of native memory to a specific byte value.
    • Method Detail

      • getInstance

        public static MemoryIO getInstance()
        Gets an instance of MemoryIO that can be used to access native memory.
        Returns:
        A MemoryIO instance.
      • getCheckedInstance

        public static MemoryIO getCheckedInstance()
      • getByte

        public abstract byte getByte​(long address)
        Reads an 8 bit integer from a native memory location.
        Parameters:
        address - The memory location to get the value from.
        Returns:
        A byte containing the value.
      • getShort

        public abstract short getShort​(long address)
        Reads a 16 bit integer from a native memory location.
        Parameters:
        address - The memory location to get the value from.
        Returns:
        A short containing the value.
      • getInt

        public abstract int getInt​(long address)
        Reads a 32 bit integer from a native memory location.
        Parameters:
        address - The memory location to get the value from.
        Returns:
        An int containing the value.
      • getLong

        public abstract long getLong​(long address)
        Reads a 64 bit integer from a native memory location.
        Parameters:
        address - The memory location to get the value from.
        Returns:
        A long containing the value.
      • getFloat

        public abstract float getFloat​(long address)
        Reads a 32 bit floating point value from a native memory location.
        Parameters:
        address - The memory location to get the value from.
        Returns:
        A float containing the value.
      • getDouble

        public abstract double getDouble​(long address)
        Reads a 64 bit floating point value from a native memory location.
        Parameters:
        address - The memory location to get the value from.
        Returns:
        A double containing the value.
      • getAddress

        public abstract long getAddress​(long address)
        Reads a native memory address from a native memory location.
        Parameters:
        address - The memory location to get the value from.
        Returns:
        A long containing the value.
      • putByte

        public abstract void putByte​(long address,
                                     byte value)
        Writes an 8 bit integer value to a native memory location.
        Parameters:
        address - The memory location to put the value.
        value - The value to write to memory.
      • putShort

        public abstract void putShort​(long address,
                                      short value)
        Writes a 16 bit integer value to a native memory location.
        Parameters:
        address - The memory location to put the value.
        value - The value to write to memory.
      • putInt

        public abstract void putInt​(long address,
                                    int value)
        Writes a 32 bit integer value to a native memory location.
        Parameters:
        address - The memory location to put the value.
        value - The value to write to memory.
      • putLong

        public abstract void putLong​(long address,
                                     long value)
        Writes a 64 bit integer value to a native memory location.
        Parameters:
        address - The memory location to put the value.
        value - The value to write to memory.
      • putFloat

        public abstract void putFloat​(long address,
                                      float value)
        Writes a 32 bit floating point value to a native memory location.
        Parameters:
        address - The memory location to put the value.
        value - The value to write to memory.
      • putDouble

        public abstract void putDouble​(long address,
                                       double value)
        Writes a 64 bit floating point value to a native memory location.
        Parameters:
        address - The memory location to put the value.
        value - The value to write to memory.
      • putAddress

        public abstract void putAddress​(long address,
                                        long value)
        Writes a native memory address value to a native memory location.
        Parameters:
        address - The memory location to put the value.
        value - The value to write to memory.
      • copyMemory

        public final void copyMemory​(long src,
                                     long dst,
                                     long size)
        Copies contents of a native memory location to another native memory location.
        Parameters:
        src - The source memory address.
        dst - The destination memory address.
        size - The number of bytes to copy.
      • setMemory

        public abstract void setMemory​(long address,
                                       long size,
                                       byte value)
        Sets a region of native memory to a specific byte value.
        Parameters:
        address - The address of start of the native memory.
        size - The number of bytes to set.
        value - The value to set the native memory to.
      • memcpy

        public abstract void memcpy​(long dst,
                                    long src,
                                    long size)
        Copies bytes from one memory location to another. The memory areas
        Parameters:
        dst - The destination memory address.
        src - The source memory address.
        size - The number of bytes to copy.
      • memmove

        public abstract void memmove​(long dst,
                                     long src,
                                     long size)
        Copies potentially overlapping memory areas.
        Parameters:
        dst - The destination memory address.
        src - The source memory address.
        size - The number of bytes to copy.
      • memset

        public final void memset​(long address,
                                 int value,
                                 long size)
        Sets a region of native memory to a specific byte value.
        Parameters:
        address - The address of start of the native memory.
        value - The value to set the native memory to.
        size - The number of bytes to set.
      • memchr

        public abstract long memchr​(long address,
                                    int value,
                                    long size)
        Gets the address of a byte value in a native memory region.
        Parameters:
        address - The native memory address to start searching.
        value - The value to search for.
        size - The size of the native memory region being searched.
        Returns:
        The address of the value, or 0 (zero) if not found.
      • putByteArray

        public abstract void putByteArray​(long address,
                                          byte[] data,
                                          int offset,
                                          int length)
        Writes a java byte array to native memory.
        Parameters:
        address - The native memory address to copy the array to.
        data - The java array to copy.
        offset - The offset within the array to start copying from.
        length - The number of array elements to copy.
      • getByteArray

        public abstract void getByteArray​(long address,
                                          byte[] data,
                                          int offset,
                                          int length)
        Reads a java byte array from native memory.
        Parameters:
        address - The native memory address to copy the array from.
        data - The java array to copy.
        offset - The offset within the array to start copying to.
        length - The number of array elements to copy.
      • putCharArray

        public abstract void putCharArray​(long address,
                                          char[] data,
                                          int offset,
                                          int length)
        Writes a java char array to native memory.
        Parameters:
        address - The native memory address to copy the array to.
        data - The java array to copy.
        offset - The offset within the array to start copying from.
        length - The number of array elements to copy.
      • getCharArray

        public abstract void getCharArray​(long address,
                                          char[] data,
                                          int offset,
                                          int length)
        Reads a java char array from native memory.
        Parameters:
        address - The native memory address to copy the array from.
        data - The java array to copy.
        offset - The offset within the array to start copying to.
        length - The number of array elements to copy.
      • putShortArray

        public abstract void putShortArray​(long address,
                                           short[] data,
                                           int offset,
                                           int length)
        Writes a java short array to native memory.
        Parameters:
        address - The native memory address to copy the array to.
        data - The java array to copy.
        offset - The offset within the array to start copying from.
        length - The number of array elements to copy.
      • getShortArray

        public abstract void getShortArray​(long address,
                                           short[] data,
                                           int offset,
                                           int length)
        Reads a java short array from native memory.
        Parameters:
        address - The native memory address to copy the array from.
        data - The java array to copy.
        offset - The offset within the array to start copying to.
        length - The number of array elements to copy.
      • putIntArray

        public abstract void putIntArray​(long address,
                                         int[] data,
                                         int offset,
                                         int length)
        Writes a java int array to native memory.
        Parameters:
        address - The native memory address to copy the array to.
        data - The java array to copy.
        offset - The offset within the array to start copying from.
        length - The number of array elements to copy.
      • getIntArray

        public abstract void getIntArray​(long address,
                                         int[] data,
                                         int offset,
                                         int length)
        Reads a java int array from native memory.
        Parameters:
        address - The native memory address to copy the array from.
        data - The java array to copy.
        offset - The offset within the array to start copying to.
        length - The number of array elements to copy.
      • putLongArray

        public abstract void putLongArray​(long address,
                                          long[] data,
                                          int offset,
                                          int length)
        Writes a java long array to native memory.
        Parameters:
        address - The native memory address to copy the array to.
        data - The java array to copy.
        offset - The offset within the array to start copying from.
        length - The number of array elements to copy.
      • getLongArray

        public abstract void getLongArray​(long address,
                                          long[] data,
                                          int offset,
                                          int length)
        Reads a java long array from native memory.
        Parameters:
        address - The native memory address to copy the array from.
        data - The java array to copy.
        offset - The offset within the array to start copying to.
        length - The number of array elements to copy.
      • putFloatArray

        public abstract void putFloatArray​(long address,
                                           float[] data,
                                           int offset,
                                           int length)
        Writes a java double array to native memory.
        Parameters:
        address - The native memory address to copy the array to.
        data - The java array to copy.
        offset - The offset within the array to start copying from.
        length - The number of array elements to copy.
      • getFloatArray

        public abstract void getFloatArray​(long address,
                                           float[] data,
                                           int offset,
                                           int length)
        Reads a java float array from native memory.
        Parameters:
        address - The native memory address to copy the array from.
        data - The java array to copy.
        offset - The offset within the array to start copying to.
        length - The number of array elements to copy.
      • putDoubleArray

        public abstract void putDoubleArray​(long address,
                                            double[] data,
                                            int offset,
                                            int length)
        Writes a java double array to native memory.
        Parameters:
        address - The native memory address to copy the array to.
        data - The java array to copy.
        offset - The offset within the array to start copying from.
        length - The number of array elements to copy.
      • getDoubleArray

        public abstract void getDoubleArray​(long address,
                                            double[] data,
                                            int offset,
                                            int length)
        Reads a java double array from native memory.
        Parameters:
        address - The native memory address to copy the array from.
        data - The java array to copy.
        offset - The offset within the array to start copying to.
        length - The number of array elements to copy.
      • allocateMemory

        public final long allocateMemory​(long size,
                                         boolean clear)
        Allocates native memory.
        Parameters:
        size - The number of bytes of memory to allocate
        clear - Whether the memory should be cleared (each byte set to zero).
        Returns:
        The native address of the allocated memory.
      • freeMemory

        public final void freeMemory​(long address)
        Releases memory allocated via allocateMemory(long, boolean) back to the system.
        Parameters:
        address - The address of the memory to release.
      • getStringLength

        public abstract long getStringLength​(long address)
        Gets the length of a native ascii or utf-8 string.
        Parameters:
        address - The native address of the string.
        Returns:
        The length of the string, in bytes.
      • getZeroTerminatedByteArray

        public abstract byte[] getZeroTerminatedByteArray​(long address)
        Reads a byte array from native memory, stopping when a zero byte is found. This can be used to read ascii or utf-8 strings from native memory.
        Parameters:
        address - The address to read the data from.
        Returns:
        The byte array containing a copy of the native data. Any zero byte is stripped from the end.
      • getZeroTerminatedByteArray

        public abstract byte[] getZeroTerminatedByteArray​(long address,
                                                          int maxlen)
        Reads a byte array from native memory, stopping when a zero byte is found, or the maximum length is reached. This can be used to read ascii or utf-8 strings from native memory.
        Parameters:
        address - The address to read the data from.
        maxlen - The limit of the memory area to scan for a zero byte.
        Returns:
        The byte array containing a copy of the native data. Any zero byte is stripped from the end.
      • getZeroTerminatedByteArray

        @Deprecated
        public final byte[] getZeroTerminatedByteArray​(long address,
                                                       long maxlen)
        Deprecated.
      • putZeroTerminatedByteArray

        public abstract void putZeroTerminatedByteArray​(long address,
                                                        byte[] data,
                                                        int offset,
                                                        int length)
        Copies a java byte array to native memory and appends a NUL terminating byte. Note A total of length + 1 bytes is written to native memory.
        Parameters:
        address - The address to copy to.
        data - The byte array to copy to native memory
        offset - The offset within the byte array to begin copying from
        length - The number of bytes to copy to native memory
      • indexOf

        public final long indexOf​(long address,
                                  byte value)
        Finds the location of a byte value in a native memory region.
        Parameters:
        address - The native memory address to start searching from.
        value - The value to search for.
        Returns:
        The offset from the memory address of the value, if found, else -1 (minus one).
      • indexOf

        public final long indexOf​(long address,
                                  byte value,
                                  int maxlen)
        Finds the location of a byte value in a native memory region.
        Parameters:
        address - The native memory address to start searching from.
        value - The value to search for.
        maxlen - The maximum number of bytes to search.
        Returns:
        The offset from the memory address of the value, if found, else -1 (minus one).
      • newDirectByteBuffer

        public final ByteBuffer newDirectByteBuffer​(long address,
                                                    int capacity)
        Creates a new Direct ByteBuffer for a native memory region.
        Parameters:
        address - The start of the native memory region.
        capacity - The size of the native memory region.
        Returns:
        A ByteBuffer representing the native memory region.
      • getDirectBufferAddress

        public final long getDirectBufferAddress​(Buffer buffer)
        Gets the native memory address of a direct ByteBuffer
        Parameters:
        buffer - A direct ByteBuffer to get the address of.
        Returns:
        The native memory address of the buffer contents, or null if not a direct buffer.