luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-11 23:16:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

Migrating docs.

Browse Source 
* docs/reference/gobject/tmpl/gclosure.sgml:
	* gobject/gboxed.h:
	* gobject/gclosure.c:
	* gobject/gclosure.h:
	* gobject/gobject.c:
	* gobject/gsourceclosure.c:
	* gobject/gsourceclosure.h:
	  Migrating docs.


svn path=/trunk/; revision=7069
This commit is contained in:
Stefan Kost 2008-06-21 12:18:12 +00:00
parent 59722c87e4
commit 83dd545044
8 changed files with 726 additions and 825 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
ChangeLog
View File

@ -1,3 +1,14 @@
2008-06-21 Stefan Kost <ensonic@users.sf.net>
* docs/reference/gobject/tmpl/gclosure.sgml:
* gobject/gboxed.h:
* gobject/gclosure.c:
* gobject/gclosure.h:
* gobject/gobject.c:
* gobject/gsourceclosure.c:
* gobject/gsourceclosure.h:
Migrating docs.
2008-06-21 Tor Lillqvist <tml@novell.com> 2008-06-21 Tor Lillqvist <tml@novell.com>
* glib/gstdio.c: Improve Windows-specific parts of * glib/gstdio.c: Improve Windows-specific parts of

825
docs/reference/gobject/tmpl/gclosure.sgml
View File

