Package org.javagi.interop

Class Interop

java.lang.Object

org.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(MemorySegment[] array, boolean zeroTerminated, Arena arena)	Allocate and initialize an (optionally NULL-terminated) array of memory addresses.
static MemorySegment	allocateNativeArray(String[][] strvs, boolean zeroTerminated, Arena arena)	Allocate and initialize an (optionally NULL-terminated) array of arrays of strings (a Strv-array).
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	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	allocateNativeString(String string, SegmentAllocator alloc)	Allocate a native string using SegmentAllocator.allocateFrom(String), but return MemorySegment.NULL for a null argument.
static MemorySegment	allocateUnownedString(String string)	Allocate a native string using g_malloc0().
static Arena	attachArena(Arena arena, Object instance)	Register a Cleaner action 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	checkNull(MemorySegment pointer)	When pointer is null, or pointer equals MemorySegment.NULL or reading an address from pointer returns MemorySegment.NULL, raise a NullPointerException.
static void	copy(MemorySegment src, MemorySegment dst, long size)	Reinterpret both memory segments to the specified size and copy size bytes from 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 void	freeGBytes(MemorySegment address)
static byte[]	fromGBytes(MemorySegment address)	Create a Java byte array from a GBytes
static MemorySegment	getAddress(Object o, Arena arena)
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 boolean	getBooleanFrom(MemorySegment address)	Copy a boolean value from native memory.
static boolean	getBooleanFrom(MemorySegment address, boolean free)	Copy a boolean value 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 byte	getByteFrom(MemorySegment address)	Copy a byte value from native memory.
static byte	getByteFrom(MemorySegment address, boolean free)	Copy a byte value 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 char	getCharacterFrom(MemorySegment address)	Copy a char value from native memory.
static char	getCharacterFrom(MemorySegment address, boolean free)	Copy a char value 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 double	getDoubleFrom(MemorySegment address)	Copy a double value from native memory.
static double	getDoubleFrom(MemorySegment address, boolean free)	Copy a double value 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 float[]	getFloatArrayFrom(MemorySegment address, Arena arena, boolean free)	Read a NULL-terminated array of float from native memory.
static float	getFloatFrom(MemorySegment address)	Copy a float value from native memory.
static float	getFloatFrom(MemorySegment address, boolean free)	Copy a float value 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 int	getIntegerFrom(MemorySegment address)	Copy an integer value from native memory.
static int	getIntegerFrom(MemorySegment address, boolean free)	Copy an integer value 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 long[]	getLongArrayFrom(MemorySegment address, Arena arena, boolean free)	Read a NULL-terminated array of longs from native memory.
static long	getLongFrom(MemorySegment address)	Copy a long value from native memory.
static long	getLongFrom(MemorySegment address, boolean free)	Copy a long value 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 short[]	getShortArrayFrom(MemorySegment address, Arena arena, boolean free)	Read a NULL-terminated array of shorts from native memory.
static short	getShortFrom(MemorySegment address)	Copy a short value from native memory.
static short	getShortFrom(MemorySegment address, boolean free)	Copy a short value 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.getString().
static String	getStringFrom(MemorySegment address, boolean free)	Copy a Java string from native memory using MemorySegment.getString().
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 <T extends Proxy> T[]	getStructArrayFrom(MemorySegment address, Class<T> cls, Function<MemorySegment,T> make, MemoryLayout layout)	Read a NULL-terminated 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 boolean	toBoolean(@Nullable Out<@Nullable Boolean> val)	Null-safe retrieve the value of a Boolean Out
static byte	toByte(@Nullable Out<@Nullable Byte> val)	Null-safe retrieve the value of a Byte Out
static char	toCharacter(@Nullable Out<@Nullable Character> val)	Null-safe retrieve the value of a Character Out
static double	toDouble(@Nullable Out<@Nullable Double> val)	Null-safe retrieve the value of a Double Out
static float	toFloat(@Nullable Out<@Nullable Float> val)	Null-safe retrieve the value of a Float Out
static MemorySegment	toGBytes(byte[] data)	Create a GBytes from a Java byte array
static int	toInteger(@Nullable Out<@Nullable Integer> val)	Null-safe retrieve the value of an Integer Out
static long	toLong(@Nullable Out<@Nullable Long> val)	Null-safe retrieve the value of a Long Out
static short	toShort(@Nullable Out<@Nullable Short> val)	Null-safe retrieve the value of a Short Out
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 action 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.ofShared().

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

