X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=gobject%2Fgclosure.c;h=4ebbfcf71ca37a07f14d936db117a214ee82d5f1;hb=323242578524a1b6355d8451015b14ca75aa0afa;hp=14647e8311f9793d98b62ad8236467125392097d;hpb=10fc00b38515bc322d5e497d61a50165b04c3c8d;p=platform%2Fupstream%2Fglib.git
diff --git a/gobject/gclosure.c b/gobject/gclosure.c
index 14647e8..4ebbfcf 100644
--- a/gobject/gclosure.c
+++ b/gobject/gclosure.c
@@ -13,9 +13,7 @@
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General
- * Public License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
- * Boston, MA 02111-1307, USA.
+ * Public License along with this library; if not, see .
*/
/*
@@ -34,7 +32,7 @@
#include "genums.h"
#include "gvalue.h"
#include "gvaluetypes.h"
-#include "gtype-private.h"
+#include "gtype-private.h"
/**
@@ -45,13 +43,13 @@
* 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 #GValues into
+ * convert the arguments for the invocation from #GValues 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
+ * 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 #GValues and suitable representations in the runtime of the language in
@@ -73,22 +71,17 @@
*
* 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 #GClosure 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.
- *
- *
- * g_closure_invalidate() and invalidation notifiers allow callbacks to be
- * automatically removed when the objects they point to go away.
- *
- *
+ *
+ * - 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 #GClosure 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.
+ *
+ * - g_closure_invalidate() and invalidation notifiers allow callbacks to be
+ * automatically removed when the objects they point to go away.
*/
#define CLOSURE_MAX_REF_COUNT ((1 << 15) - 1)
@@ -151,19 +144,19 @@ enum {
/**
* g_closure_new_simple:
* @sizeof_closure: the size of the structure to allocate, must be at least
- * sizeof (GClosure)
+ * `sizeof (GClosure)`
* @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
+ * /* extra data goes here */
* };
*
* static void
@@ -172,7 +165,7 @@ enum {
* {
* MyClosure *my_closure = (MyClosure *)closure;
*
- * // free extra data here
+ * /* free extra data here */
* }
*
* MyClosure *my_closure_new (gpointer data)
@@ -183,7 +176,7 @@ enum {
* closure = g_closure_new_simple (sizeof (MyClosure), data);
* my_closure = (MyClosure *) closure;
*
- * // initialize extra data here
+ * /* initialize extra data here */
*
* g_closure_add_finalize_notifier (closure, notify_data,
* my_closure_finalize);
@@ -608,27 +601,27 @@ g_closure_unref (GClosure *closure)
* still being held
*
* 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.
- * 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 existence of the floating state is to
- * prevent cumbersome code sequences like:
- * |[
+ * initially created in a "floating" 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
+ * 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); // XXX GObject doesn't really need this
+ * g_closure_unref (closure); /* 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)
@@ -733,7 +726,7 @@ g_closure_remove_finalize_notifier (GClosure *closure,
* doesn't return a value.
* @n_param_values: the length of the @param_values array
* @param_values: (array length=n_param_values): an array of
- * #GValues holding the arguments on which to
+ * #GValues holding the arguments on which to
* invoke the callback of @closure
* @invocation_hint: (allow-none): a context-dependent invocation hint
*
@@ -855,7 +848,7 @@ _g_closure_invoke_va (GClosure *closure,
* @closure: a #GClosure
* @marshal: a #GClosureMarshal function
*
- * Sets the marshaller of @closure. The marshal_data
+ * Sets the marshaller of @closure. The `marshal_data`
* 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_*()
@@ -1367,7 +1360,7 @@ va_to_ffi_type (GType gtype,
* @return_gvalue: 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 #GValues holding the arguments
+ * @param_values: An array of #GValues 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().
@@ -1375,8 +1368,8 @@ va_to_ffi_type (GType gtype,
* marshaller, see g_closure_set_marshal() and
* g_closure_set_meta_marshal()
*
- * A generic marshaller function implemented via libffi.
+ * A generic marshaller function implemented via
+ * [libffi](http://sourceware.org/libffi/).
*
* Since: 2.30
*/
@@ -1585,7 +1578,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, gpointer user_data).
+ * `void (*callback) (gpointer instance, gpointer user_data)`.
*/
/**
@@ -1599,7 +1592,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, gboolean arg1, gpointer user_data).
+ * `void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`.
*/
/**
@@ -1613,7 +1606,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, gchar arg1, gpointer user_data).
+ * `void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`.
*/
/**
@@ -1627,7 +1620,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, guchar arg1, gpointer user_data).
+ * `void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`.
*/
/**
@@ -1641,7 +1634,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, gint arg1, gpointer user_data).
+ * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)`.
*/
/**
@@ -1655,7 +1648,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, guint arg1, gpointer user_data).
+ * `void (*callback) (gpointer instance, guint arg1, gpointer user_data)`.
*/
/**
@@ -1669,7 +1662,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, glong arg1, gpointer user_data).
+ * `void (*callback) (gpointer instance, glong arg1, gpointer user_data)`.
*/
/**
@@ -1683,7 +1676,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, gulong arg1, gpointer user_data).
+ * `void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`.
*/
/**
@@ -1697,7 +1690,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, gint arg1, gpointer user_data) where the #gint parameter denotes an enumeration type..
+ * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type..
*/
/**
@@ -1711,7 +1704,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, gint arg1, gpointer user_data) where the #gint parameter denotes a flags type.
+ * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type.
*/
/**
@@ -1725,7 +1718,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, gfloat arg1, gpointer user_data).
+ * `void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`.
*/
/**
@@ -1739,7 +1732,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, gdouble arg1, gpointer user_data).
+ * `void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`.
*/
/**
@@ -1753,7 +1746,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data).
+ * `void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`.
*/
/**
@@ -1767,7 +1760,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data).
+ * `void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`.
*/
/**
@@ -1781,7 +1774,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data).
+ * `void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`.
*/
/**
@@ -1795,7 +1788,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, gpointer arg1, gpointer user_data).
+ * `void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`.
*/
/**
@@ -1809,7 +1802,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, GObject *arg1, gpointer user_data).
+ * `void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`.
*/
/**
@@ -1823,7 +1816,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data).
+ * `void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`.
*
* Since: 2.26
*/
@@ -1839,7 +1832,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data).
+ * `void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`.
*/
/**
@@ -1853,7 +1846,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data) where the #gint parameter
+ * `gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter
* denotes a flags type.
*/
@@ -1873,7 +1866,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data).
+ * `gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`.
*/
/**
* g_cclosure_marshal_BOOLEAN__OBJECT_BOXED_BOXED:
@@ -1886,7 +1879,7 @@ g_cclosure_marshal_generic_va (GClosure *closure,
* @marshal_data: additional data specified when registering the marshaller
*
* A marshaller for a #GCClosure with a callback of type
- * gboolean (*callback) (gpointer instance, GBoxed *arg1, GBoxed *arg2, gpointer user_data).
+ * `gboolean (*callback) (gpointer instance, GBoxed *arg1, GBoxed *arg2, gpointer user_data)`.
*
* Since: 2.26
*/