Package io.github.jwharm.javagi.interop

Class Interop

java.lang.Object

io.github.jwharm.javagi.interop.Interop

public class Interop
extends Object

The Interop class contains functionality for interoperability with native code.

Constructor Summary

Constructors

Constructor	Description
Interop()

Method Summary

Modifier and Type	Method	Description
static MemorySegment	allocateNativeArray(boolean[] array, boolean zeroTerminated, Arena arena)	Convert a boolean[] array into an int[] array, and calls allocateNativeArray(int[], boolean, Arena).
static MemorySegment	allocateNativeArray(byte[] array, boolean zeroTerminated, Arena arena)	Allocate and initialize an (optionally NULL-terminated) array of bytes.
static MemorySegment	allocateNativeArray(char[] array, boolean zeroTerminated, Arena arena)	Allocate and initialize an (optionally NULL-terminated) array of chars.
static MemorySegment	allocateNativeArray(double[] array, boolean zeroTerminated, Arena arena)	Allocate and initialize an (optionally NULL-terminated) array of doubles.
static MemorySegment	allocateNativeArray(float[] array, boolean zeroTerminated, Arena arena)	Allocate and initialize an (optionally NULL-terminated) array of floats.
static MemorySegment	allocateNativeArray(int[] array, boolean zeroTerminated, Arena arena)	Allocate and initialize an (optionally NULL-terminated) array of floats.
static MemorySegment	allocateNativeArray(long[] array, boolean zeroTerminated, Arena arena)	Allocate and initialize an (optionally NULL-terminated) array of longs.
static MemorySegment	allocateNativeArray(short[] array, boolean zeroTerminated, Arena arena)	Allocate and initialize an (optionally NULL-terminated) array of shorts.
static MemorySegment	allocateNativeArray(Proxy[] array, boolean zeroTerminated, Arena arena)	Allocate and initialize an (optionally NULL-terminated) array of pointers (from Proxy instances).
static MemorySegment	allocateNativeArray(Proxy[] array, MemoryLayout layout, boolean zeroTerminated, Arena arena)	Allocate and initialize an (optionally NULL-terminated) array of structs (from Proxy instances).
static MemorySegment	allocateNativeArray(MemorySegment[] array, boolean zeroTerminated, Arena arena)	Allocate and initialize an (optionally NULL-terminated) array of memory addresses.
static MemorySegment	allocateNativeArray(String[] strings, boolean zeroTerminated, Arena arena)	Allocate and initialize an (optionally NULL-terminated) array of strings (NULL-terminated utf8 char*).
static MemorySegment	allocateNativeString(String string, SegmentAllocator alloc)	Allocate a native string using SegmentAllocator.allocateFrom(String), but return MemorySegment.NULL for a null argument.
static Arena	attachArena(Arena arena, Object instance)	Register a Cleaner that will close the arena when the instance is garbage-collected, coupling the lifetime of the arena to the lifetime of the instance.
static void	copy(MemorySegment src, MemorySegment dst)	First reinterpret the memory segments so they have equal size, then copy src into dst.
static MemorySegment	dereference(MemorySegment pointer)	Dereference a pointer
static MethodHandle	downcallHandle(MemorySegment symbol, FunctionDescriptor fdesc, Linker.Option... options)	Create a method handle that is used to call the native function at the provided memory address.
static MethodHandle	downcallHandle(String name, FunctionDescriptor fdesc)	Convenience method that calls downcallHandle(String, FunctionDescriptor, boolean) with variadic=false.
static MethodHandle	downcallHandle(String name, FunctionDescriptor fdesc, boolean variadic)	Create a method handle that is used to call the native function with the provided name and function descriptor.
static <T extends Enum<T> & Enumeration> int	enumSetToInt(Set<T> set)	Create a bitfield from the provided Set of enums
static MemorySegment[]	getAddressArrayFrom(MemorySegment address, boolean free)	Read an array of pointers from a NULL-terminated array in native memory.
static MemorySegment[]	getAddressArrayFrom(MemorySegment address, int length, boolean free)	Read an array of pointers with the requested length from native memory.
static <T> T[]	getArrayFromIntPointer(MemorySegment address, int length, Class<T> cls, Function<Integer,T> make)	Read an array of integers from native memory, create a Java instance for each integer value with the provided constructor, and return an array of these instances.
static boolean[]	getBooleanArrayFrom(MemorySegment address, long length, Arena arena, boolean free)	Read an array of booleans with the requested length from native memory.
static byte[]	getByteArrayFrom(MemorySegment address, long length, Arena arena, boolean free)	Read an array of bytes with the requested length from native memory.
static byte[]	getByteArrayFrom(MemorySegment address, Arena arena, boolean free)	Read a NULL-terminated array of bytes from native memory.
static char[]	getCharacterArrayFrom(MemorySegment address, long length, Arena arena, boolean free)	Read an array of chars with the requested length from native memory.
static double[]	getDoubleArrayFrom(MemorySegment address, long length, Arena arena, boolean free)	Read an array of doubles with the requested length from native memory.
static float[]	getFloatArrayFrom(MemorySegment address, long length, Arena arena, boolean free)	Read an array of floats with the requested length from native memory.
static int[]	getIntegerArrayFrom(MemorySegment address, long length, Arena arena, boolean free)	Read an array of integers with the requested length from native memory.
static int[]	getIntegerArrayFrom(MemorySegment address, Arena arena, boolean free)	Read a NULL-terminated array of integers from native memory.
static long[]	getLongArrayFrom(MemorySegment address, long length, Arena arena, boolean free)	Read an array of longs with the requested length from native memory.
static <T extends Proxy> T[]	getProxyArrayFrom(MemorySegment address, int length, Class<T> cls, Function<MemorySegment,T> make)	Read an array of memory addresses from native memory, create a Proxy instance for each address, and return an array of Proxy instances.
static <T extends Proxy> T[]	getProxyArrayFrom(MemorySegment address, Class<T> cls, Function<MemorySegment,T> make)	Read a NULL-terminated array of memory addresses from native memory, create a Proxy instance for each address, and return an array of Proxy instances.
static short[]	getShortArrayFrom(MemorySegment address, long length, Arena arena, boolean free)	Read an array of shorts with the requested length from native memory.
static String[]	getStringArrayFrom(MemorySegment address, boolean free)	Read an array of Strings from a NULL-terminated array in native memory.
static String[]	getStringArrayFrom(MemorySegment address, int length, boolean free)	Read an array of Strings with the requested length from native memory.
static String	getStringFrom(MemorySegment address)	Copy a Java string from native memory using MemorySegment.getUtf8String().
static String	getStringFrom(MemorySegment address, boolean free)	Copy a Java string from native memory using MemorySegment.getUtf8String().
static <T extends Proxy> T[]	getStructArrayFrom(MemorySegment address, int length, Class<T> cls, Function<MemorySegment,T> make, MemoryLayout layout)	Read an array of structs from native memory, create a Proxy instance for each struct, and return an array of Proxy instances.
static String[][]	getStrvArrayFrom(MemorySegment address, boolean free)	Read NULL-terminated arrays of Strings from a NULL-terminated array in native memory.
static Type	getType(String getTypeFunction)	Get a GType by executing the provided get-type function.
static int[]	getValues(Enumeration[] array)	Convert an array of enums into an array of integers.
static <T extends Enum<T> & Enumeration> EnumSet<T>	intToEnumSet(Class<T> cls, Function<Integer,T> make, int bitfield)	Create an EnumSet of class `cls` from the provided bitfield
static void	loadLibrary(String name)	Load the specified library using SymbolLookup.libraryLookup(String, Arena)RESTRICTED.
static boolean	longAsInt()
static MemorySegment	reinterpret(MemorySegment address, long newSize)	Reinterpret address to newSize iff newSize is larger than the current size of address.
static MethodHandle	upcallHandle(MethodHandles.Lookup lookup, Class<?> cls, FunctionDescriptor descriptor)	Create a method handle for the upcall method in the provided class.
static MethodHandle	upcallHandle(MethodHandles.Lookup lookup, Class<?> cls, String name, FunctionDescriptor descriptor)	Create a method handle for a method in the provided class.