Throws:

NullPointerException - when the pointer is null or references null

copy

public static void copy(MemorySegment src,
 MemorySegment dst,
 long size)

Reinterpret both memory segments to the specified size and copy size bytes from src into dst.

Parameters:

src - source memory segment

dst - destination memory segment

size - the number of bytes to copy

checkNull

public static void checkNull(MemorySegment pointer)

When pointer is null, or pointer equals MemorySegment.NULL or reading an address from pointer returns MemorySegment.NULL, raise a NullPointerException.

Parameters:

pointer - the pointer to check

Throws:

NullPointerException - when the check failed

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

allocateUnownedString

public static MemorySegment allocateUnownedString(String string)

Allocate a native string using g_malloc0(). Will return MemorySegment.NULL for a null argument.

Parameters:

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

Returns:

the allocated MemorySegment with the native utf8 string, that must be freed with g_free(), or MemorySegment.NULL

getStringFrom

public static String getStringFrom(MemorySegment address)

Copy a Java string from native memory using MemorySegment.getString(). 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.getString(). 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

getBooleanFrom

public static boolean getBooleanFrom(MemorySegment address)

Copy a boolean value from native memory. If the native address is NULL or contains the value 0, false is returned; else, true is returned.

Parameters:

address - the memory address of the native boolean (0 is false, any other value is true)

Returns:

the resulting boolean

getBooleanFrom

public static boolean getBooleanFrom(MemorySegment address,
 boolean free)

Copy a boolean value from native memory. If the native address is NULL or contains the value 0, false is returned; else, true is returned.

Parameters:

address - the memory address of the native boolean (0 is false, any other value is true)

free - if the address must be freed

Returns:

the resulting boolean

getByteFrom

public static byte getByteFrom(MemorySegment address)

Copy a byte value from native memory. If the native address is NULL, 0 is returned.

Parameters:

address - the memory address of the native byte

Returns:

the resulting byte

getByteFrom

public static byte getByteFrom(MemorySegment address,
 boolean free)

Copy a byte value from native memory. If the native address is NULL, 0 is returned.

Parameters:

address - the memory address of the native byte

free - if the address must be freed

Returns:

the resulting byte

getCharacterFrom

public static char getCharacterFrom(MemorySegment address)

Copy a char value from native memory. If the native address is NULL, 0 is returned.

Parameters:

address - the memory address of the native char

Returns:

the resulting char

getCharacterFrom

public static char getCharacterFrom(MemorySegment address,
 boolean free)

Copy a char value from native memory. If the native address is NULL, 0 is returned.

Parameters:

address - the memory address of the native char

free - if the address must be freed

Returns:

the resulting char

getDoubleFrom

public static double getDoubleFrom(MemorySegment address)

Copy a double value from native memory. If the native address is NULL, 0 is returned.

Parameters:

address - the memory address of the native double

Returns:

the resulting double

getDoubleFrom

public static double getDoubleFrom(MemorySegment address,
 boolean free)

Copy a double value from native memory. If the native address is NULL, 0 is returned.

Parameters:

address - the memory address of the native double

free - if the address must be freed

Returns:

the resulting double

getFloatFrom

public static float getFloatFrom(MemorySegment address)

Copy a float value from native memory. If the native address is NULL, 0 is returned.

Parameters:

address - the memory address of the native float

Returns:

the resulting float

getFloatFrom

public static float getFloatFrom(MemorySegment address,
 boolean free)

Copy a float value from native memory. If the native address is NULL, 0 is returned.

Parameters:

address - the memory address of the native float

free - if the address must be freed

Returns:

the resulting float

getIntegerFrom

public static int getIntegerFrom(MemorySegment address)

Copy an integer value from native memory. If the native address is NULL, 0 is returned.

Parameters:

address - the memory address of the native integer

Returns:

the resulting integer

getIntegerFrom

public static int getIntegerFrom(MemorySegment address,
 boolean free)

Copy an integer value from native memory. If the native address is NULL, 0 is returned.

Parameters:

address - the memory address of the native integer

free - if the address must be freed

Returns:

the resulting integer

getLongFrom

public static long getLongFrom(MemorySegment address)

Copy a long value from native memory. If the native address is NULL, 0 is returned.

