Closure
Object Hierarchy:
Description:
[ Compact ]
public class Closure
A Closure 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 reponsibility of the marshaller to convert the
arguments for the invocation from Values into a suitable form, perform the callback on
the converted arguments, and transform the return value back into a 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
Value and native C types. The GObject library provides the GCClosure type
for this purpose. Bindings for other languages need marshallers which convert between
Values and suitable representations in the runtime of the language in order to use functions written in that languages as callbacks.
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 utility. Closures can be explicitly connected to signals with
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 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.
- invalidate and invalidation notifiers allow callbacks to be
automatically removed when the objects they point to go away.
Content:
Creation methods:
Methods:
- public void sink ()
Takes over the initial ownership of a closure.
- public void invoke (out Value? return_value, Value[] param_values, void* invocation_hint)
Invokes the closure, i.e. executes the callback represented by the
closure.
- 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
closure to be ignored.
- public void add_finalize_notifier (void* notify_data, ClosureNotify notify_func)
Registers a finalization notifier which will be called when the reference
count of closure 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
closure is invalidated with invalidate.
- 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 closure.
- 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 set_meta_marshal (void* marshal_data, ClosureMarshal meta_marshal)
Sets the meta marshaller of closure.
Fields:
