Package com.kenai.jffi

Class MemoryIO

java.lang.Object
com.kenai.jffi.MemoryIO
Direct Known Subclasses:
UnsafeMemoryIO
public abstract class MemoryIO
extends java.lang.Object
Provides facilities to access native memory from java.

  • Method Summary

    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​(java.nio.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.
    java.nio.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.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • 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 java.nio.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​(java.nio.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.