Package org.javagi.interop

Class Interop

java.lang.Object

org.javagi.interop.Interop

@NullMarked
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 @Nullable [] array, boolean zeroTerminated, SegmentAllocator alloc)	Convert a boolean[] array into an int[] array, and calls allocateNativeArray(int[], boolean, SegmentAllocator).
static MemorySegment	allocateNativeArray(byte @Nullable [] array, boolean zeroTerminated, SegmentAllocator alloc)	Allocate and initialize an (optionally NULL-terminated) array of bytes.
static MemorySegment	allocateNativeArray(char @Nullable [] array, boolean zeroTerminated, SegmentAllocator alloc)	Allocate and initialize an (optionally NULL-terminated) array of chars.
static MemorySegment	allocateNativeArray(double @Nullable [] array, boolean zeroTerminated, SegmentAllocator alloc)	Allocate and initialize an (optionally NULL-terminated) array of doubles.
static MemorySegment	allocateNativeArray(float @Nullable [] array, boolean zeroTerminated, SegmentAllocator alloc)	Allocate and initialize an (optionally NULL-terminated) array of floats.
static MemorySegment	allocateNativeArray(int @Nullable [] array, boolean zeroTerminated, SegmentAllocator alloc)	Allocate and initialize an (optionally NULL-terminated) array of floats.
static MemorySegment	allocateNativeArray(long @Nullable [] array, boolean zeroTerminated, SegmentAllocator alloc)	Allocate and initialize an (optionally NULL-terminated) array of longs.
static MemorySegment	allocateNativeArray(short @Nullable [] array, boolean zeroTerminated, SegmentAllocator alloc)	Allocate and initialize an (optionally NULL-terminated) array of shorts.
static MemorySegment	allocateNativeArray(@Nullable String @Nullable [] @Nullable [] strvs, boolean zeroTerminated, SegmentAllocator alloc, SegmentAllocator elementAlloc)	Allocate and initialize an (optionally NULL-terminated) array of arrays of strings (a Strv-array).
static MemorySegment	allocateNativeArray(@Nullable String @Nullable [] strings, boolean zeroTerminated, SegmentAllocator alloc)	Allocate and initialize an (optionally NULL-terminated) array of strings (NULL-terminated utf8 char*).
static MemorySegment	allocateNativeArray(@Nullable MemorySegment @Nullable [] array, boolean zeroTerminated, SegmentAllocator alloc)	Allocate and initialize an (optionally NULL-terminated) array of memory addresses.
static MemorySegment	allocateNativeArray(@Nullable Proxy @Nullable [] array, boolean zeroTerminated, SegmentAllocator alloc)	Allocate and initialize an (optionally NULL-terminated) array of pointers (from Proxy instances).
static MemorySegment	allocateNativeArray(@Nullable Proxy @Nullable [] array, MemoryLayout layout, boolean zeroTerminated, SegmentAllocator alloc)	Allocate and initialize an (optionally NULL-terminated) array of structs (from Proxy instances).
static MemorySegment	allocateNativeString(@Nullable String string, SegmentAllocator alloc)	Allocate a native string using SegmentAllocator.allocateFrom(String), but return MemorySegment.NULL for a null argument.
static MemorySegment	allocateUnownedString(@Nullable 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(@Nullable 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(@Nullable 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 int	enumSetToInt(@Nullable Set<? extends Enumeration> set)	Create a bitfield from the provided Set of enums
static void	freeGBytes(MemorySegment address)	Free a GBytes with g_bytes_unref()
static void	freeGString(MemorySegment address)	Free a GString (including the character data).
static byte @Nullable []	fromGBytes(MemorySegment address)	Create a Java byte array from a GBytes
static @Nullable String	fromGString(MemorySegment address, TransferOwnership transfer)	Marshal a GString to a Java String.
static Object	functionNotFound(Object[] args)	A MethodHandle to this function is returned when a downcall handle was requested for a foreign function that was not found by the linker.
static MemorySegment	getAddress(@Nullable Object o, SegmentAllocator alloc)	Allocate memory for this object.
static MemorySegment @Nullable []	getAddressArrayFrom(MemorySegment address, int length, TransferOwnership transfer)	Read an array of pointers with the requested length from native memory.
static MemorySegment @Nullable []	getAddressArrayFrom(MemorySegment address, TransferOwnership transfer)	Read an array of pointers from a NULL-terminated array in native memory.
static <T> T @Nullable []	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 @Nullable []	getBooleanArrayFrom(MemorySegment address, long length, Arena arena, TransferOwnership transfer)	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, TransferOwnership transfer)	Copy a boolean value from native memory.
static byte @Nullable []	getByteArrayFrom(MemorySegment address, long length, Arena arena, TransferOwnership transfer)	Read an array of bytes with the requested length from native memory.
static byte @Nullable []	getByteArrayFrom(MemorySegment address, Arena arena, TransferOwnership transfer)	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, TransferOwnership transfer)	Copy a byte value from native memory.
static char @Nullable []	getCharacterArrayFrom(MemorySegment address, long length, Arena arena, TransferOwnership transfer)	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, TransferOwnership transfer)	Copy a char value from native memory.
static double @Nullable []	getDoubleArrayFrom(MemorySegment address, long length, Arena arena, TransferOwnership transfer)	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, TransferOwnership transfer)	Copy a double value from native memory.
static float @Nullable []	getFloatArrayFrom(MemorySegment address, long length, Arena arena, TransferOwnership transfer)	Read an array of floats with the requested length from native memory.
static float @Nullable []	getFloatArrayFrom(MemorySegment address, Arena arena, TransferOwnership transfer)	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, TransferOwnership transfer)	Copy a float value from native memory.
static int @Nullable []	getIntegerArrayFrom(MemorySegment address, long length, Arena arena, TransferOwnership transfer)	Read an array of integers with the requested length from native memory.
static int @Nullable []	getIntegerArrayFrom(MemorySegment address, Arena arena, TransferOwnership transfer)	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, TransferOwnership transfer)	Copy an integer value from native memory.
static long @Nullable []	getLongArrayFrom(MemorySegment address, long length, Arena arena, TransferOwnership transfer)	Read an array of longs with the requested length from native memory.
static long @Nullable []	getLongArrayFrom(MemorySegment address, Arena arena, TransferOwnership transfer)	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, TransferOwnership transfer)	Copy a long value from native memory.
static <T extends Proxy> T @Nullable []	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 @Nullable []	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 @Nullable []	getShortArrayFrom(MemorySegment address, long length, Arena arena, TransferOwnership transfer)	Read an array of shorts with the requested length from native memory.
static short @Nullable []	getShortArrayFrom(MemorySegment address, Arena arena, TransferOwnership transfer)	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, TransferOwnership transfer)	Copy a short value from native memory.
static @Nullable String @Nullable []	getStringArrayFrom(MemorySegment address, int length, TransferOwnership transfer)	Read an array of Strings with the requested length from native memory.
static @Nullable String @Nullable []	getStringArrayFrom(MemorySegment address, TransferOwnership transfer)	Read an array of Strings from a NULL-terminated array in native memory.
static @Nullable String	getStringFrom(MemorySegment address)	Copy a Java string from native memory using MemorySegment.getString().
static @Nullable String	getStringFrom(MemorySegment address, TransferOwnership transfer)	Copy a Java string from native memory using MemorySegment.getString().
static <T extends Proxy> T @Nullable []	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 @Nullable []	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 @Nullable String @Nullable [] @Nullable []	getStrvArrayFrom(MemorySegment address, int length, TransferOwnership transfer)	Read length arrays of Strings from native memory.
static @Nullable String @Nullable [] @Nullable []	getStrvArrayFrom(MemorySegment address, TransferOwnership transfer)	Read NULL-terminated arrays of Strings from a NULL-terminated array in native memory.
static @Nullable Type	getType(@Nullable String getTypeFunction)	Get a GType by executing the provided get-type function.
static int @Nullable []	getValues(Enumeration @Nullable [] 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 SegmentAllocator	mallocAllocator()	Create a SegmentAllocator that uses malloc() to allocate memory.
static MemorySegment	newGArray(int elementSize)	Create a new empty GArray.
static MemorySegment	newGArray(MemorySegment data, long length, long elementSize)	Create a new GArray with the provided data.
static MemorySegment	newGByteArray()	Create a new empty GByteArray.
static MemorySegment	newGPtrArray()	Create a new empty GPtrArray.
static MemorySegment	newGPtrArray(MemorySegment data, long length)	Create a new empty GPtrArray.
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 @Nullable [] data)	Create a GBytes from a Java byte array
static MemorySegment	toGString(@Nullable String string)	Marshal a Java String to a GString.
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