Methods inherited from class java.lang.Object

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

Constructor Details

Interop

public Interop()

Method Details

longAsInt

public static boolean longAsInt()

loadLibrary

public static void loadLibrary(String name)

Load the specified library using SymbolLookup.libraryLookup(String, Arena)^RESTRICTED.

Parameters:

name - the name of the library

downcallHandle

public static MethodHandle downcallHandle(String name,
 FunctionDescriptor fdesc)

Convenience method that calls downcallHandle(String, FunctionDescriptor, boolean) with variadic=false.

Parameters:

name - name of the native function

fdesc - function descriptor of the native function

Returns:

the MethodHandle

downcallHandle

public static MethodHandle downcallHandle(String name,
 FunctionDescriptor fdesc,
 boolean variadic)

Create a method handle that is used to call the native function with the provided name and function descriptor.

Parameters:

name - name of the native function

fdesc - function descriptor of the native function

variadic - whether the function has varargs

Returns:

the newly created MethodHandle

downcallHandle

public static MethodHandle downcallHandle(MemorySegment symbol,
 FunctionDescriptor fdesc,
 Linker.Option... options)

Create a method handle that is used to call the native function at the provided memory address.

Parameters:

symbol - memory address of the native function

fdesc - function descriptor of the native function

options - linker options

