From 9d641fd17a149f8a78828d72cd67e8a03894ae3a Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Tue, 14 Oct 2003 00:37:18 +0000 Subject: [PATCH] Document closures. --- docs/reference/ChangeLog | 10 + docs/reference/gobject/gobject-sections.txt | 25 +- docs/reference/gobject/tmpl/gclosure.sgml | 611 +++++++++++++++++++++++----- 3 files changed, 543 insertions(+), 103 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 0abaadb..55ade1b 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,13 @@ +Tue Oct 14 02:35:45 2003 Matthias Clasen + + * gobject/gobject-sections.txt: Move the g_cclosure_marshal_* + functions to a non-private subsection, since these functions + are not private. + +Tue Oct 14 02:35:16 2003 Matthias Clasen + + * gobject/tmpl/gclosure.sgml: Fill in. + Sun Oct 5 23:23:53 2003 Matthias Clasen * gobject/glib-sections.txt: diff --git a/docs/reference/gobject/gobject-sections.txt b/docs/reference/gobject/gobject-sections.txt index 40c6136..9800791 100644 --- a/docs/reference/gobject/gobject-sections.txt +++ b/docs/reference/gobject/gobject-sections.txt @@ -688,7 +688,6 @@ G_TYPE_CLOSURE GCClosure GClosureMarshal GClosureNotify -GClosureNotifyData g_cclosure_new g_cclosure_new_swap g_cclosure_new_object @@ -711,7 +710,31 @@ g_source_set_closure G_TYPE_IO_CHANNEL G_TYPE_IO_CONDITION + +g_cclosure_marshal_VOID__VOID +g_cclosure_marshal_VOID__BOOLEAN +g_cclosure_marshal_VOID__CHAR +g_cclosure_marshal_VOID__UCHAR +g_cclosure_marshal_VOID__INT +g_cclosure_marshal_VOID__UINT +g_cclosure_marshal_VOID__LONG +g_cclosure_marshal_VOID__ULONG +g_cclosure_marshal_VOID__ENUM +g_cclosure_marshal_VOID__FLAGS +g_cclosure_marshal_VOID__FLOAT +g_cclosure_marshal_VOID__DOUBLE +g_cclosure_marshal_VOID__STRING +g_cclosure_marshal_VOID__PARAM +g_cclosure_marshal_VOID__BOXED +g_cclosure_marshal_VOID__POINTER +g_cclosure_marshal_VOID__OBJECT +g_cclosure_marshal_STRING__OBJECT_POINTER +g_cclosure_marshal_VOID__UINT_POINTER +g_cclosure_marshal_BOOLEAN__FLAGS +g_cclosure_marshal_BOOL__FLAGS + +GClosureNotifyData g_closure_get_type g_cclosure_marshal_VOID__VOID g_cclosure_marshal_VOID__BOOLEAN diff --git a/docs/reference/gobject/tmpl/gclosure.sgml b/docs/reference/gobject/tmpl/gclosure.sgml index 9f52377..c8e04f6 100644 --- a/docs/reference/gobject/tmpl/gclosure.sgml +++ b/docs/reference/gobject/tmpl/gclosure.sgml @@ -6,7 +6,20 @@ 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 #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 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 order to use functions written in that languages as +callbacks. @@ -16,50 +29,62 @@ Functions as first-class objects - +Returns %TRUE if a #GClosureMarshal marshaller has not yet been set on +@closure. See g_closure_set_marshal(). -@closure: +@closure: a #GClosure - +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(). -@cl: +@cl: a #GClosure - +Returns whether the user data of the #GCClosure should be passed as the +first parameter to the callback. See g_cclosure_new_swap(). -@cclosure: +@cclosure: a #GCClosure - +Cast a function pointer to a #GCallback. -@f: +@f: a function pointer. - +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. - +A #GClosure represents a callback supplied by the programmer. -@in_marshal: -@is_invalid: Indicates whether the closure has been invalidated by g_closure_invalidate() +@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() @@ -70,97 +95,107 @@ The #GType for #GClosure. - +A #GCClosure is a specialization of #GClosure for C function callbacks. -@closure: -@callback: +@closure: the #GClosure +@callback: the callback function - +The type used for marshaller functions. -@closure: -@return_value: -@n_param_values: -@param_values: -@invocation_hint: -@marshal_data: +@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 #GValues holding the arguments on + which to invoke the callback of @closure +@invocation_hint: the invocation hint given as the 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 the various notification callbacks which can be registered +on closures. -@data: -@closure: - - - - - - +@data: data specified when registering the notification callback +@closure: the #GClosure on which the notification is emitted -@data: -@notify: - +Creates a new closure which invokes @callback_func with @user_data as last +parameter. -@callback_func: -@user_data: -@destroy_data: -@Returns: +@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 destroyed +@Returns: a new #GCClosure - +Creates a new closure which invokes @callback_func with @user_data as first +parameter. -@callback_func: -@user_data: -@destroy_data: -@Returns: +@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 destroyed +@Returns: a new #GCClosure - +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 mainly useful when implementing new types +of closures. -@callback_func: -@object: -@Returns: +@callback_func: the function to invoke +@object: a #GObject pointer to pass to @callback_func +@Returns: a new #GCClosure - +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 mainly useful when implementing new types +of closures. -@callback_func: -@object: -@Returns: +@callback_func: the function to invoke +@object: a #GObject pointer to pass to @callback_func +@Returns: a new #GCClosure - +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. -@sizeof_closure: -@object: -@Returns: +@sizeof_closure: the size of the structure to allocate, must be at least +sizeof (GClosure) +@object: a #GObject pointer to store in the @data field of the newly + allocated #GClosure +@Returns: a newly allocated #GClosure -Increment the reference count on a closure to force it staying +Increments the reference count on a closure to force it staying alive while the caller holds a pointer to it. @@ -170,7 +205,7 @@ alive while the caller holds a pointer to it. -Take over the initial ownership of a closure. +Takes over the initial ownership of a closure. When closures are newly created, they get an initial reference count of 1, eventhough no caller has yet invoked g_closure_ref() on the @closure. Code entities that store closures for notification purposes are supposed @@ -201,7 +236,7 @@ g_closure_ref() should be called prior to this function. -Decrement the reference count of a closure after it was +Decrements the reference count of a closure after it was previously incremented by the same caller. The closure will most likely be destroyed and freed after this function returns. @@ -212,25 +247,27 @@ returns. - +Invokes the closure. -@closure: -@return_value: -@n_param_values: -@param_values: -@invocation_hint: +@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 #GValues holding the arguments on + which to invoke the callback of @closure +@invocation_hint: a context-dependent invocation hint -This function 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. +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, and since invalidation notifiers may unreference the closure, @closure should be considered an invalidated pointer -atfer this function, unles g_closure_ref() was called beforehand. +after this function, unless g_closure_ref() was called beforehand. @closure: GClosure to invalidate @@ -238,83 +275,144 @@ atfer this function, unles g_closure_ref() was called beforehand. - +Registers a finalization notifier which will be called when the reference +count of @closure goes down to 0. Finalization notifiers are invoked after +invalidation notifiers, in an unspecified order. -@closure: -@notify_data: -@notify_func: +@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. -@closure: -@notify_data: -@notify_func: +@closure: a #GClosure +@notify_data: data to pass to @notify_func +@notify_func: the callback function to register - +Removes a finalization notifier. Notifiers may only be removed before or +during their invocation. -@closure: -@notify_data: -@notify_func: +@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 invalidation notifier. Notifiers may only be removed before or +during their invocation. -@closure: -@notify_data: -@notify_func: +@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 - +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 */ -@sizeof_closure: -@data: -@Returns: + g_closure_add_finalize_notifier (closure, notify_data, + my_closure_finalize); + return my_closure; +} + + + +@sizeof_closure: the size of the structure to allocate, must be at least +sizeof (GClosure) +@data: data to store in the @data field of the newly allocated #GClosure +@Returns: a newly allocated #GClosure - +Sets the marshaller of @closure. A marshaller set with g_closure_set_marshal() +should interpret its @marshal_data argument as a callback function to be +invoked instead of @closure->callback, provided it is not %NULL. GObject provides a number of predefined marshallers for use with #GCClosures, +see the g_cclosure_marshal_*() functions. -@closure: -@marshal: +@closure: a #GClosure +@marshal: a #GClosureMarshal function - +Adds a pair of notifiers which get invoked before and after the closure +callback, respectively. See g_object_watch_closure() for a use of marshal +guards. -@closure: -@pre_marshal_data: -@pre_marshal_notify: -@post_marshal_data: -@post_marshal_notify: +@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 - +Sets the meta marshaller of @closure. A meta marshaller +should use its @marshal_data argument together with @closure->data +to determine the callback function to use, and pass it as @marshal_data +to @closure->marshal. + + +As an example for the use of a meta marshaller, consider a closure whose +@data member contains a pointer to a class structure. The meta marshaller +could then be given an offset into this struct in @marshal_data, and use +it to determine the class member function to use as callback. This is +how class closures for signals are actually implemented in GObject. -@closure: -@marshal_data: -@meta_marshal: +@closure: a #GClosure +@marshal_data: context-dependent data to pass to @meta_marshal +@meta_marshal: a #GClosureMarshal function @@ -345,3 +443,312 @@ The #GType for #GIOCondition. + + +A marshaller for a #GCClosure with a callback of type +void (*callback) (gpointer instance, gpointer user_data). + + +@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 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 +void (*callback) (gpointer instance, gboolean arg1, gpointer user_data). + + +@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 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 +void (*callback) (gpointer instance, gchar arg1, gpointer user_data). + + +@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 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 +void (*callback) (gpointer instance, guchar arg1, gpointer user_data). + + +@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 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 +void (*callback) (gpointer instance, gint arg1, gpointer user_data). + + +@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 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 +void (*callback) (gpointer instance, guint arg1, gpointer user_data). + + +@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 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 +void (*callback) (gpointer instance, glong arg1, gpointer user_data). + + +@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 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 +void (*callback) (gpointer instance, gulong arg1, gpointer user_data). + + +@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 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 +void (*callback) (gpointer instance, gint arg1, gpointer user_data) where the #gint parameter denotes an enumeration type.. + + +@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 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 +void (*callback) (gpointer instance, gint arg1, gpointer user_data) where the #gint parameter denotes a flags type +denotes a flags type. + + +@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 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 +void (*callback) (gpointer instance, gfloat arg1, gpointer user_data). + + +@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 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 +void (*callback) (gpointer instance, gdouble arg1, gpointer user_data). + + +@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 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 +void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data). + + +@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 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 +void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data). + + +@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 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 +void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data). + + +@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 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 +void (*callback) (gpointer instance, gpointer arg1, gpointer user_data). + + +@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 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 +void (*callback) (gpointer instance, GOBject *arg1, gpointer user_data). + + +@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 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 +void (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data). + + +@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 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 +void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data). + + +@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 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 +gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data) where the #gint parameter +denotes a flags type. + + +@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 the last argument + to g_closure_invoke() +@marshal_data: additional data specified when registering the marshaller + + + + +Another name for g_cclosure_marshal_BOOLEAN__FLAGS(). + + + + -- 2.7.4