Package org.gnome.gobject

Class Closure

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.gobject.Closure

All Implemented Interfaces:

Proxy

Direct Known Subclasses:

JavaClosure

@Generated("io.github.jwharm.JavaGI")
public class Closure
extends ProxyInstance

A GClosure represents a callback supplied by the programmer.

It will generally comprise a function of some kind and a marshaller used to call it. It is the responsibility of the marshaller to convert the arguments for the invocation from GValues into a suitable form, perform the callback on the converted arguments, and transform the return value back into a GValue.

In the case of C programs, a closure usually just holds a pointer to a function and maybe a data argument, and the marshaller converts between GValue and native C types. The GObject library provides the GCClosure type for this purpose. Bindings for other languages need marshallers which convert between GValues and suitable representations in the runtime of the language in order to use functions written in that language as callbacks. Use g_closure_set_marshal() to set the marshaller on such a custom closure implementation.

Within GObject, closures play an important role in the implementation of signals. When a signal is registered, the cMarshaller argument to g_signal_new() specifies the default C marshaller for any closure which is connected to this signal. GObject provides a number of C marshallers for this purpose, see the g_cclosure_marshal_*() functions. Additional C marshallers can be generated with the [glib-genmarshal][glib-genmarshal] utility. Closures can be explicitly connected to signals with g_signal_connect_closure(), but it usually more convenient to let GObject create a closure automatically by using one of the g_signal_connect_*() functions which take a callback function/user data pair.

Using closures has a number of important advantages over a simple callback function/data pointer combination:

• Closures allow the callee to get the types of the callback parameters, which means that language bindings don't have to write individual glue for each callback type.

• The reference counting of GClosure makes it easy to handle reentrancy right; if a callback is removed while it is being invoked, the closure and its parameters won't be freed until the invocation finishes.

• g_closure_invalidate() and invalidation notifiers allow callbacks to be automatically removed when the objects they point to go away.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Closure.MarshalCallback	Functional interface declaration of the MarshalCallback callback.

Constructor Summary

Constructors

Constructor	Description
Closure()	Allocate a new Closure.
Closure(Arena arena)	Allocate a new Closure.
Closure(MemorySegment address)	Create a Closure proxy instance for the provided memory address.
Closure(Closure.MarshalCallback marshal, MemorySegment data, ClosureNotifyData notifiers)	Allocate a new Closure with the fields set to the provided values.
Closure(Closure.MarshalCallback marshal, MemorySegment data, ClosureNotifyData notifiers, Arena arena)	Allocate a new Closure with the fields set to the provided values.

Method Summary

Modifier and Type	Method	Description
void	addFinalizeNotifier(@Nullable MemorySegment notifyData, ClosureNotify notifyFunc)	Registers a finalization notifier which will be called when the reference count of this Closure goes down to 0.
void	addInvalidateNotifier(@Nullable MemorySegment notifyData, ClosureNotify notifyFunc)	Registers an invalidation notifier which will be called when the this Closure is invalidated with g_closure_invalidate().
void	addMarshalGuards(@Nullable MemorySegment preMarshalData, ClosureNotify preMarshalNotify, ClosureNotify postMarshalNotify)	Adds a pair of notifiers which get invoked before and after the closure callback, respectively.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
static Type	getType()	Get the GType of the Closure class
void	invalidate()	Sets a flag on the closure to indicate that its calling environment has become invalid, and thus causes any future invocations of g_closure_invoke() on this this Closure to be ignored.
void	invoke(@Nullable Value returnValue, Value[] paramValues, @Nullable MemorySegment invocationHint)	Invokes the closure, i.e.
static Closure	object(int sizeofClosure, GObject object)	A variant of g_closure_new_simple() which stores object in the data field of the closure and calls g_object_watch_closure() on object and the created closure.
void	overrideMarshal(Closure.MarshalCallback marshal, Arena _arena)	Write a value in the field marshal.
MemorySegment	readData()	Read the value of the field data.
ClosureNotifyData	readNotifiers()	Read the value of the field notifiers.
Closure	ref()	Increments the reference count on a closure to force it staying alive while the caller holds a pointer to it.
void	removeFinalizeNotifier(@Nullable MemorySegment notifyData, ClosureNotify notifyFunc)	Removes a finalization notifier.
void	removeInvalidateNotifier(@Nullable MemorySegment notifyData, ClosureNotify notifyFunc)	Removes an invalidation notifier.
void	setMarshal(ClosureMarshal marshal)	Sets the marshaller of this Closure.
void	setMetaMarshal(@Nullable MemorySegment marshalData, ClosureMarshal metaMarshal)	Sets the meta marshaller of this Closure.
static Closure	simple(int sizeofClosure, @Nullable MemorySegment data)	Allocates a struct of the given size and initializes the initial part as a GClosure.
void	sink()	Takes over the initial ownership of a closure.
void	unref()	Decrements the reference count of a closure after it was previously incremented by the same caller.
void	writeData(MemorySegment data)	Write a value in the field data.
void	writeNotifiers(ClosureNotifyData notifiers)	Write a value in the field notifiers.

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

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