Returns:

the newly created MethodHandle

upcallHandle

public static MethodHandle upcallHandle(MethodHandles.Lookup lookup,
 Class<?> cls,
 FunctionDescriptor descriptor)

Create a method handle for the upcall method in the provided class.

Parameters:

cls - the callback class

descriptor - the function descriptor for the native function

Returns:

a method handle to use when creating an upcall stub

upcallHandle

public static MethodHandle upcallHandle(MethodHandles.Lookup lookup,
 Class<?> cls,
 String name,
 FunctionDescriptor descriptor)

Create a method handle for a method in the provided class.

Parameters:

cls - the callback class

name - the name of the callback method

descriptor - the function descriptor for the native function

Returns:

a method handle to use when creating an upcall stub

attachArena

public static Arena attachArena(Arena arena,
 Object instance)

Register a Cleaner that will close the arena when the instance is garbage-collected, coupling the lifetime of the arena to the lifetime of the instance.

Parameters:

arena - a memory arena that can be closed (normally Arena.ofConfined() or Arena.ofAuto().

instance - an object

Returns:

the arena (for method chaining)

reinterpret

public static MemorySegment reinterpret(MemorySegment address,
 long newSize)

Reinterpret address to newSize iff newSize is larger than the current size of address.

Parameters:

address - a MemorySegment

newSize - new size for the MemorySegment

Returns:

the same MemorySegment reinterpreted to at least newSize

dereference

public static MemorySegment dereference(MemorySegment pointer)

Dereference a pointer

Parameters:

pointer - the pointer to dereference

Returns:

the value of the pointer, or null in case of a pointer to NULL.

copy

public static void copy(MemorySegment src,
 MemorySegment dst)

First reinterpret the memory segments so they have equal size, then copy src into dst.

Parameters:

src - source memory segment

dst - destination memory segment

getType

public static Type getType(String getTypeFunction)

Get a GType by executing the provided get-type function.

Returns:

the gtype from the provided get-type function

allocateNativeString

public static MemorySegment allocateNativeString(String string,
 SegmentAllocator alloc)

Allocate a native string using SegmentAllocator.allocateFrom(String), but return MemorySegment.NULL for a null argument.

Parameters:

string - the string to allocate as a native string (utf8 char*) (can be null)

alloc - the segment allocator to use

Returns:

the allocated MemorySegment with the native utf8 string, or MemorySegment.NULL

getStringFrom

public static String getStringFrom(MemorySegment address)

Copy a Java string from native memory using MemorySegment.getUtf8String(). If an error occurs or when the native address is NULL, null is returned.

The native memory is not freed.

Parameters:

address - the memory address of the native String (a NULL-terminated char*)

Returns:

a String or null

getStringFrom

public static String getStringFrom(MemorySegment address,
 boolean free)

Copy a Java string from native memory using MemorySegment.getUtf8String(). If an error occurs or when the native address is NULL, null is returned.

Parameters:

address - the memory address of the native String (a NULL-terminated char*)

free - if the address must be freed

Returns:

a String or null

getStringArrayFrom

public static String[] getStringArrayFrom(MemorySegment address,
 int length,
 boolean free)

Read an array of Strings with the requested length from native memory.

Parameters:

address - address of the memory segment

length - length of the array

free - if the strings and the array must be freed

Returns:

array of Strings

getStringArrayFrom

public static String[] getStringArrayFrom(MemorySegment address,
 boolean free)

Read an array of Strings from a NULL-terminated array in native memory.

Parameters:

address - address of the memory segment

free - if the strings and the array must be freed

Returns:

array of Strings

getStrvArrayFrom

public static String[][] getStrvArrayFrom(MemorySegment address,
 boolean free)

Read NULL-terminated arrays of Strings from a NULL-terminated array in native memory.

Parameters:

address - address of the memory segment

free - if the strings and the array must be freed

Returns:

two-dimensional array of Strings

getAddressArrayFrom

public static MemorySegment[] getAddressArrayFrom(MemorySegment address,
 int length,
 boolean free)

Read an array of pointers with the requested length from native memory.

Parameters:

address - address of the memory segment

length - length of the array

free - if the array must be freed

Returns:

array of pointers

getAddressArrayFrom

public static MemorySegment[] getAddressArrayFrom(MemorySegment address,
 boolean free)

Read an array of pointers from a NULL-terminated array in native memory.

Parameters:

address - address of the memory segment

free - if the array must be freed

Returns:

array of pointers

getBooleanArrayFrom

public static boolean[] getBooleanArrayFrom(MemorySegment address,
 long length,
 Arena arena,
 boolean free)

Read an array of booleans with the requested length from native memory. The array is read from native memory as an array of integers with value 1 or 0, and converted to booleans with 1 = true and 0 = false.

Parameters:

address - address of the memory segment

length - length of the array

arena - the memory scope

free - if the array must be freed

Returns:

array of booleans

getByteArrayFrom

public static byte[] getByteArrayFrom(MemorySegment address,
 long length,
 Arena arena,
 boolean free)

Read an array of bytes with the requested length from native memory.

Parameters:

address - address of the memory segment

length - length of the array

arena - the memory scope

free - if the array must be freed

Returns:

array of bytes

getByteArrayFrom

public static byte[] getByteArrayFrom(MemorySegment address,
 Arena arena,
 boolean free)

Read a NULL-terminated array of bytes from native memory.

Parameters:

address - address of the memory segment

arena - the memory scope

free - if the array must be freed

Returns:

array of bytes

getCharacterArrayFrom

public static char[] getCharacterArrayFrom(MemorySegment address,
 long length,
 Arena arena,
 boolean free)

Read an array of chars with the requested length from native memory.

Parameters:

address - address of the memory segment

length - length of the array

arena - the memory scope

free - if the array must be freed

Returns:

array of chars

getDoubleArrayFrom

public static double[] getDoubleArrayFrom(MemorySegment address,
 long length,
 Arena arena,
 boolean free)

Read an array of doubles with the requested length from native memory.

Parameters:

address - address of the memory segment

length - length of the array

arena - the memory scope

free - if the array must be freed

Returns:

array of doubles

getFloatArrayFrom

public static float[] getFloatArrayFrom(MemorySegment address,
 long length,
 Arena arena,
 boolean free)

Read an array of floats with the requested length from native memory.

Parameters:

address - address of the memory segment

length - length of the array

arena - the memory scope

free - if the array must be freed

Returns:

array of floats

getIntegerArrayFrom

public static int[] getIntegerArrayFrom(MemorySegment address,
 long length,
 Arena arena,
 boolean free)

Read an array of integers with the requested length from native memory.

Parameters:

address - address of the memory segment

length - length of the array

arena - the memory scope

free - if the array must be freed

Returns:

array of integers

getIntegerArrayFrom

public static int[] getIntegerArrayFrom(MemorySegment address,
 Arena arena,
 boolean free)

Read a NULL-terminated array of integers from native memory.

Parameters:

address - address of the memory segment

arena - the memory scope

free - if the array must be freed

Returns:

array of integers

getLongArrayFrom

public static long[] getLongArrayFrom(MemorySegment address,
 long length,
 Arena arena,
 boolean free)

Read an array of longs with the requested length from native memory.

Parameters:

address - address of the memory segment

length - length of the array

arena - the memory scope

free - if the array must be freed

Returns:

array of longs

getShortArrayFrom

public static short[] getShortArrayFrom(MemorySegment address,
 long length,
 Arena arena,
 boolean free)

Read an array of shorts with the requested length from native memory.

Parameters:

address - address of the memory segment

length - length of the array

arena - the memory scope

free - if the array must be freed

Returns:

array of shorts

getProxyArrayFrom

public static <T extends Proxy> T[] getProxyArrayFrom(MemorySegment address,
 Class<T> cls,
 Function<MemorySegment,T> make)

Read a NULL-terminated array of memory addresses from native memory, create a Proxy instance for each address, and return an array of Proxy instances.

Type Parameters:

T - the type of the Proxy instances

Parameters:

address - address of the memory segment

cls - class of the Proxy type

make - constructor of the Proxy type

Returns:

array of Proxy instances

getProxyArrayFrom

public static <T extends Proxy> T[] getProxyArrayFrom(MemorySegment address,
 int length,
 Class<T> cls,
 Function<MemorySegment,T> make)

Read an array of memory addresses from native memory, create a Proxy instance for each address, and return an array of Proxy instances.

Type Parameters:

T - the type of the Proxy instances

Parameters:

address - address of the memory segment

length - length of the array

cls - class of the Proxy type

make - constructor of the Proxy type

Returns:

array of Proxy instances

getStructArrayFrom

public static <T extends Proxy> T[] getStructArrayFrom(MemorySegment address,
 int length,
 Class<T> cls,
 Function<MemorySegment,T> make,
 MemoryLayout layout)

Read an array of structs from native memory, create a Proxy instance for each struct, and return an array of Proxy instances.

Type Parameters:

T - the type of the Proxy instances

Parameters:

address - address of the memory segment

length - length of the array

cls - class of the Proxy type

make - constructor of the Proxy type

Returns:

array of Proxy instances

getArrayFromIntPointer

public static <T> T[] getArrayFromIntPointer(MemorySegment address,
 int length,
 Class<T> cls,
 Function<Integer,T> make)

Read an array of integers from native memory, create a Java instance for each integer value with the provided constructor, and return an array of these instances. This is used to create an array of Enumeration or Bitfield objects from a native integer array.

Type Parameters:

T - the type to construct

Parameters:

address - address of the memory segment

length - length of the array

cls - class that will be returned in the array

make - constructor to create the instances

Returns:

array of constructed instances

allocateNativeArray

public static MemorySegment allocateNativeArray(String[] strings,
 boolean zeroTerminated,
 Arena arena)

Allocate and initialize an (optionally NULL-terminated) array of strings (NULL-terminated utf8 char*).

Parameters:

strings - array of Strings

zeroTerminated - whether to add a NULL to the array

arena - the segment allocator for memory allocation

Returns:

the memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(boolean[] array,
 boolean zeroTerminated,
 Arena arena)

Convert a boolean[] array into an int[] array, and calls allocateNativeArray(int[], boolean, Arena). Each boolean value "true" is converted 1, boolean value "false" to 0.

Parameters:

array - array of booleans

zeroTerminated - when true, an (int) 0 is appended to the array

arena - the segment allocator for memory allocation

Returns:

The memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(byte[] array,
 boolean zeroTerminated,
 Arena arena)

Allocate and initialize an (optionally NULL-terminated) array of bytes.

Parameters:

array - array of bytes

zeroTerminated - when true, a (byte) 0 is appended to the array

arena - the segment allocator for memory allocation

Returns:

the memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(char[] array,
 boolean zeroTerminated,
 Arena arena)

Allocate and initialize an (optionally NULL-terminated) array of chars.

Parameters:

array - array of chars

zeroTerminated - when true, a (char) 0 is appended to the array

arena - the segment allocator for memory allocation

Returns:

whe memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(double[] array,
 boolean zeroTerminated,
 Arena arena)

Allocate and initialize an (optionally NULL-terminated) array of doubles.

Parameters:

array - array of doubles

zeroTerminated - when true, a (double) 0 is appended to the array

arena - the segment allocator for memory allocation

Returns:

the memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(float[] array,
 boolean zeroTerminated,
 Arena arena)

Allocate and initialize an (optionally NULL-terminated) array of floats.

Parameters:

array - array of floats

zeroTerminated - when true, a (float) 0 is appended to the array

arena - the segment allocator for memory allocation

Returns:

the memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(int[] array,
 boolean zeroTerminated,
 Arena arena)

Allocate and initialize an (optionally NULL-terminated) array of floats.

Parameters:

array - array of floats

zeroTerminated - when true, a (int) 0 is appended to the array

arena - the segment allocator for memory allocation

Returns:

the memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(long[] array,
 boolean zeroTerminated,
 Arena arena)

Allocate and initialize an (optionally NULL-terminated) array of longs.

Parameters:

array - array of longs

zeroTerminated - when true, a (long) 0 is appended to the array

arena - the segment allocator for memory allocation

Returns:

the memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(short[] array,
 boolean zeroTerminated,
 Arena arena)

Allocate and initialize an (optionally NULL-terminated) array of shorts.

Parameters:

array - array of shorts

zeroTerminated - when true, a (short) 0 is appended to the array

arena - the segment allocator for memory allocation

Returns:

the memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(Proxy[] array,
 boolean zeroTerminated,
 Arena arena)

Allocate and initialize an (optionally NULL-terminated) array of pointers (from Proxy instances).

Parameters:

array - array of Proxy instances

zeroTerminated - whether to add a NULL to the array

arena - the segment allocator for memory allocation

Returns:

the memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(Proxy[] array,
 MemoryLayout layout,
 boolean zeroTerminated,
 Arena arena)

Allocate and initialize an (optionally NULL-terminated) array of structs (from Proxy instances). The actual memory segments (not the pointers) are copied into the array.

Parameters:

array - array of Proxy instances

layout - the memory layout of the object type

zeroTerminated - whether to add a NULL to the array

arena - the allocator for memory allocation

Returns:

the memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(MemorySegment[] array,
 boolean zeroTerminated,
 Arena arena)

Allocate and initialize an (optionally NULL-terminated) array of memory addresses.

Parameters:

array - array of MemorySegments

zeroTerminated - whether to add a NULL to the array

arena - the segment allocator for memory allocation

Returns:

the memory segment of the native array

intToEnumSet

public static <T extends Enum<T> & Enumeration>
EnumSet<T> intToEnumSet(Class<T> cls,
 Function<Integer,T> make,
 int bitfield)

Create an EnumSet of class `cls` from the provided bitfield

Type Parameters:

T - an enum implementing the Java-GI Enumeration interface

Parameters:

cls - the class of the enum

make - function that will construct an enum from one flag value

bitfield - the integer containing the bitfield

Returns:

an EnumSet containing the enum values as set in the bitfield

enumSetToInt

public static <T extends Enum<T> & Enumeration> int enumSetToInt(Set<T> set)

Create a bitfield from the provided Set of enums

Type Parameters:

T - an enum implementing the Java-GI Enumeration interface

Parameters:

set - the set of enums

Returns:

the resulting bitfield

getValues

public static int[] getValues(Enumeration[] array)

Convert an array of enums into an array of integers.

Parameters:

array - an array of enums

Returns:

an array containing the integer values of the provided Enumeration instances