@ -1,825 +0,0 @@
<!-- ##### SECTION Title ##### -->
Closures
<!-- ##### SECTION Short_Description ##### -->
Functions as first-class objects
<!-- ##### SECTION Long_Description ##### -->
<para>
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
reponsibility of the marshaller to convert the arguments for the invocation
from #GValue<!-- -->s into a suitable form, perform the callback on the
converted arguments, and transform the return value back into a #GValue.
</para>
<para>
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 #GValue<!-- -->s and suitable representations in the runtime
of the language in order to use functions written in that languages as
callbacks.
</para>
<para>
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 <link linkend="glib-genmarshal"
>glib-genmarshal</link> 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.
</para>
<para>
Using closures has a number of important advantages over a simple
callback function/data pointer combination:
<itemizedlist>
<listitem><para>
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.
</para></listitem>
<listitem><para>
The reference counting of #GClosure makes it easy to handle reentrancy
right; if a callback is removed while it is being invoked, the closure
and it's parameters won't be freed until the invocation finishes.
</para></listitem>
<listitem><para>
g_closure_invalidate() and invalidation notifiers allow callbacks to be
automatically removed when the objects they point to go away.
</para></listitem>
</itemizedlist>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### MACRO G_CLOSURE_NEEDS_MARSHAL ##### -->
<para>
Returns %TRUE if a #GClosureMarshal marshaller has not yet been set on
@closure. See g_closure_set_marshal().
</para>
@closure: a #GClosure
<!-- ##### MACRO G_CLOSURE_N_NOTIFIERS ##### -->
<para>
Returns the total number of notifiers connected with the closure @cl.
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().
</para>
@cl: a #GClosure
<!-- ##### MACRO G_CCLOSURE_SWAP_DATA ##### -->
<para>
Returns whether the user data of the #GCClosure should be passed as the
first parameter to the callback. See g_cclosure_new_swap().
</para>
@cclosure: a #GCClosure
<!-- ##### MACRO G_CALLBACK ##### -->
<para>
Cast a function pointer to a #GCallback.
</para>
@f: a function pointer.
<!-- ##### USER_FUNCTION GCallback ##### -->
<para>
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.
</para>
<!-- ##### STRUCT GClosure ##### -->
<para>
A #GClosure represents a callback supplied by the programmer.
</para>
@in_marshal: Indicates whether the closure is currently being invoked with
g_closure_invoke()
@is_invalid: Indicates whether the closure has been invalidated by
g_closure_invalidate()
<!-- ##### MACRO G_TYPE_CLOSURE ##### -->
<para>
The #GType for #GClosure.
</para>
<!-- ##### STRUCT GCClosure ##### -->
<para>
A #GCClosure is a specialization of #GClosure for C function callbacks.
</para>
@closure: the #GClosure
@callback: the callback function
<!-- ##### USER_FUNCTION GClosureMarshal ##### -->
<para>
The type used for marshaller functions.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: a #GValue to store the return value. May be %NULL if the
callback of @closure doesn't return a value.
@n_param_values: the length of the @param_values array
@param_values: an array of #GValue<!-- -->s holding the arguments on
which to invoke the callback of @closure
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller,
see g_closure_set_marshal() and g_closure_set_meta_marshal()
<!-- ##### USER_FUNCTION GClosureNotify ##### -->
<para>
The type used for the various notification callbacks which can be registered
on closures.
</para>
@data: data specified when registering the notification callback
@closure: the #GClosure on which the notification is emitted
<!-- ##### FUNCTION g_cclosure_new ##### -->
<para>
Creates a new closure which invokes @callback_func with @user_data as
the last parameter.
</para>
@callback_func: the function to invoke
@user_data: user data to pass to @callback_func
@destroy_data: destroy notify to be called when @user_data is no longer used
@Returns: a new #GCClosure
<!-- ##### FUNCTION g_cclosure_new_swap ##### -->
<para>
Creates a new closure which invokes @callback_func with @user_data as
the first parameter.
</para>
@callback_func: the function to invoke
@user_data: user data to pass to @callback_func
@destroy_data: destroy notify to be called when @user_data is no longer used
@Returns: a new #GCClosure
<!-- ##### FUNCTION g_cclosure_new_object ##### -->
<para>
A variant of g_cclosure_new() which uses @object as @user_data and calls
g_object_watch_closure() on @object and the created closure. This function
is useful when you have a callback closely associated with a #GObject,
and want the callback to no longer run after the object is is freed.
</para>
@callback_func: the function to invoke
@object: a #GObject pointer to pass to @callback_func
@Returns: a new #GCClosure
<!-- ##### FUNCTION g_cclosure_new_object_swap ##### -->
<para>
A variant of g_cclosure_new_swap() which uses @object as @user_data and calls
g_object_watch_closure() on @object and the created closure. This function
is useful when you have a callback closely associated with a #GObject,
and want the callback to no longer run after the object is is freed.
</para>
@callback_func: the function to invoke
@object: a #GObject pointer to pass to @callback_func
@Returns: a new #GCClosure
<!-- ##### FUNCTION g_closure_new_object ##### -->
<para>
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.
</para>
@sizeof_closure: the size of the structure to allocate, must be at least
<literal>sizeof (GClosure)</literal>
@object: a #GObject pointer to store in the @data field of the newly
allocated #GClosure
@Returns: a newly allocated #GClosure
<!-- ##### FUNCTION g_closure_ref ##### -->
<para>
Increments the reference count on a closure to force it staying
alive while the caller holds a pointer to it.
</para>
@closure: #GClosure to increment the reference count on
@Returns: The @closure passed in, for convenience
<!-- ##### FUNCTION g_closure_sink ##### -->
<para>
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:
<programlisting>
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 */
</programlisting>
Because g_source_set_closure() (and similar functions) take ownership of the
initial reference count, if it is unowned, we instead can write:
<programlisting>
g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
</programlisting>
</para>
<para>
Generally, this function is used together with g_closure_ref(). Ane example
of storing a closure for later notification looks like:
<informalexample><programlisting>
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);
}
}
</programlisting></informalexample>
</para>
<para>
Because g_closure_sink() may decrement the reference count of a closure
(if it hasn't been called on @closure yet) just like g_closure_unref(),
g_closure_ref() should be called prior to this function.
</para>
@closure: #GClosure to decrement the initial reference count on, if it's
still being held
<!-- ##### FUNCTION g_closure_unref ##### -->
<para>
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.
</para>
@closure: #GClosure to decrement the reference count on
<!-- ##### FUNCTION g_closure_invoke ##### -->
<para>
Invokes the closure, i.e. executes the callback represented by the @closure.
</para>
@closure: a #GClosure
@return_value: a #GValue to store the return value. May be %NULL if the
callback of @closure doesn't return a value.
@n_param_values: the length of the @param_values array
@param_values: an array of #GValue<!-- -->s holding the arguments on
which to invoke the callback of @closure
@invocation_hint: a context-dependent invocation hint
<!-- ##### FUNCTION g_closure_invalidate ##### -->
<para>
Sets a flag on the closure to indicate that it's calling environment has
become invalid, and thus causes any future invocations of g_closure_invoke()
on this @closure 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().
</para>
<para>
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).
</para>
@closure: GClosure to invalidate
<!-- ##### FUNCTION g_closure_add_finalize_notifier ##### -->
<para>
Registers a finalization notifier which will be called when the reference
count of @closure 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.
</para>
@closure: a #GClosure
@notify_data: data to pass to @notify_func
@notify_func: the callback function to register
<!-- ##### FUNCTION g_closure_add_invalidate_notifier ##### -->
<para>
Registers an invalidation notifier which will be called when the @closure
is invalidated with g_closure_invalidate(). Invalidation notifiers are
invoked before finalization notifiers, in an unspecified order.
</para>
@closure: a #GClosure
@notify_data: data to pass to @notify_func
@notify_func: the callback function to register
<!-- ##### FUNCTION g_closure_remove_finalize_notifier ##### -->
<para>
Removes a finalization notifier.
</para>
<para>
Notice that notifiers are automatically removed after they are run.
</para>
@closure: a #GClosure
@notify_data: data which was passed to g_closure_add_finalize_notifier()
when registering @notify_func
@notify_func: the callback function to remove
<!-- ##### FUNCTION g_closure_remove_invalidate_notifier ##### -->
<para>
Removes an invalidation notifier.
</para>
<para>
Notice that notifiers are automatically removed after they are run.
</para>
@closure: a #GClosure
@notify_data: data which was passed to g_closure_add_invalidate_notifier()
when registering @notify_func
@notify_func: the callback function to remove
<!-- ##### FUNCTION g_closure_new_simple ##### -->
<para>
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.
</para>
<informalexample>
<programlisting>
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;
}
</programlisting>
</informalexample>
@sizeof_closure: the size of the structure to allocate, must be at least
<literal>sizeof (GClosure)</literal>
@data: data to store in the @data field of the newly allocated #GClosure
@Returns: a newly allocated #GClosure
<!-- ##### FUNCTION g_closure_set_marshal ##### -->
<para>
Sets the marshaller of @closure. The <literal>marshal_data</literal>
of @marshal 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
@closure->callback.
</para>
@closure: a #GClosure
@marshal: a #GClosureMarshal function
<!-- ##### FUNCTION g_closure_add_marshal_guards ##### -->
<para>
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.
</para>
@closure: a #GClosure
@pre_marshal_data: data to pass to @pre_marshal_notify
@pre_marshal_notify: a function to call before the closure callback
@post_marshal_data: data to pass to @post_marshal_notify
@post_marshal_notify: a function to call after the closure callback
<!-- ##### FUNCTION g_closure_set_meta_marshal ##### -->
<para>
Sets the meta marshaller of @closure.
A meta marshaller wraps @closure->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 @closure->callback, but in other cases we want to use some
different technique to retrieve the callback function.
</para>
<para>
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 @marshal_data argument.
</para>
@closure: a #GClosure
@marshal_data: context-dependent data to pass to @meta_marshal
@meta_marshal: a #GClosureMarshal function
<!-- ##### FUNCTION g_source_set_closure ##### -->
<para>
Set the callback for a source as a #GClosure.
</para>
<para>
If the source is not one of the standard GLib types, the @closure_callback
and @closure_marshal fields of the #GSourceFuncs structure must have been
filled in with pointers to appropriate functions.
</para>
@source: the source
@closure: a #GClosure
<!-- ##### MACRO G_TYPE_IO_CHANNEL ##### -->
<para>
The #GType for #GIOChannel.
</para>
<!-- ##### MACRO G_TYPE_IO_CONDITION ##### -->
<para>
The #GType for #GIOCondition.
</para>
<!-- ##### FUNCTION g_cclosure_marshal_VOID__VOID ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>void (*callback) (gpointer instance, gpointer user_data)</literal>.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: ignored
@n_param_values: 1
@param_values: a #GValue array holding only the instance
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_VOID__BOOLEAN ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)</literal>.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: ignored
@n_param_values: 2
@param_values: a #GValue array holding the instance and the #gboolean parameter
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_VOID__CHAR ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>void (*callback) (gpointer instance, gchar arg1, gpointer user_data)</literal>.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: ignored
@n_param_values: 2
@param_values: a #GValue array holding the instance and the #gchar parameter
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_VOID__UCHAR ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>void (*callback) (gpointer instance, guchar arg1, gpointer user_data)</literal>.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: ignored
@n_param_values: 2
@param_values: a #GValue array holding the instance and the #guchar parameter
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_VOID__INT ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal>.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: ignored
@n_param_values: 2
@param_values: a #GValue array holding the instance and the #gint parameter
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_VOID__UINT ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>void (*callback) (gpointer instance, guint arg1, gpointer user_data)</literal>.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: ignored
@n_param_values: 2
@param_values: a #GValue array holding the instance and the #guint parameter
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_VOID__LONG ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>void (*callback) (gpointer instance, glong arg1, gpointer user_data)</literal>.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: ignored
@n_param_values: 2
@param_values: a #GValue array holding the instance and the #glong parameter
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_VOID__ULONG ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>void (*callback) (gpointer instance, gulong arg1, gpointer user_data)</literal>.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: ignored
@n_param_values: 2
@param_values: a #GValue array holding the instance and the #gulong parameter
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_VOID__ENUM ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes an enumeration type..
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: ignored
@n_param_values: 2
@param_values: a #GValue array holding the instance and the enumeration parameter
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_VOID__FLAGS ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes a flags type.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: ignored
@n_param_values: 2
@param_values: a #GValue array holding the instance and the flags parameter
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_VOID__FLOAT ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)</literal>.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: ignored
@n_param_values: 2
@param_values: a #GValue array holding the instance and the #gfloat parameter
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_VOID__DOUBLE ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)</literal>.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: ignored
@n_param_values: 2
@param_values: a #GValue array holding the instance and the #gdouble parameter
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_VOID__STRING ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)</literal>.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: ignored
@n_param_values: 2
@param_values: a #GValue array holding the instance and the #gchar* parameter
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_VOID__PARAM ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)</literal>.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: ignored
@n_param_values: 2
@param_values: a #GValue array holding the instance and the #GParamSpec* parameter
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_VOID__BOXED ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)</literal>.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: ignored
@n_param_values: 2
@param_values: a #GValue array holding the instance and the #GBoxed* parameter
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_VOID__POINTER ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)</literal>.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: ignored
@n_param_values: 2
@param_values: a #GValue array holding the instance and the #gpointer parameter
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_VOID__OBJECT ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>void (*callback) (gpointer instance, GOBject *arg1, gpointer user_data)</literal>.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: ignored
@n_param_values: 2
@param_values: a #GValue array holding the instance and the #GObject* parameter
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_STRING__OBJECT_POINTER ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)</literal>.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: a #GValue, which can store the returned string
@n_param_values: 3
@param_values: a #GValue array holding instance, arg1 and arg2
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_VOID__UINT_POINTER ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)</literal>.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: ignored
@n_param_values: 3
@param_values: a #GValue array holding instance, arg1 and arg2
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### FUNCTION g_cclosure_marshal_BOOLEAN__FLAGS ##### -->
<para>
A marshaller for a #GCClosure with a callback of type
<literal>gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter
denotes a flags type.
</para>
@closure: the #GClosure to which the marshaller belongs
@return_value: a #GValue which can store the returned #gboolean
@n_param_values: 2
@param_values: a #GValue array holding instance and arg1
@invocation_hint: the invocation hint given as the last argument
to g_closure_invoke()
@marshal_data: additional data specified when registering the marshaller
<!-- ##### MACRO g_cclosure_marshal_BOOL__FLAGS ##### -->
<para>
Another name for g_cclosure_marshal_BOOLEAN__FLAGS().
</para>