Constructor Details

Closure

public Closure(MemorySegment address)

Create a Closure proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Closure

public Closure(Arena arena)

Allocate a new Closure.

Parameters:

arena - to control the memory allocation scope

Closure

public Closure()

Allocate a new Closure. The memory is allocated with Arena.ofAuto().

Closure

public Closure(Closure.MarshalCallback marshal,
 MemorySegment data,
 ClosureNotifyData notifiers,
 Arena arena)

Allocate a new Closure with the fields set to the provided values.

Parameters:

marshal - callback function for the field marshal

data - value for the field data

notifiers - value for the field notifiers

arena - to control the memory allocation scope

Closure

public Closure(Closure.MarshalCallback marshal,
 MemorySegment data,
 ClosureNotifyData notifiers)

Allocate a new Closure with the fields set to the provided values. The memory is allocated with Arena.ofAuto().

Parameters:

marshal - callback function for the field marshal

data - value for the field data

notifiers - value for the field notifiers

Method Details

getType

public static Type getType()

Get the GType of the Closure class

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

overrideMarshal

public void overrideMarshal(Closure.MarshalCallback marshal,
 Arena _arena)

Write a value in the field marshal.

Parameters:

marshal - The new value for the field marshal

_arena - to control the memory allocation scope

readData

public MemorySegment readData()

Read the value of the field data.

Returns:

The value of the field data

writeData

public void writeData(MemorySegment data)

Write a value in the field data.

Parameters:

data - The new value for the field data

readNotifiers

public ClosureNotifyData readNotifiers()

Read the value of the field notifiers.

Returns:

The value of the field notifiers

writeNotifiers

public void writeNotifiers(ClosureNotifyData notifiers)

Write a value in the field notifiers.

Parameters:

notifiers - The new value for the field notifiers

object

public static Closure object(int sizeofClosure,
 GObject object)

A variant of g_closure_new_simple() which stores object in the data field of the closure and calls g_object_watch_closure() on object and the created closure. This function is mainly useful when implementing new types of closures.

Parameters:

sizeofClosure - the size of the structure to allocate, must be at least sizeof (GClosure)

object - a GObject pointer to store in the data field of the newly allocated GClosure

Returns:

a newly allocated GClosure

simple

public static Closure simple(int sizeofClosure,
 @Nullable
 @Nullable MemorySegment data)

Allocates a struct of the given size and initializes the initial part as a GClosure.

This function is mainly useful when implementing new types of closures:

typedef struct _MyClosure MyClosure;
 struct _MyClosure
 {
   GClosure closure;
   // extra data goes here
 };

 static void
 my_closure_finalize (gpointer  notify_data,
                      GClosure *closure)
 {
   MyClosure *my_closure = (MyClosure *)closure;

   // free extra data here
 }

 MyClosure *my_closure_new (gpointer data)
 {
   GClosure *closure;
   MyClosure *my_closure;

   closure = g_closure_new_simple (sizeof (MyClosure), data);
   my_closure = (MyClosure *) closure;

   // initialize extra data here

   g_closure_add_finalize_notifier (closure, notify_data,
                                    my_closure_finalize);
   return my_closure;
 }
 

Parameters:

sizeofClosure - the size of the structure to allocate, must be at least sizeof (GClosure)

data - data to store in the data field of the newly allocated GClosure

Returns:

a floating reference to a new GClosure

addFinalizeNotifier

public void addFinalizeNotifier(@Nullable
 @Nullable MemorySegment notifyData,
 ClosureNotify notifyFunc)

Registers a finalization notifier which will be called when the reference count of this Closure goes down to 0.

Multiple finalization notifiers on a single closure are invoked in unspecified order. If a single call to g_closure_unref() results in the closure being both invalidated and finalized, then the invalidate notifiers will be run before the finalize notifiers.

Parameters:

notifyData - data to pass to notifyFunc

notifyFunc - the callback function to register

addInvalidateNotifier

public void addInvalidateNotifier(@Nullable
 @Nullable MemorySegment notifyData,
 ClosureNotify notifyFunc)

Registers an invalidation notifier which will be called when the this Closure is invalidated with g_closure_invalidate().

Invalidation notifiers are invoked before finalization notifiers, in an unspecified order.

Parameters:

notifyData - data to pass to notifyFunc

notifyFunc - the callback function to register

addMarshalGuards

public void addMarshalGuards(@Nullable
 @Nullable MemorySegment preMarshalData,
 ClosureNotify preMarshalNotify,
 ClosureNotify postMarshalNotify)

Adds a pair of notifiers which get invoked before and after the closure callback, respectively.

This is typically used to protect the extra arguments for the duration of the callback. See g_object_watch_closure() for an example of marshal guards.

