glib/docs/reference/gobject/tmpl/gclosure.sgml
Matthias Clasen 280a213b09 Move all docs out-of-line. Boy, what a waste of time.
2003-02-07  Matthias Clasen  <maclas@gmx.de>

	* gobject/tmpl/gtypemodule.sgml:
	* gobject/tmpl/gtype.sgml:
	* gobject/tmpl/gclosure.sgml:
	* gobject/tmpl/param_value_types.sgml:
	* gobject/tmpl/gparamspec.sgml:
	* gobject/tmpl/objects.sgml:
	* gobject/tmpl/signals.sgml: Move all docs out-of-line. Boy, what
	a waste of time.
2003-02-07 22:08:53 +00:00

348 lines
5.6 KiB
Plaintext

<!-- ##### SECTION Title ##### -->
Closures
<!-- ##### SECTION Short_Description ##### -->
Functions as first-class objects
<!-- ##### SECTION Long_Description ##### -->
<para>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### MACRO G_CLOSURE_NEEDS_MARSHAL ##### -->
<para>
</para>
@closure:
<!-- ##### MACRO G_CLOSURE_N_NOTIFIERS ##### -->
<para>
</para>
@cl:
<!-- ##### MACRO G_CCLOSURE_SWAP_DATA ##### -->
<para>
</para>
@cclosure:
<!-- ##### MACRO G_CALLBACK ##### -->
<para>
</para>
@f:
<!-- ##### USER_FUNCTION GCallback ##### -->
<para>
</para>
<!-- ##### STRUCT GClosure ##### -->
<para>
</para>
@in_marshal:
@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>
</para>
@closure:
@callback:
<!-- ##### USER_FUNCTION GClosureMarshal ##### -->
<para>
</para>
@closure:
@return_value:
@n_param_values:
@param_values:
@invocation_hint:
@marshal_data:
<!-- ##### USER_FUNCTION GClosureNotify ##### -->
<para>
</para>
@data:
@closure:
<!-- ##### STRUCT GClosureNotifyData ##### -->
<para>
</para>
@data:
@notify:
<!-- ##### FUNCTION g_cclosure_new ##### -->
<para>
</para>
@callback_func:
@user_data:
@destroy_data:
@Returns:
<!-- ##### FUNCTION g_cclosure_new_swap ##### -->
<para>
</para>
@callback_func:
@user_data:
@destroy_data:
@Returns:
<!-- ##### FUNCTION g_cclosure_new_object ##### -->
<para>
</para>
@callback_func:
@object:
@Returns:
<!-- ##### FUNCTION g_cclosure_new_object_swap ##### -->
<para>
</para>
@callback_func:
@object:
@Returns:
<!-- ##### FUNCTION g_closure_new_object ##### -->
<para>
</para>
@sizeof_closure:
@object:
@Returns:
<!-- ##### FUNCTION g_closure_ref ##### -->
<para>
Increment 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>
Take 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
to call this function, for example like this:
<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>
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>
Decrement 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.
</para>
@closure: #GClosure to decrement the reference count on
<!-- ##### FUNCTION g_closure_invoke ##### -->
<para>
</para>
@closure:
@return_value:
@n_param_values:
@param_values:
@invocation_hint:
<!-- ##### FUNCTION g_closure_invalidate ##### -->
<para>
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.
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.
</para>
@closure: GClosure to invalidate
<!-- ##### FUNCTION g_closure_add_finalize_notifier ##### -->
<para>
</para>
@closure:
@notify_data:
@notify_func:
<!-- ##### FUNCTION g_closure_add_invalidate_notifier ##### -->
<para>
</para>
@closure:
@notify_data:
@notify_func:
<!-- ##### FUNCTION g_closure_remove_finalize_notifier ##### -->
<para>
</para>
@closure:
@notify_data:
@notify_func:
<!-- ##### FUNCTION g_closure_remove_invalidate_notifier ##### -->
<para>
</para>
@closure:
@notify_data:
@notify_func:
<!-- ##### FUNCTION g_closure_new_simple ##### -->
<para>
</para>
@sizeof_closure:
@data:
@Returns:
<!-- ##### FUNCTION g_closure_set_marshal ##### -->
<para>
</para>
@closure:
@marshal:
<!-- ##### FUNCTION g_closure_add_marshal_guards ##### -->
<para>
</para>
@closure:
@pre_marshal_data:
@pre_marshal_notify:
@post_marshal_data:
@post_marshal_notify:
<!-- ##### FUNCTION g_closure_set_meta_marshal ##### -->
<para>
</para>
@closure:
@marshal_data:
@meta_marshal:
<!-- ##### 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>