GObject.Closure - Structures - GObject 2.0 (original) (raw)
Fields¶
| Name | Type | Access | Description |
|---|---|---|---|
| data | object | r | |
| derivative_flag | int | r | |
| floating | int | r | |
| in_inotify | int | r | |
| in_marshal | int | r/w | Indicates whether the closure is currently being invoked with GObject.Closure.invoke() |
| is_invalid | int | r/w | Indicates whether the closure has been invalidated by GObject.Closure.invalidate() |
| marshal | object | r | |
| meta_marshal_nouse | int | r | |
| n_fnotifiers | int | r | |
| n_guards | int | r | |
| n_inotifiers | int | r | |
| notifiers | GObject.ClosureNotifyData | r | |
| ref_count | int | r |
Methods¶
| class | new_object (sizeof_closure, object) |
|---|---|
| class | new_simple (sizeof_closure, data) |
| invalidate () | |
| invoke (param_values, invocation_hint) | |
| ref () | |
| sink () | |
| unref () |
Details¶
class GObject.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 GObject.Values into a suitable form, perform the callback on the converted arguments, and transform the return value back into a GObject.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 GObject.Value and native C types. The GObject.Objectlibrary provides the GObject.CClosure type for this purpose. Bindings for other languages need marshallers which convert between GObject.Valuesand 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.Object, closures play an important role in the implementation of signals. When a signal is registered, thec_marshaller argument to GObject.signal_new() specifies the default C marshaller for any closure which is connected to this signal. GObject.Object provides a number of C marshallers for this purpose, see the g_cclosure_marshal_*() functions. Additional C marshallers can be generated with the glib-genmarshalutility. Closures can be explicitly connected to signals withGObject.signal_connect_closure(), but it usually more convenient to letGObject.Object 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 GObject.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.
- GObject.Closure.invalidate() and invalidation notifiers allow callbacks to be automatically removed when the objects they point to go away.
classmethod new_object(sizeof_closure, object)[source]¶
Parameters:
- sizeof_closure (int) – the size of the structure to allocate, must be at least
sizeof (GClosure) - object (GObject.Object) – a GObject.Object pointer to store in the data field of the newly allocated GObject.Closure
Returns:
a newly allocated GObject.Closure
Return type:
A variant of GObject.Closure.new_simple() which stores object in thedata field of the closure and calls GObject.Object.watch_closure() onobject and the created closure. This function is mainly useful when implementing new types of closures.
classmethod new_simple(sizeof_closure, data)[source]¶
Parameters:
- sizeof_closure (int) – the size of the structure to allocate, must be at least
sizeof (GClosure) - data (object or None) – data to store in the data field of the newly allocated GObject.Closure
Returns:
a floating reference to a new GObject.Closure
Return type:
Allocates a struct of the given size and initializes the initial part as a GObject.Closure.
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; }
Sets a flag on the closure to indicate that its calling environment has become invalid, and thus causes any future invocations of GObject.Closure.invoke() on this self 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 GObject.Closure.invalidate(), make sure that you’ve previously called GObject.Closure.ref().
Note that GObject.Closure.invalidate() will also be called when the reference count of a closure drops to zero (unless it has already been invalidated before).
invoke(param_values, invocation_hint)[source]¶
Parameters:
- param_values ([GObject.Value]) – an array ofGObject.Values holding the arguments on which to invoke the callback of self
- invocation_hint (object or None) – a context-dependent invocation hint
Returns:
a GObject.Value to store the return value. May be None if the callback of selfdoesn’t return a value.
Return type:
return_value: GObject.Value
Invokes the closure, i.e. executes the callback represented by the self.
Returns:
The self passed in, for convenience
Return type:
Increments the reference count on a closure to force it staying alive while the caller holds a pointer to it.
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, GObject.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 GObject.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 GObject.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 GObject.Closure.sink() may decrement the reference count of a closure (if it hasn’t been called on self yet) just like GObject.Closure.unref(),GObject.Closure.ref() should be called prior to this function.
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.