functionNotFound

public static Object functionNotFound(Object[] args)

A MethodHandle to this function is returned when a downcall handle was requested for a foreign function that was not found by the linker.

Parameters:

args - ignored

Returns:

ignored

Throws:

InteropException - always thrown

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

Throws:

NullPointerException - when symbol is null

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

mallocAllocator

public static SegmentAllocator mallocAllocator()

Create a SegmentAllocator that uses malloc() to allocate memory.

The returned allocator currently calls GLib.tryMalloc0(long), so the allocated memory is zero-initialized, but they may change in the future.

It is up to the user of this allocator to release the allocated memory, for example with GLib.free(java.lang.foreign.MemorySegment).

Returns:

the newly created SegmentAllocator

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(@Nullable 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(@Nullable 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 @Nullable Type getType(@Nullable 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(@Nullable 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(@Nullable 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 @Nullable 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 @Nullable String getStringFrom(MemorySegment address,
 TransferOwnership transfer)

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*)

transfer - ownership transfer

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,
 TransferOwnership transfer)

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)

transfer - ownership transfer

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,
 TransferOwnership transfer)

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

transfer - ownership transfer

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,
 TransferOwnership transfer)

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

transfer - ownership transfer

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,
 TransferOwnership transfer)

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

transfer - ownership transfer

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,
 TransferOwnership transfer)

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

