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 */