5
gobject/gboxed.h
View File

@ -74,6 +74,11 @@ GType g_boxed_type_register_static (const gchar *name,
/* --- GLib boxed types --- */ /* --- GLib boxed types --- */
/**
* G_TYPE_CLOSURE:
*
* The #GType for #GClosure.
*/
#define G_TYPE_CLOSURE (g_closure_get_type ()) #define G_TYPE_CLOSURE (g_closure_get_type ())
#define G_TYPE_VALUE (g_value_get_type ()) #define G_TYPE_VALUE (g_value_get_type ())
#define G_TYPE_VALUE_ARRAY (g_value_array_get_type ()) #define G_TYPE_VALUE_ARRAY (g_value_array_get_type ())

566
gobject/gclosure.c
View File

@ -17,6 +17,56 @@
* Free Software Foundation, Inc., 59 Temple Place, Suite 330, * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
* Boston, MA 02111-1307, USA. * Boston, MA 02111-1307, USA.
*/ */
/**
* SECTION:Closures
* @Short_description: Functions as first-class objects
*
* 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
* reponsibility of the marshaller to convert the arguments for the invocation
* from #GValue<!-- -->s 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 #GValue<!-- -->s 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 <link linkend="glib-genmarshal"
* >glib-genmarshal</link> 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:
* <itemizedlist>
* <listitem><para>
* 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.
* </para></listitem>
* <listitem><para>
* The reference counting of #GClosure makes it easy to handle reentrancy
* right; if a callback is removed while it is being invoked, the closure
* and it's parameters won't be freed until the invocation finishes.
* </para></listitem>
* <listitem><para>
* g_closure_invalidate() and invalidation notifiers allow callbacks to be
* automatically removed when the objects they point to go away.
* </para></listitem>
* </itemizedlist>
*/
#include "gclosure.h" #include "gclosure.h"
/* /*
@ -86,6 +136,51 @@ enum {
/* --- functions --- */ /* --- functions --- */
/**
* g_closure_new_simple:
* @sizeof_closure: the size of the structure to allocate, must be at least
* <literal>sizeof (GClosure)</literal>
* @data: data to store in the @data 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
*/
GClosure* GClosure*
g_closure_new_simple (guint sizeof_closure, g_closure_new_simple (guint sizeof_closure,
gpointer data) gpointer data)
@ -190,6 +285,26 @@ closure_invoke_notifiers (GClosure *closure,
} }
} }
/**
* g_closure_set_meta_marshal:
* @closure: a #GClosure
* @marshal_data: context-dependent data to pass to @meta_marshal
* @meta_marshal: a #GClosureMarshal function
*
* Sets the meta marshaller of @closure.
* A meta marshaller wraps @closure->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 @closure->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 @marshal_data argument.
*/
void void
g_closure_set_meta_marshal (GClosure *closure, g_closure_set_meta_marshal (GClosure *closure,
gpointer marshal_data, gpointer marshal_data,
@ -218,6 +333,19 @@ g_closure_set_meta_marshal (GClosure *closure,
SET (closure, meta_marshal, 1); SET (closure, meta_marshal, 1);
} }
/**
* g_closure_add_marshal_guards:
* @closure: a #GClosure
* @pre_marshal_data: data to pass to @pre_marshal_notify
* @pre_marshal_notify: a function to call before the closure callback
* @post_marshal_data: data to pass to @post_marshal_notify
* @post_marshal_notify: 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.
*/
void void
g_closure_add_marshal_guards (GClosure *closure, g_closure_add_marshal_guards (GClosure *closure,
gpointer pre_marshal_data, gpointer pre_marshal_data,
@ -263,6 +391,19 @@ g_closure_add_marshal_guards (GClosure *closure,
INC (closure, n_guards); INC (closure, n_guards);
} }
/**
* g_closure_add_finalize_notifier:
* @closure: a #GClosure
* @notify_data: data to pass to @notify_func
* @notify_func: the callback function to register
*
* Registers a finalization notifier which will be called when the reference
* count of @closure 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.
*/
void void
g_closure_add_finalize_notifier (GClosure *closure, g_closure_add_finalize_notifier (GClosure *closure,
gpointer notify_data, gpointer notify_data,
@ -286,6 +427,16 @@ g_closure_add_finalize_notifier (GClosure *closure,
INC (closure, n_fnotifiers); INC (closure, n_fnotifiers);
} }
/**
* g_closure_add_invalidate_notifier:
* @closure: a #GClosure
* @notify_data: data to pass to @notify_func
* @notify_func: the callback function to register
*
* Registers an invalidation notifier which will be called when the @closure
* is invalidated with g_closure_invalidate(). Invalidation notifiers are
* invoked before finalization notifiers, in an unspecified order.
*/
void void
g_closure_add_invalidate_notifier (GClosure *closure, g_closure_add_invalidate_notifier (GClosure *closure,
gpointer notify_data, gpointer notify_data,
@ -349,6 +500,15 @@ closure_try_remove_fnotify (GClosure *closure,
return FALSE; return FALSE;
} }
/**
* g_closure_ref:
* @closure: #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 @closure passed in, for convenience
*/
GClosure* GClosure*
g_closure_ref (GClosure *closure) g_closure_ref (GClosure *closure)
{ {
@ -363,6 +523,22 @@ g_closure_ref (GClosure *closure)
return closure; return closure;
} }
/**
* g_closure_invalidate:
* @closure: GClosure to invalidate
*
* Sets a flag on the closure to indicate that it's calling environment has
* become invalid, and thus causes any future invocations of g_closure_invoke()
* on this @closure 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).
*/
void void
g_closure_invalidate (GClosure *closure) g_closure_invalidate (GClosure *closure)
{ {
@ -380,6 +556,14 @@ g_closure_invalidate (GClosure *closure)
} }
} }
/**
* g_closure_unref:
* @closure: #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.
*/
void void
g_closure_unref (GClosure *closure) g_closure_unref (GClosure *closure)
{ {
@ -401,6 +585,51 @@ g_closure_unref (GClosure *closure)
} }
} }
/**
* g_closure_sink:
* @closure: #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 @closure yet) just like g_closure_unref(),
* g_closure_ref() should be called prior to this function.
*/
void void
g_closure_sink (GClosure *closure) g_closure_sink (GClosure *closure)
{ {
@ -422,6 +651,18 @@ g_closure_sink (GClosure *closure)
} }
} }
/**
* g_closure_remove_invalidate_notifier:
* @closure: a #GClosure
* @notify_data: data which was passed to g_closure_add_invalidate_notifier()
* when registering @notify_func
* @notify_func: the callback function to remove
*
* Removes an invalidation notifier.
*
*
* Notice that notifiers are automatically removed after they are run.
*/
void void
g_closure_remove_invalidate_notifier (GClosure *closure, g_closure_remove_invalidate_notifier (GClosure *closure,
gpointer notify_data, gpointer notify_data,
@ -439,6 +680,17 @@ g_closure_remove_invalidate_notifier (GClosure *closure,
notify_func, notify_data); notify_func, notify_data);
} }
/**
* g_closure_remove_finalize_notifier:
* @closure: a #GClosure
* @notify_data: data which was passed to g_closure_add_finalize_notifier()
* when registering @notify_func
* @notify_func: the callback function to remove
*
* Removes a finalization notifier.
*
* Notice that notifiers are automatically removed after they are run.
*/
void void
g_closure_remove_finalize_notifier (GClosure *closure, g_closure_remove_finalize_notifier (GClosure *closure,
gpointer notify_data, gpointer notify_data,
@ -456,6 +708,18 @@ g_closure_remove_finalize_notifier (GClosure *closure,
notify_func, notify_data); notify_func, notify_data);
} }
/**
* g_closure_invoke:
* @closure: a #GClosure
* @return_value: a #GValue to store the return value. May be %NULL if the
* callback of @closure doesn't return a value.
* @n_param_values: the length of the @param_values array
* @param_values: an array of #GValue<!-- -->s holding the arguments on
* which to invoke the callback of @closure
* @invocation_hint: a context-dependent invocation hint
*
* Invokes the closure, i.e. executes the callback represented by the @closure.
*/
void void
g_closure_invoke (GClosure *closure, g_closure_invoke (GClosure *closure,
GValue /*out*/ *return_value, GValue /*out*/ *return_value,
@ -499,6 +763,18 @@ g_closure_invoke (GClosure *closure,
g_closure_unref (closure); g_closure_unref (closure);
} }
/**
* g_closure_set_marshal:
* @closure: a #GClosure
* @marshal: a #GClosureMarshal function
*
* Sets the marshaller of @closure. The <literal>marshal_data</literal>
* of @marshal 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
* @closure->callback.
*/
void void
g_closure_set_marshal (GClosure *closure, g_closure_set_marshal (GClosure *closure,
GClosureMarshal marshal) GClosureMarshal marshal)
@ -513,6 +789,17 @@ g_closure_set_marshal (GClosure *closure,
closure->marshal = marshal; closure->marshal = marshal;
} }
/**
* g_cclosure_new:
* @callback_func: the function to invoke
* @user_data: user data to pass to @callback_func
* @destroy_data: destroy notify to be called when @user_data is no longer used
*
* Creates a new closure which invokes @callback_func with @user_data as
* the last parameter.
*
* Returns: a new #GCClosure
*/
GClosure* GClosure*
g_cclosure_new (GCallback callback_func, g_cclosure_new (GCallback callback_func,
gpointer user_data, gpointer user_data,
@ -530,6 +817,17 @@ g_cclosure_new (GCallback callback_func,
return closure; return closure;
} }
/**
* g_cclosure_new_swap:
* @callback_func: the function to invoke
* @user_data: user data to pass to @callback_func
* @destroy_data: destroy notify to be called when @user_data is no longer used
*
* Creates a new closure which invokes @callback_func with @user_data as
* the first parameter.
*
* Returns: a new #GCClosure
*/
GClosure* GClosure*
g_cclosure_new_swap (GCallback callback_func, g_cclosure_new_swap (GCallback callback_func,
gpointer user_data, gpointer user_data,
@ -612,5 +910,273 @@ g_signal_type_cclosure_new (GType itype,
return closure; return closure;
} }
/**
* g_cclosure_marshal_VOID__VOID:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: ignored
* @n_param_values: 1
* @param_values: a #GValue array holding only the instance
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__BOOLEAN:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: ignored
* @n_param_values: 2
* @param_values: a #GValue array holding the instance and the #gboolean parameter
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__CHAR:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: ignored
* @n_param_values: 2
* @param_values: a #GValue array holding the instance and the #gchar parameter
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gchar arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__UCHAR:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: ignored
* @n_param_values: 2
* @param_values: a #GValue array holding the instance and the #guchar parameter
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, guchar arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__INT:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: ignored
* @n_param_values: 2
* @param_values: a #GValue array holding the instance and the #gint parameter
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__UINT:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: ignored
* @n_param_values: 2
* @param_values: a #GValue array holding the instance and the #guint parameter
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, guint arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__LONG:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: ignored
* @n_param_values: 2
* @param_values: a #GValue array holding the instance and the #glong parameter
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, glong arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__ULONG:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: ignored
* @n_param_values: 2
* @param_values: a #GValue array holding the instance and the #gulong parameter
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gulong arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__ENUM:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: ignored
* @n_param_values: 2
* @param_values: a #GValue array holding the instance and the enumeration parameter
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes an enumeration type..
*/
/**
* g_cclosure_marshal_VOID__FLAGS:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: ignored
* @n_param_values: 2
* @param_values: a #GValue array holding the instance and the flags parameter
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes a flags type.
*/
/**
* g_cclosure_marshal_VOID__FLOAT:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: ignored
* @n_param_values: 2
* @param_values: a #GValue array holding the instance and the #gfloat parameter
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__DOUBLE:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: ignored
* @n_param_values: 2
* @param_values: a #GValue array holding the instance and the #gdouble parameter
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__STRING:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: ignored
* @n_param_values: 2
* @param_values: a #GValue array holding the instance and the #gchar* parameter
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__PARAM:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: ignored
* @n_param_values: 2
* @param_values: a #GValue array holding the instance and the #GParamSpec* parameter
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__BOXED:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: ignored
* @n_param_values: 2
* @param_values: a #GValue array holding the instance and the #GBoxed* parameter
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__POINTER:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: ignored
* @n_param_values: 2
* @param_values: a #GValue array holding the instance and the #gpointer parameter
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__OBJECT:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: ignored
* @n_param_values: 2
* @param_values: a #GValue array holding the instance and the #GObject* parameter
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, GOBject *arg1, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_VOID__UINT_POINTER:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: ignored
* @n_param_values: 3
* @param_values: a #GValue array holding instance, arg1 and arg2
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)</literal>.
*/
/**
* g_cclosure_marshal_BOOLEAN__FLAGS:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: a #GValue which can store the returned #gboolean
* @n_param_values: 2
* @param_values: a #GValue array holding instance and arg1
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter
* denotes a flags type.
*/
/**
* g_cclosure_marshal_BOOL__FLAGS:
*
* Another name for g_cclosure_marshal_BOOLEAN__FLAGS().
*/
/**
* g_cclosure_marshal_STRING__OBJECT_POINTER:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: a #GValue, which can store the returned string
* @n_param_values: 3
* @param_values: a #GValue array holding instance, arg1 and arg2
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
* <literal>gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)</literal>.
*/
#define __G_CLOSURE_C__ #define __G_CLOSURE_C__
#include "gobjectaliasdef.c" #include "gobjectaliasdef.c"

85
gobject/gclosure.h
View File

@ -29,25 +29,101 @@
G_BEGIN_DECLS G_BEGIN_DECLS
/* --- defines --- */ /* --- defines --- */
/**
* G_CLOSURE_NEEDS_MARSHAL:
* @closure: 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
* @closure.
*/
#define G_CLOSURE_NEEDS_MARSHAL(closure) (((GClosure*) (closure))->marshal == NULL) #define G_CLOSURE_NEEDS_MARSHAL(closure) (((GClosure*) (closure))->marshal == NULL)
/**
* G_CLOSURE_N_NOTIFIERS:
* @cl: a #GClosure
*
* Get the total number of notifiers connected with the closure @cl.
* 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
*/
#define G_CLOSURE_N_NOTIFIERS(cl) ((cl)->meta_marshal + ((cl)->n_guards << 1L) + \ #define G_CLOSURE_N_NOTIFIERS(cl) ((cl)->meta_marshal + ((cl)->n_guards << 1L) + \
(cl)->n_fnotifiers + (cl)->n_inotifiers) (cl)->n_fnotifiers + (cl)->n_inotifiers)
/**
* G_CCLOSURE_SWAP_DATA:
* @cclosure: 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.
*/
#define G_CCLOSURE_SWAP_DATA(cclosure) (((GClosure*) (cclosure))->derivative_flag) #define G_CCLOSURE_SWAP_DATA(cclosure) (((GClosure*) (cclosure))->derivative_flag)
/**
* G_CALLBACK:
* @f: a function pointer.
*
* Cast a function pointer to a #GCallback.
*/
#define G_CALLBACK(f) ((GCallback) (f)) #define G_CALLBACK(f) ((GCallback) (f))
/* -- typedefs --- */ /* -- typedefs --- */
typedef struct _GClosure GClosure; typedef struct _GClosure GClosure;
typedef struct _GClosureNotifyData GClosureNotifyData; typedef struct _GClosureNotifyData GClosureNotifyData;
/**
* 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 void (*GCallback) (void); typedef void (*GCallback) (void);
/**
* GClosureNotify:
* @data: data specified when registering the notification callback
* @closure: the #GClosure on which the notification is emitted
*
* The type used for the various notification callbacks which can be registered
* on closures.
*/
typedef void (*GClosureNotify) (gpointer data, typedef void (*GClosureNotify) (gpointer data,
GClosure *closure); GClosure *closure);
/**
* GClosureMarshal:
* @closure: the #GClosure to which the marshaller belongs
* @return_value: a #GValue to store the return value. May be %NULL if the
* callback of @closure doesn't return a value.
* @n_param_values: the length of the @param_values array
* @param_values: an array of #GValue<!-- -->s holding the arguments on
* which to invoke the callback of @closure
* @invocation_hint: the invocation hint given as the last argument
* to g_closure_invoke()
* @marshal_data: 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 void (*GClosureMarshal) (GClosure *closure, typedef void (*GClosureMarshal) (GClosure *closure,
GValue *return_value, GValue *return_value,
guint n_param_values, guint n_param_values,
const GValue *param_values, const GValue *param_values,
gpointer invocation_hint, gpointer invocation_hint,
gpointer marshal_data); gpointer marshal_data);
/**
* GCClosure:
* @closure: the #GClosure
* @callback: the callback function
*
* A #GCClosure is a specialization of #GClosure for C function callbacks.
*/
typedef struct _GCClosure GCClosure; typedef struct _GCClosure GCClosure;
@ -57,6 +133,15 @@ struct _GClosureNotifyData
gpointer data; gpointer data;
GClosureNotify notify; GClosureNotify notify;
}; };
/**
* GClosure:
* @in_marshal: Indicates whether the closure is currently being invoked with
* g_closure_invoke()
* @is_invalid: Indicates whether the closure has been invalidated by
* g_closure_invalidate()
*
* A #GClosure represents a callback supplied by the programmer.
*/
struct _GClosure struct _GClosure
{ {
/*< private >*/ /*< private >*/

38
gobject/gobject.c
View File

@ -2182,6 +2182,20 @@ g_object_watch_closure (GObject *object,
g_datalist_id_set_data_full (&object->qdata, quark_closure_array, carray, destroy_closure_array); g_datalist_id_set_data_full (&object->qdata, quark_closure_array, carray, destroy_closure_array);
} }
/**
* g_closure_new_object:
* @sizeof_closure: the size of the structure to allocate, must be at least
* <literal>sizeof (GClosure)</literal>
* @object: a #GObject pointer to store in the @data field of the newly
* allocated #GClosure
*
* 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.
*
* Returns: a newly allocated #GClosure
*/
GClosure* GClosure*
g_closure_new_object (guint sizeof_closure, g_closure_new_object (guint sizeof_closure,
GObject *object) GObject *object)
@ -2197,6 +2211,18 @@ g_closure_new_object (guint sizeof_closure,
return closure; return closure;
} }
/**
* g_cclosure_new_object:
* @callback_func: the function to invoke
* @object: a #GObject pointer to pass to @callback_func
*
* A variant of g_cclosure_new() which uses @object as @user_data and calls
* g_object_watch_closure() on @object and the created closure. This function
* is useful when you have a callback closely associated with a #GObject,
* and want the callback to no longer run after the object is is freed.
*
* Returns: a new #GCClosure
*/
GClosure* GClosure*
g_cclosure_new_object (GCallback callback_func, g_cclosure_new_object (GCallback callback_func,
GObject *object) GObject *object)
@ -2213,6 +2239,18 @@ g_cclosure_new_object (GCallback callback_func,
return closure; return closure;
} }
/**
* g_cclosure_new_object_swap:
* @callback_func: the function to invoke
* @object: a #GObject pointer to pass to @callback_func
*
* A variant of g_cclosure_new_swap() which uses @object as @user_data and calls
* g_object_watch_closure() on @object and the created closure. This function
* is useful when you have a callback closely associated with a #GObject,
* and want the callback to no longer run after the object is is freed.
*
* Returns: a new #GCClosure
*/
GClosure* GClosure*
g_cclosure_new_object_swap (GCallback callback_func, g_cclosure_new_object_swap (GCallback callback_func,
GObject *object) GObject *object)

