Closure

Closure

Object Hierarchy:

Description:

[ CCode ( ref_function = "g_closure_ref" , type_id = "G_TYPE_CLOSURE" , unref_function = "g_closure_unref" ) ]
[ Compact ]
public class Closure

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][struct@Value] into a suitable form, perform the callback on the converted arguments, and transform the return value back into a [struct@Value].

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 [struct@Value] and native C types. The GObject library provides the [struct@CClosure] type for this purpose. Bindings for other languages need marshallers which convert between [GValues][struct@Value] and suitable representations in the runtime of the language in order to use functions written in that language as callbacks. Use [method@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 [func@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 utility. Closures can be explicitly connected to signals with [func@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 [struct@Closure] 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.
[method@Closure.invalidate] and invalidation notifiers allow callbacks to be automatically removed when the objects they point to go away.

Namespace: GLib

Package: gobject-2.0

Content:

Creation methods:

public Closure (ulong sizeof_closure, Object object)
public Closure.object (uint sizeof_closure, Object object)
A variant of Closure.simple which stores object in the data field of the closure and calls watch_closure on object and the created closure.
public Closure.simple (uint sizeof_closure, void* data)
Allocates a struct of the given size and initializes the initial part as a Closure.

Methods:

public unowned Closure @ref ()
Increments the reference count on a closure to force it staying alive while the caller holds a pointer to it.
public void add_finalize_notifier (void* notify_data, ClosureNotify notify_func)
Registers a finalization notifier which will be called when the reference count of this goes down to 0.
public void add_invalidate_notifier (void* notify_data, ClosureNotify notify_func)
Registers an invalidation notifier which will be called when the this is invalidated with invalidate.
public void add_marshal_guards (void* pre_marshal_data, ClosureNotify pre_marshal_notify, void* post_marshal_data, ClosureNotify post_marshal_notify)
Adds a pair of notifiers which get invoked before and after the closure callback, respectively.
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 invoke on this this to be ignored.
public void invoke (ref Value return_value, Value[] param_values, void* invocation_hint = null)
Invokes the closure, i.
public void remove_finalize_notifier (void* notify_data, ClosureNotify notify_func)
Removes a finalization notifier.
public void remove_invalidate_notifier (void* notify_data, ClosureNotify notify_func)
Removes an invalidation notifier.
public void set_marshal (ClosureMarshal marshal)
Sets the marshaller of this.
public void set_meta_marshal (void* marshal_data, ClosureMarshal meta_marshal)
Sets the meta marshaller of this.
public void sink ()
Takes over the initial ownership of a closure.
public void unref ()
Decrements the reference count of a closure after it was previously incremented by the same caller.

Fields:

public static size_t SIZE