Package com.kenai.jffi
Class MemoryIO
- java.lang.Object
-
- com.kenai.jffi.MemoryIO
-
- Direct Known Subclasses:
MemoryIO.CheckedNativeImpl
,MemoryIO.NativeImpl
,UnsafeMemoryIO
public abstract class MemoryIO extends java.lang.Object
Provides facilities to access native memory from java.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
MemoryIO.CheckedMemorySingletonHolder
private static class
MemoryIO.CheckedNativeImpl
private static class
MemoryIO.NativeImpl
An implementation of MemoryIO using JNI methods.private static class
MemoryIO.NativeImpl32
A 32 bit optimized implementation ofMemoryIO
using JNI.private static class
MemoryIO.NativeImpl64
A 64 bit optimized implementation ofMemoryIO
using JNI.private static class
MemoryIO.SingletonHolder
Holds a single instance ofMemoryIO
-
Field Summary
Fields Modifier and Type Field Description (package private) static long
ADDRESS_MASK
The address mask used to truncate 32bit addresses contained in long values(package private) Foreign
foreign
A handle to the JNI accessor
-
Constructor Summary
Constructors Constructor Description MemoryIO()
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 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.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 viaallocateMemory(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 ByteBufferabstract 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 ofMemoryIO
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.(package private) static boolean
isUnsafeAvailable()
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.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.private static MemoryIO
newMemoryIO()
Creates a new instance ofMemoryIO
optimized for the current platform.private static MemoryIO
newNativeCheckedImpl()
private static MemoryIO
newNativeImpl()
private static MemoryIO
newNativeImpl32()
Creates a new JNI implementation ofMemoryIO
optimized for 32 bit platformsprivate static MemoryIO
newNativeImpl64()
Creates a new JNI implementation ofMemoryIO
optimized for 64 bit platformsprivate static MemoryIO
newUnsafeImpl()
Creates a new sun.misc.Unsafe implementation ofMemoryIO
private static MemoryIO
newUnsafeImpl32()
Creates a new sun.misc.Unsafe implementation ofMemoryIO
optimized for 32 bit platformsprivate static MemoryIO
newUnsafeImpl64()
Creates a new sun.misc.Unsafe implementation ofMemoryIO
optimized for 64 bit platformsabstract 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(java.lang.Class unsafeClass, java.lang.Class primitive)
Verifies that there is are accessor functions (get,put) for a particular primitive type in the sun.misc.Unsafe class.
-
-
-
Field Detail
-
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
-
-
Method Detail
-
getInstance
public static MemoryIO getInstance()
Gets an instance ofMemoryIO
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 ofMemoryIO
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 ofMemoryIO
optimized for 32 bit platforms- Returns:
- An instance of
MemoryIO
-
newNativeImpl64
private static MemoryIO newNativeImpl64()
Creates a new JNI implementation ofMemoryIO
optimized for 64 bit platforms- Returns:
- An instance of
MemoryIO
-
newUnsafeImpl
private static MemoryIO newUnsafeImpl()
Creates a new sun.misc.Unsafe implementation ofMemoryIO
- Returns:
- An instance of
MemoryIO
-
newUnsafeImpl32
private static MemoryIO newUnsafeImpl32()
Creates a new sun.misc.Unsafe implementation ofMemoryIO
optimized for 32 bit platforms- Returns:
- An instance of
MemoryIO
-
newUnsafeImpl64
private static MemoryIO newUnsafeImpl64()
Creates a new sun.misc.Unsafe implementation ofMemoryIO
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 allocateclear
- 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 viaallocateMemory(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 memoryoffset
- The offset within the byte array to begin copying fromlength
- 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.
-
verifyAccessor
private static void verifyAccessor(java.lang.Class unsafeClass, java.lang.Class primitive) throws java.lang.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.Unsafeprimitive
- The class of the primitive type.- Throws:
java.lang.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
-
-