11
gobject/gsourceclosure.c
View File

@ -155,6 +155,17 @@ static GSourceCallbackFuncs closure_callback_funcs = {
closure_callback_get closure_callback_get
}; };
/**
* g_source_set_closure:
* @source: the source
* @closure: a #GClosure
*
* Set the callback for a source as a #GClosure.
*
* If the source is not one of the standard GLib types, the @closure_callback
* and @closure_marshal fields of the #GSourceFuncs structure must have been
* filled in with pointers to appropriate functions.
*/
void void
g_source_set_closure (GSource *source, g_source_set_closure (GSource *source,
GClosure *closure) GClosure *closure)

10
gobject/gsourceclosure.h
View File

@ -33,7 +33,17 @@ void g_source_set_closure (GSource *source,
GType g_io_channel_get_type (void); GType g_io_channel_get_type (void);
GType g_io_condition_get_type (void); GType g_io_condition_get_type (void);
/**
* G_TYPE_IO_CHANNEL:
*
* The #GType for #GIOChannel.
*/
#define G_TYPE_IO_CHANNEL (g_io_channel_get_type ()) #define G_TYPE_IO_CHANNEL (g_io_channel_get_type ())
/**
* G_TYPE_IO_CONDITION:
*
* The #GType for #GIOCondition.
*/
#define G_TYPE_IO_CONDITION (g_io_condition_get_type ()) #define G_TYPE_IO_CONDITION (g_io_condition_get_type ())
G_END_DECLS G_END_DECLS