Class MemoryIO

java.lang.Object
com.kenai.jffi.MemoryIO
Direct Known Subclasses:
MemoryIO.CheckedNativeImpl, MemoryIO.NativeImpl, UnsafeMemoryIO

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

    Nested Classes
    Modifier and Type
    Class
    Description
    private static final class 
     
    private static final class 
     
    private static class 
    An implementation of MemoryIO using JNI methods.
    private static final class 
    A 32 bit optimized implementation of MemoryIO using JNI.
    private static final class 
    A 64 bit optimized implementation of MemoryIO using JNI.
    private static final class 
    Holds a single instance of MemoryIO
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) static final long
    The address mask used to truncate 32bit addresses contained in long values
    (package private) final Foreign
    A handle to the JNI accessor
  • Constructor Summary

    Constructors
    Constructor
    Description
     
  • Method Summary

    Modifier and Type
    Method
    Description
    (package private) abstract void
    _copyMemory(long src, long dst, long size)
    Copies contents of a native memory location to another native memory location.
    final long
    allocateMemory(long size, boolean clear)
    Allocates native memory.
    final void
    copyMemory(long src, long dst, long size)
    Copies contents of a native memory location to another native memory location.
    final 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
     
    final long
    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
    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[]
    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.
    final byte[]
    getZeroTerminatedByteArray(long address, long maxlen)
    Deprecated.
    final long
    indexOf(long address, byte value)
    Finds the location of a byte value in a native memory region.
    final long
    indexOf(long address, byte value, int maxlen)
    Finds the location of a byte value in a native memory region.
    (package private) static boolean
    Determines the best Unsafe implementation to use.
    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.
    final void
    memset(long address, int value, long size)
    Sets a region of native memory to a specific byte value.
    newDirectByteBuffer(long address, int capacity)
    Creates a new Direct ByteBuffer for a native memory region.
    private static MemoryIO
    Creates a new instance of MemoryIO optimized for the current platform.
    private static MemoryIO
     
    private static MemoryIO
     
    private static MemoryIO
    Creates a new JNI implementation of MemoryIO optimized for 32 bit platforms
    private static MemoryIO
    Creates a new JNI implementation of MemoryIO optimized for 64 bit platforms
    private static MemoryIO
    Creates a new sun.misc.Unsafe implementation of MemoryIO
    private static MemoryIO
    Creates a new sun.misc.Unsafe implementation of MemoryIO optimized for 32 bit platforms
    private static MemoryIO
    Creates a new sun.misc.Unsafe implementation of MemoryIO optimized for 64 bit platforms
    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.
    private static void
    verifyAccessor(Class unsafeClass, Class primitive)
    Verifies that there is are accessor functions (get,put) for a particular primitive type in the sun.misc.Unsafe class.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • foreign

      final Foreign foreign
      A handle to the JNI accessor
    • ADDRESS_MASK

      static final long ADDRESS_MASK
      The address mask used to truncate 32bit addresses contained in long values
  • Constructor Details

    • MemoryIO

      MemoryIO()
  • 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()
    • newMemoryIO

      private static MemoryIO newMemoryIO()
      Creates a new instance of MemoryIO optimized for the current platform.
      Returns:
      An instance of MemoryIO
    • newNativeImpl

      private static MemoryIO newNativeImpl()
    • newNativeCheckedImpl

      private static MemoryIO newNativeCheckedImpl()
    • newNativeImpl32

      private static MemoryIO newNativeImpl32()
      Creates a new JNI implementation of MemoryIO optimized for 32 bit platforms
      Returns:
      An instance of MemoryIO
    • newNativeImpl64

      private static MemoryIO newNativeImpl64()
      Creates a new JNI implementation of MemoryIO optimized for 64 bit platforms
      Returns:
      An instance of MemoryIO
    • newUnsafeImpl

      private static MemoryIO newUnsafeImpl()
      Creates a new sun.misc.Unsafe implementation of MemoryIO
      Returns:
      An instance of MemoryIO
    • newUnsafeImpl32

      private static MemoryIO newUnsafeImpl32()
      Creates a new sun.misc.Unsafe implementation of MemoryIO optimized for 32 bit platforms
      Returns:
      An instance of MemoryIO
    • newUnsafeImpl64

      private static MemoryIO newUnsafeImpl64()
      Creates a new sun.misc.Unsafe implementation of MemoryIO optimized for 64 bit platforms
      Returns:
      An instance of MemoryIO
    • 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.
    • _copyMemory

      abstract 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.
    • verifyAccessor

      private static void verifyAccessor(Class unsafeClass, Class primitive) throws NoSuchMethodException
      Verifies that there is are accessor functions (get,put) for a particular primitive type in the sun.misc.Unsafe class.
      Parameters:
      unsafeClass - The class of sun.misc.Unsafe
      primitive - The class of the primitive type.
      Throws:
      NoSuchMethodException - If no accessors for that primitive type exist.
    • isUnsafeAvailable

      static boolean isUnsafeAvailable()
      Determines the best Unsafe implementation to use. Some platforms (e.g. gcj) do not have all the methods that sun.misc.Unsafe does, so we need to check for them. This also handles the case where sun.misc.Unsafe vanishes from future versions of the JVM.
      Returns:
      true if sun.misc.Unsafe is available and usable