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 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
      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(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 <T> MemorySegment allocateNativeArray(@Nullable Alias<T> @Nullable [] aliases, boolean zeroTerminated, SegmentAllocator alloc)
      Allocate and initialize an (optionally NULL-terminated) array with the values taken from Alias values, i.e. typedefs of primitive values, Strings or memory segments.
      Parameters:
      aliases - array of aliased values
      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 [] 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>> 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>> int enumSetToInt(@Nullable Set<T> 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