Package org.gnome.gobject

Interface TypeValueCollectFunc

All Superinterfaces:

FunctionPointer

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
@Generated("io.github.jwharm.JavaGI")
public interface TypeValueCollectFunc
extends FunctionPointer

Functional interface declaration of the TypeValueCollectFunc callback.

See Also:

• run(org.gnome.gobject.Value, org.gnome.gobject.TypeCValue[], int)

Method Summary

Modifier and Type	Method	Description
String	run(Value value, TypeCValue[] collectValues, int collectFlags)	This function is responsible for converting the values collected from a variadic argument list into contents suitable for storage in a GValue.
default MemorySegment	toCallback(Arena arena)	Creates a native function pointer to the upcall(java.lang.foreign.MemorySegment, int, java.lang.foreign.MemorySegment, int) method.
default MemorySegment	upcall(MemorySegment value, int nCollectValues, MemorySegment collectValues, int collectFlags)	The upcall method is called from native code.

Method Details

run

String run(Value value,
 TypeCValue[] collectValues,
 int collectFlags)

This function is responsible for converting the values collected from a variadic argument list into contents suitable for storage in a GValue.

This function should setup value similar to GTypeValueInitFunc; e.g. for a string value that does not allow NULL pointers, it needs to either emit an error, or do an implicit conversion by storing an empty string.

The value passed in to this function has a zero-filled data array, so just like for GTypeValueInitFunc it is guaranteed to not contain any old contents that might need freeing.

The nCollectValues argument is the string length of the collect_format field of GTypeValueTable, and collect_values is an array of GTypeCValue with length of nCollectValues, containing the collected values according to collect_format.

The collectFlags argument provided as a hint by the caller. It may contain the flag G_VALUE_NOCOPY_CONTENTS indicating that the collected value contents may be considered ‘static’ for the duration of the value lifetime. Thus an extra copy of the contents stored in collectValues is not required for assignment to value.

For our above string example, we continue with:

if (!collect_values[0].v_pointer)
   value->data[0].v_pointer = g_strdup ("");
 else if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
   {
     value->data[0].v_pointer = collect_values[0].v_pointer;
     // keep a flag for the value_free() implementation to not free this string
     value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS;
   }
 else
   value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer);
 return NULL;
 

It should be noted, that it is generally a bad idea to follow the G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the signal emission code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementation for GTypeValueTable.collect_value() of GObject:

GObject *object = G_OBJECT (collect_values[0].v_pointer);
 g_return_val_if_fail (object != NULL,
    g_strdup_printf ("Object %p passed as invalid NULL pointer", object));
 // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types
 value->data[0].v_pointer = g_object_ref (object);
 return NULL;
 

The reference count for valid objects is always incremented, regardless of collect_flags. For invalid objects, the example returns a newly allocated string without altering value.

Upon success, collect_value() needs to return NULL. If, however, an error condition occurred, collect_value() should return a newly allocated string containing an error diagnostic.

The calling code makes no assumptions about the value contents being valid upon error returns, value is simply thrown away without further freeing. As such, it is a good idea to not allocate GValue contents prior to returning an error; however, collect_values() is not obliged to return a correctly setup value for error returns, simply because any non-NULL return is considered a fatal programming error, and further program behaviour is undefined.

upcall

default MemorySegment upcall(MemorySegment value,
 int nCollectValues,
 MemorySegment collectValues,
 int collectFlags)

The upcall method is called from native code. The parameters are marshaled and run(org.gnome.gobject.Value, org.gnome.gobject.TypeCValue[], int) is executed.

toCallback

default MemorySegment toCallback(Arena arena)

Creates a native function pointer to the upcall(java.lang.foreign.MemorySegment, int, java.lang.foreign.MemorySegment, int) method.

Specified by:

toCallback in interface FunctionPointer

Parameters:

arena - the function pointer will be allocated in this arena

Returns:

the native function pointer