transfer - ownership transfer

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,
 TransferOwnership transfer)

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

transfer - ownership transfer

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,
 TransferOwnership transfer)

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

transfer - ownership transfer

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,
 TransferOwnership transfer)

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

transfer - ownership transfer

Returns:

the resulting short

getAddress

public static MemorySegment getAddress(@Nullable Object o,
 SegmentAllocator alloc)

Allocate memory for this object. Java-GI must be able to marshal the object, which means it must implement the Proxy interface, a primitive type, a String, an Enumeration, a Set<Enumeration>, or an existing MemorySegment (returned as-is).

For most primitive types, the value is written in a newly allocated memory segment. Integers however are returned as an address; for the reason why, read the GLib documentation for the GINT_TO_POINTER and GPOINTER_TO_INT macros. The same is done for GTypes (for compatibility with GTYPE_TO_POINTER and vice versa).

Parameters:

o - the object to allocate memory for

alloc - the memory allocator

Returns:

the allocated memory holding the object

getStringArrayFrom

public static @Nullable String @Nullable [] getStringArrayFrom(MemorySegment address,
 int length,
 TransferOwnership transfer)

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

Parameters:

address - address of the memory segment

length - length of the array

transfer - ownership transfer

Returns:

array of Strings

getStringArrayFrom

public static @Nullable String @Nullable [] getStringArrayFrom(MemorySegment address,
 TransferOwnership transfer)

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

Parameters:

address - address of the memory segment

transfer - ownership transfer

Returns:

array of Strings

getStrvArrayFrom

public static @Nullable String @Nullable [] @Nullable [] getStrvArrayFrom(MemorySegment address,
 TransferOwnership transfer)

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

Parameters:

address - address of the memory segment

transfer - ownership transfer

Returns:

two-dimensional array of Strings

getStrvArrayFrom

public static @Nullable String @Nullable [] @Nullable [] getStrvArrayFrom(MemorySegment address,
 int length,
 TransferOwnership transfer)

Read length arrays of Strings from native memory.

Parameters:

address - address of the memory segment

length - the length of the array

transfer - ownership transfer

Returns:

two-dimensional array of Strings

getAddressArrayFrom

public static MemorySegment @Nullable [] getAddressArrayFrom(MemorySegment address,
 int length,
 TransferOwnership transfer)

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

Parameters:

address - address of the memory segment

length - length of the array

