Struct
GObjectClosure
Description
struct GClosure {
guint in_marshal : 1;
guint is_invalid : 1;
void (* marshal) (
GClosure* closure,
GValue* return_value,
guint n_param_values,
const GValue* param_values,
gpointer invocation_hint,
gpointer marshal_data
);
}
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
c_marshaller 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
GClosuremakes 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.
Structure members
in_marshalIndicates whether the closure is currently being invoked with
g_closure_invoke()is_invalidIndicates whether the closure has been invalidated by
g_closure_invalidate()marshal- No description available.
Constructors
g_closure_new_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.
g_closure_new_simple
Allocates a struct of the given size and initializes the initial
part as a GClosure.
Instance methods
g_closure_add_finalize_notifier
Registers a finalization notifier which will be called when the
reference count of closure goes down to 0.
g_closure_add_invalidate_notifier
Registers an invalidation notifier which will be called when the
closure is invalidated with g_closure_invalidate().
g_closure_add_marshal_guards
Adds a pair of notifiers which get invoked before and after the closure callback, respectively.
g_closure_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 closure to be ignored.
g_closure_ref
Increments the reference count on a closure to force it staying alive while the caller holds a pointer to it.
g_closure_unref
Decrements the reference count of a closure after it was previously incremented by the same caller.