gclosure.h File Reference

__G_CLOSURE_H__

G_CLOSURE_NEEDS_MARSHAL

G_CLOSURE_NEEDS_MARSHAL: : a GClosure

Check if the closure still needs a marshaller. See g_closure_set_marshal().

Returns: TRUE if a GClosureMarshal marshaller has not yet been set on .

G_CLOSURE_N_NOTIFIERS

G_CLOSURE_N_NOTIFIERS: : a GClosure

Get the total number of notifiers connected with the closure . The count includes the meta marshaller, the finalize and invalidate notifiers and the marshal guards. Note that each guard counts as two notifiers. See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(), g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards().

Returns: number of notifiers

G_CCLOSURE_SWAP_DATA

G_CCLOSURE_SWAP_DATA: : a GCClosure

Checks whether the user data of the GCClosure should be passed as the first parameter to the callback. See g_cclosure_new_swap().

Returns: TRUE if data has to be swapped.

G_CALLBACK

G_CALLBACK: : a function pointer.

Cast a function pointer to a GCallback.

Typedef GClosure

typedef struct _GClosureGClosure

Typedef GClosureNotifyData

typedef struct _GClosureNotifyDataGClosureNotifyData

Typedef GCallback

typedef void(*GCallback

GCallback:

The type used for callback functions in structure definitions and function signatures. This doesn't mean that all callback functions must take no parameters and return void. The required signature of a callback function is determined by the context in which is used (e.g. the signal to which it is connected). Use G_CALLBACK() to cast the callback function to a GCallback.

Typedef GClosureNotify

typedef void(*GClosureNotify

GClosureNotify: : data specified when registering the notification callback : the GClosure on which the notification is emitted

The type used for the various notification callbacks which can be registered on closures.

Typedef GClosureMarshal

typedef void(*GClosureMarshal

GClosureMarshal: : the GClosure to which the marshaller belongs : a GValue to store the return value. May be NULL if the callback of doesn't return a value. : the length of the array : an array of #GValues holding the arguments on which to invoke the callback of : the invocation hint given as the last argument to g_closure_invoke() : additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal()

The type used for marshaller functions.

Typedef GCClosure

typedef struct _GCClosureGCClosure

GCClosure: : the GClosure : the callback function

A GCClosure is a specialization of GClosure for C function callbacks.

g_cclosure_new ( GCallback, gpointer, GClosureNotify )

IMPORT_C GClosure *g_cclosure_new(GCallbackcallback_func,
gpointeruser_data,
GClosureNotifydestroy_data
)

g_cclosure_new: : the function to invoke : user data to pass to : destroy notify to be called when is no longer used

Creates a new closure which invokes with as the last parameter.

Returns: a new GCClosure

g_cclosure_new_swap ( GCallback, gpointer, GClosureNotify )

IMPORT_C GClosure *g_cclosure_new_swap(GCallbackcallback_func,
gpointeruser_data,
GClosureNotifydestroy_data
)

g_cclosure_new_swap: : the function to invoke : user data to pass to : destroy notify to be called when is no longer used

Creates a new closure which invokes with as the first parameter.

Returns: a new GCClosure

g_signal_type_cclosure_new ( GType, guint )

IMPORT_C GClosure *g_signal_type_cclosure_new(GTypeitype,
guintstruct_offset
)

g_signal_type_cclosure_new: : the GType identifier of an interface or classed type : the offset of the member function of 's class structure which is to be invoked by the new closure

Creates a new closure which invokes the function found at the offset in the class structure of the interface or classed type identified by .

Returns: a new GCClosure

g_closure_ref ( GClosure * )

IMPORT_C GClosure *g_closure_ref(GClosure *closure)

g_closure_ref: : GClosure to increment the reference count on

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

Returns: The passed in, for convenience

g_closure_sink ( GClosure * )

IMPORT_C voidg_closure_sink(GClosure *closure)

g_closure_sink: : GClosure to decrement the initial reference count on, if it's still being held

Takes over the initial ownership of a closure. Each closure is initially created in a <firstterm>floating</firstterm> state, which means that the initial reference count is not owned by any caller. g_closure_sink() 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 existance 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); // XXX 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(). Ane 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 yet) just like g_closure_unref(), g_closure_ref() should be called prior to this function.

g_closure_unref ( GClosure * )

IMPORT_C voidg_closure_unref(GClosure *closure)

g_closure_unref: : GClosure to decrement the reference count on

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.

g_closure_new_simple ( guint, gpointer )

IMPORT_C GClosure *g_closure_new_simple(guintsizeof_closure,
gpointerdata
)

g_closure_new_simple: : the size of the structure to allocate, must be at least <literal>sizeof (GClosure)</literal> : data to store in the field of the newly allocated GClosure

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; } ]|