Parameters:

address - the memory address of the native long

Returns:

the resulting long

getLongFrom

public static long getLongFrom(MemorySegment address,
 boolean free)

Copy a long value from native memory. If the native address is NULL, 0 is returned.

Parameters:

address - the memory address of the native long

free - if the address must be freed

Returns:

the resulting long

getShortFrom

public static short getShortFrom(MemorySegment address)

Copy a short value from native memory. If the native address is NULL, 0 is returned.

Parameters:

address - the memory address of the native short

Returns:

the resulting short

getShortFrom

public static short getShortFrom(MemorySegment address,
 boolean free)

Copy a short value from native memory. If the native address is NULL, 0 is returned.

Parameters:

address - the memory address of the native short

free - if the address must be freed

Returns:

the resulting short

getAddress

public static MemorySegment getAddress(Object o,
 Arena arena)

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

getFloatArrayFrom

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

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

Parameters:

address - address of the memory segment

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

getLongArrayFrom

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

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

Parameters:

address - address of the memory segment

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

getShortArrayFrom

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

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

Parameters:

address - address of the memory segment

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,
 Class<T> cls,
 Function<MemorySegment,T> make,
 MemoryLayout layout)

Read a NULL-terminated array of structs from native memory, create a Proxy instance for each struct, and return an array of Proxy instances. The array must be terminated by a completely null-filled struct.

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

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(String[][] strvs,
 boolean zeroTerminated,
 Arena arena)

Allocate and initialize an (optionally NULL-terminated) array of arrays of strings (a Strv-array).

Parameters:

strvs - the array of String arrays

zeroTerminated - whether to add a NULL to the array. The embedded arrays are always NULL-terminated.

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 struct contents (not the pointers) are copied into the array.

Parameters:

array - array of Proxy instances

layout - the memory layout of the struct

zeroTerminated - whether to terminate the array by a struct with all members being NULL

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. Undefined flags are logged (with level LogLevelFlags.LEVEL_WARNING) and ignored.

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

toGBytes

public static MemorySegment toGBytes(byte[] data)

Create a GBytes from a Java byte array

Parameters:

data - the Java byte array

Returns:

the GBytes

fromGBytes

public static byte[] fromGBytes(MemorySegment address)

Create a Java byte array from a GBytes

Parameters:

address - the memory address of the GBytes

Returns:

the Java byte array

freeGBytes

public static void freeGBytes(MemorySegment address)

toBoolean

public static boolean toBoolean(@Nullable
 @Nullable Out<@Nullable Boolean> val)

Null-safe retrieve the value of a Boolean Out

Parameters:

val - a possibly null Out<Boolean>

Returns:

the boolean value, or false when null

toByte

public static byte toByte(@Nullable
 @Nullable Out<@Nullable Byte> val)

Null-safe retrieve the value of a Byte Out

Parameters:

val - a possibly null Out<Byte>

Returns:

the byte value, or 0 when null

toCharacter

public static char toCharacter(@Nullable
 @Nullable Out<@Nullable Character> val)

Null-safe retrieve the value of a Character Out

Parameters:

val - a possibly null Out<Character>

Returns:

the char value, or 0 when null

toDouble

public static double toDouble(@Nullable
 @Nullable Out<@Nullable Double> val)

Null-safe retrieve the value of a Double Out

Parameters:

val - a possibly null Out<Double>

Returns:

the double value, or 0 when null

toFloat

public static float toFloat(@Nullable
 @Nullable Out<@Nullable Float> val)

Null-safe retrieve the value of a Float Out

Parameters:

val - a possibly null Out<Float>

Returns:

the float value, or 0 when null

toInteger

public static int toInteger(@Nullable
 @Nullable Out<@Nullable Integer> val)

Null-safe retrieve the value of an Integer Out

Parameters:

val - a possibly null Out<Integer>

Returns:

the int value, or 0 when null

toLong

public static long toLong(@Nullable
 @Nullable Out<@Nullable Long> val)

Null-safe retrieve the value of a Long Out

Parameters:

val - a possibly null Out<Long>

Returns:

the long value, or 0 when null

toShort

public static short toShort(@Nullable
 @Nullable Out<@Nullable Short> val)

Null-safe retrieve the value of a Short Out

Parameters:

val - a possibly null Out<Short>

Returns:

the short value, or 0 when null