Parameters:

preMarshalData - data to pass to preMarshalNotify

preMarshalNotify - a function to call before the closure callback

postMarshalNotify - a function to call after the closure callback

invalidate

public void invalidate()

Sets a flag on the closure to indicate that its calling environment has become invalid, and thus causes any future invocations of g_closure_invoke() on this this Closure to be ignored.

Also, invalidation notifiers installed on the closure will be called at this point. Note that unless you are holding a reference to the closure yourself, the invalidation notifiers may unref the closure and cause it to be destroyed, so if you need to access the closure after calling g_closure_invalidate(), make sure that you've previously called g_closure_ref().

Note that g_closure_invalidate() will also be called when the reference count of a closure drops to zero (unless it has already been invalidated before).

invoke

public void invoke(@Nullable
 @Nullable Value returnValue,
 Value[] paramValues,
 @Nullable
 @Nullable MemorySegment invocationHint)

Invokes the closure, i.e. executes the callback represented by the this Closure.

Parameters:

returnValue - a GValue to store the return value. May be null if the callback of this Closure doesn't return a value.

paramValues - an array of GValues holding the arguments on which to invoke the callback of this Closure

invocationHint - a context-dependent invocation hint

ref

public Closure ref()

Increments the reference count on a closure to force it staying alive while the caller holds a pointer to it.

Returns:

The this Closure passed in, for convenience

removeFinalizeNotifier

public void removeFinalizeNotifier(@Nullable
 @Nullable MemorySegment notifyData,
 ClosureNotify notifyFunc)

Removes a finalization notifier.

Notice that notifiers are automatically removed after they are run.

Parameters:

notifyData - data which was passed to g_closure_add_finalize_notifier() when registering notifyFunc

notifyFunc - the callback function to remove

removeInvalidateNotifier

public void removeInvalidateNotifier(@Nullable
 @Nullable MemorySegment notifyData,
 ClosureNotify notifyFunc)

Removes an invalidation notifier.

Notice that notifiers are automatically removed after they are run.

Parameters:

notifyData - data which was passed to g_closure_add_invalidate_notifier() when registering notifyFunc

notifyFunc - the callback function to remove

setMarshal

public void setMarshal(ClosureMarshal marshal)

Sets the marshaller of this Closure.

The marshal_data of marshal provides a way for a meta marshaller to provide additional information to the marshaller.

For GObject's C predefined marshallers (the g_cclosure_marshal_*() functions), what it provides is a callback function to use instead of this Closure->callback.

See also: g_closure_set_meta_marshal()

Parameters:

marshal - a GClosureMarshal function

setMetaMarshal

public void setMetaMarshal(@Nullable
 @Nullable MemorySegment marshalData,
 ClosureMarshal metaMarshal)

Sets the meta marshaller of this Closure.

A meta marshaller wraps the this Closure's marshal and modifies the way it is called in some fashion. The most common use of this facility is for C callbacks.

The same marshallers (generated by [glib-genmarshal][glib-genmarshal]), are used everywhere, but the way that we get the callback function differs. In most cases we want to use the this Closure's callback, but in other cases we want to use some different technique to retrieve the callback function.

For example, class closures for signals (see g_signal_type_cclosure_new()) retrieve the callback function from a fixed offset in the class structure. The meta marshaller retrieves the right callback and passes it to the marshaller as the marshalData argument.

Parameters:

marshalData - context-dependent data to pass to metaMarshal

metaMarshal - a GClosureMarshal function

sink

public void sink()

Takes over the initial ownership of a closure.

Each closure is initially created in a "floating" state, which means that the initial reference count is not owned by any caller.

This function checks to see if the object is still floating, and if so, unsets the floating state and decreases the reference count. If the closure is not floating, g_closure_sink() does nothing.

The reason for the existence of the floating state is to prevent cumbersome code sequences like:

closure = g_cclosure_new (cb_func, cb_data);
 g_source_set_closure (source, closure);
 g_closure_unref (closure); // GObject doesn't really need this
 

Because g_source_set_closure() (and similar functions) take ownership of the initial reference count, if it is unowned, we instead can write:

g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
 

Generally, this function is used together with g_closure_ref(). An example of storing a closure for later notification looks like:

static GClosure *notify_closure = NULL;
 void
 foo_notify_set_closure (GClosure *closure)
 {
   if (notify_closure)
     g_closure_unref (notify_closure);
   notify_closure = closure;
   if (notify_closure)
     {
       g_closure_ref (notify_closure);
       g_closure_sink (notify_closure);
     }
 }
 

Because g_closure_sink() may decrement the reference count of a closure (if it hasn't been called on this Closure yet) just like g_closure_unref(), g_closure_ref() should be called prior to this function.

unref

public void unref()

Decrements the reference count of a closure after it was previously incremented by the same caller.

If no other callers are using the closure, then the closure will be destroyed and freed.