Returns: a newly allocated GClosure

g_closure_add_finalize_notifier ( GClosure *, gpointer, GClosureNotify )

IMPORT_C voidg_closure_add_finalize_notifier(GClosure *closure,
gpointernotify_data,
GClosureNotifynotify_func
)

g_closure_add_finalize_notifier: : a GClosure : data to pass to : the callback function to register

Registers a finalization notifier which will be called when the reference count of 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.

g_closure_remove_finalize_notifier ( GClosure *, gpointer, GClosureNotify )

IMPORT_C voidg_closure_remove_finalize_notifier(GClosure *closure,
gpointernotify_data,
GClosureNotifynotify_func
)

g_closure_remove_finalize_notifier: : a GClosure : data which was passed to g_closure_add_finalize_notifier() when registering : the callback function to remove

Removes a finalization notifier.

Notice that notifiers are automatically removed after they are run.

g_closure_add_invalidate_notifier ( GClosure *, gpointer, GClosureNotify )

IMPORT_C voidg_closure_add_invalidate_notifier(GClosure *closure,
gpointernotify_data,
GClosureNotifynotify_func
)

g_closure_add_invalidate_notifier: : a GClosure : data to pass to : the callback function to register

Registers an invalidation notifier which will be called when the is invalidated with g_closure_invalidate(). Invalidation notifiers are invoked before finalization notifiers, in an unspecified order.

g_closure_remove_invalidate_notifier ( GClosure *, gpointer, GClosureNotify )

IMPORT_C voidg_closure_remove_invalidate_notifier(GClosure *closure,
gpointernotify_data,
GClosureNotifynotify_func
)

g_closure_remove_invalidate_notifier: : a GClosure : data which was passed to g_closure_add_invalidate_notifier() when registering : the callback function to remove

Removes an invalidation notifier.

Notice that notifiers are automatically removed after they are run.

g_closure_add_marshal_guards ( GClosure *, gpointer, GClosureNotify, gpointer, GClosureNotify )

IMPORT_C voidg_closure_add_marshal_guards(GClosure *closure,
gpointerpre_marshal_data,
GClosureNotifypre_marshal_notify,
gpointerpost_marshal_data,
GClosureNotifypost_marshal_notify
)

g_closure_add_marshal_guards: : a GClosure : data to pass to : a function to call before the closure callback : data to pass to : a function to call after the closure callback

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.

g_closure_set_marshal ( GClosure *, GClosureMarshal )

IMPORT_C voidg_closure_set_marshal(GClosure *closure,
GClosureMarshalmarshal
)

g_closure_set_marshal: : a GClosure : a GClosureMarshal function

Sets the marshaller of . The <literal>marshal_data</literal> of provides a way for a meta marshaller to provide additional information to the marshaller. (See g_closure_set_meta_marshal().) For GObject's C predefined marshallers (the g_cclosure_marshal_*() functions), what it provides is a callback function to use instead of ->callback.

g_closure_set_meta_marshal ( GClosure *, gpointer, GClosureMarshal )

IMPORT_C voidg_closure_set_meta_marshal(GClosure *closure,
gpointermarshal_data,
GClosureMarshalmeta_marshal
)

g_closure_set_meta_marshal: : a GClosure : context-dependent data to pass to : a GClosureMarshal function

Sets the meta marshaller of . A meta marshaller wraps ->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 <link linkend="glib-genmarshal">glib-genmarshal</link>) are used everywhere, but the way that we get the callback function differs. In most cases we want to use ->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 argument.

g_closure_invalidate ( GClosure * )

IMPORT_C voidg_closure_invalidate(GClosure *closure)

g_closure_invalidate: : GClosure to 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 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).

g_closure_invoke ( GClosure *, GValue *, guint, const GValue *, gpointer )

IMPORT_C voidg_closure_invoke(GClosure *closure,
GValue *return_value,
guintn_param_values,
const GValue *param_values,
gpointerinvocation_hint
)

g_closure_invoke: : a GClosure : a GValue to store the return value. May be NULL if the callback of doesn't return a value. : the length of the array : an array of #GValues holding the arguments on which to invoke the callback of : a context-dependent invocation hint

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