transfer - ownership transfer

Returns:

array of pointers

getAddressArrayFrom

public static MemorySegment @Nullable [] getAddressArrayFrom(MemorySegment address,
 TransferOwnership transfer)

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

Parameters:

address - address of the memory segment

transfer - ownership transfer

Returns:

array of pointers

getBooleanArrayFrom

public static boolean @Nullable [] getBooleanArrayFrom(MemorySegment address,
 long length,
 Arena arena,
 TransferOwnership transfer)

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

transfer - ownership transfer

Returns:

array of booleans

getByteArrayFrom

public static byte @Nullable [] getByteArrayFrom(MemorySegment address,
 long length,
 Arena arena,
 TransferOwnership transfer)

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

transfer - ownership transfer

Returns:

array of bytes

getByteArrayFrom

public static byte @Nullable [] getByteArrayFrom(MemorySegment address,
 Arena arena,
 TransferOwnership transfer)

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

Parameters:

address - address of the memory segment

arena - the memory scope

transfer - ownership transfer

Returns:

array of bytes

getCharacterArrayFrom

public static char @Nullable [] getCharacterArrayFrom(MemorySegment address,
 long length,
 Arena arena,
 TransferOwnership transfer)

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

transfer - ownership transfer

Returns:

array of chars

getDoubleArrayFrom

public static double @Nullable [] getDoubleArrayFrom(MemorySegment address,
 long length,
 Arena arena,
 TransferOwnership transfer)

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

transfer - ownership transfer

Returns:

array of doubles

getFloatArrayFrom

public static float @Nullable [] getFloatArrayFrom(MemorySegment address,
 long length,
 Arena arena,
 TransferOwnership transfer)

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

transfer - ownership transfer

Returns:

array of floats

getFloatArrayFrom

public static float @Nullable [] getFloatArrayFrom(MemorySegment address,
 Arena arena,
 TransferOwnership transfer)

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

Parameters:

address - address of the memory segment

arena - the memory scope

transfer - ownership transfer

Returns:

array of floats

getIntegerArrayFrom

public static int @Nullable [] getIntegerArrayFrom(MemorySegment address,
 long length,
 Arena arena,
 TransferOwnership transfer)

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

transfer - ownership transfer

Returns:

array of integers

getIntegerArrayFrom

public static int @Nullable [] getIntegerArrayFrom(MemorySegment address,
 Arena arena,
 TransferOwnership transfer)

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

Parameters:

address - address of the memory segment

arena - the memory scope

transfer - ownership transfer

Returns:

array of integers

getLongArrayFrom

public static long @Nullable [] getLongArrayFrom(MemorySegment address,
 long length,
 Arena arena,
 TransferOwnership transfer)

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

transfer - ownership transfer

Returns:

array of longs

getLongArrayFrom

public static long @Nullable [] getLongArrayFrom(MemorySegment address,
 Arena arena,
 TransferOwnership transfer)

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

Parameters:

address - address of the memory segment

arena - the memory scope

transfer - ownership transfer

Returns:

array of longs

getShortArrayFrom

public static short @Nullable [] getShortArrayFrom(MemorySegment address,
 long length,
 Arena arena,
 TransferOwnership transfer)

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

transfer - ownership transfer

Returns:

array of shorts

getShortArrayFrom

public static short @Nullable [] getShortArrayFrom(MemorySegment address,
 Arena arena,
 TransferOwnership transfer)

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

Parameters:

address - address of the memory segment

arena - the memory scope

transfer - ownership transfer

Returns:

array of shorts

getProxyArrayFrom

public static <T extends Proxy> T @Nullable [] 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 @Nullable [] 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 @Nullable [] 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 @Nullable [] 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 @Nullable [] 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(@Nullable String @Nullable [] strings,
 boolean zeroTerminated,
 SegmentAllocator alloc)

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

alloc - the segment allocator for the array

Returns:

the memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(@Nullable String @Nullable [] @Nullable [] strvs,
 boolean zeroTerminated,
 SegmentAllocator alloc,
 SegmentAllocator elementAlloc)

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.

alloc - the segment allocator for the array

elementAlloc - the segment allocator for the array elements

Returns:

the memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(boolean @Nullable [] array,
 boolean zeroTerminated,
 SegmentAllocator alloc)

Convert a boolean[] array into an int[] array, and calls allocateNativeArray(int[], boolean, SegmentAllocator). 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

alloc - the segment allocator for memory allocation

Returns:

The memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(byte @Nullable [] array,
 boolean zeroTerminated,
 SegmentAllocator alloc)

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

alloc - the segment allocator for memory allocation

Returns:

the memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(char @Nullable [] array,
 boolean zeroTerminated,
 SegmentAllocator alloc)

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

alloc - the segment allocator for memory allocation

Returns:

whe memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(double @Nullable [] array,
 boolean zeroTerminated,
 SegmentAllocator alloc)

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

alloc - the segment allocator for memory allocation

Returns:

the memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(float @Nullable [] array,
 boolean zeroTerminated,
 SegmentAllocator alloc)

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

alloc - the segment allocator for memory allocation

Returns:

the memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(int @Nullable [] array,
 boolean zeroTerminated,
 SegmentAllocator alloc)

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

alloc - the segment allocator for memory allocation

Returns:

the memory segment of the native array

newGArray

public static MemorySegment newGArray(int elementSize)

Create a new empty GArray.

Parameters:

elementSize - element size

Returns:

the newly created GArray

newGArray

public static MemorySegment newGArray(MemorySegment data,
 long length,
 long elementSize)

Create a new GArray with the provided data.

Parameters:

data - memory segment containing the array data

length - number of array elements

elementSize - element size

Returns:

the newly created GArray

newGByteArray

public static MemorySegment newGByteArray()

Create a new empty GByteArray.

Returns:

the newly create GByteArray

newGPtrArray

public static MemorySegment newGPtrArray()

Create a new empty GPtrArray.

Returns:

the newly create GPtrArray

newGPtrArray

public static MemorySegment newGPtrArray(MemorySegment data,
 long length)

Create a new empty GPtrArray.

Returns:

the newly create GPtrArray

allocateNativeArray

public static MemorySegment allocateNativeArray(long @Nullable [] array,
 boolean zeroTerminated,
 SegmentAllocator alloc)

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

alloc - the segment allocator for memory allocation

Returns:

the memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(short @Nullable [] array,
 boolean zeroTerminated,
 SegmentAllocator alloc)

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

alloc - the segment allocator for memory allocation

Returns:

the memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(@Nullable Proxy @Nullable [] array,
 boolean zeroTerminated,
 SegmentAllocator alloc)

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

alloc - the segment allocator for memory allocation

Returns:

the memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(@Nullable Proxy @Nullable [] array,
 MemoryLayout layout,
 boolean zeroTerminated,
 SegmentAllocator alloc)

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

alloc - the allocator for memory allocation

Returns:

the memory segment of the native array

allocateNativeArray

public static MemorySegment allocateNativeArray(@Nullable MemorySegment @Nullable [] array,
 boolean zeroTerminated,
 SegmentAllocator alloc)

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

alloc - 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 int enumSetToInt(@Nullable Set<? extends Enumeration> set)

Create a bitfield from the provided Set of enums

Parameters:

set - the set of enums

Returns:

the resulting bitfield

getValues

public static int @Nullable [] getValues(Enumeration @Nullable [] 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 @Nullable [] data)

Create a GBytes from a Java byte array

Parameters:

data - the Java byte array

Returns:

the GBytes

fromGBytes

public static byte @Nullable [] 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)

Free a GBytes with g_bytes_unref()

Parameters:

address - the address of the GBytes to free

fromGString

public static @Nullable String fromGString(MemorySegment address,
 TransferOwnership transfer)

Marshal a GString to a Java String.

Parameters:

address - address of a GString

transfer - if not NONE, the GString is freed

Returns:

the Java String

toGString

public static MemorySegment toGString(@Nullable String string)

Marshal a Java String to a GString.

Parameters:

string - a Java String

Returns:

the address of the GString

freeGString

public static void freeGString(MemorySegment address)

Free a GString (including the character data).

Parameters:

address - address of a GString

toBoolean

public static boolean toBoolean(@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 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 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 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 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 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 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 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