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

doc common functions like ref/ sink/unref/invalidate.

Browse Source 
Mon Feb  4 17:55:39 2002  Tim Janik  <timj@gtk.org>

        * gobject/tmpl/closures.sgml: doc common functions like ref/
        sink/unref/invalidate.
This commit is contained in:
Tim Janik 2002-02-04 18:08:23 +00:00 committed by Tim Janik
parent 179963de91
commit c73fba247b
3 changed files with 57 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/reference/ChangeLog
View File

@ -1,6 +1,9 @@
Mon Feb 4 17:55:39 2002 Tim Janik <timj@gtk.org>
* gobject/tmpl/closures.sgml: doc common functions like ref/
sink/unref/invalidate.
* gobject/tmpl/objects.sgml: document g_obejct_watch_closure() and
* gobject/tmpl/objects.sgml: document g_object_watch_closure() and
qdata functions.
Tue Jan 29 12:00:59 2002 Owen Taylor <otaylor@redhat.com>

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

@ -58,7 +58,7 @@ Closures
</para>
@is_invalid:
@is_invalid: Indicates whether the closure has been invalidated by g_closure_invalidate()
<!-- ##### MACRO G_TYPE_CLOSURE ##### -->
<para>
@ -159,27 +159,54 @@ Closures
<!-- ##### 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:
@Returns:
@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:
<msgtext><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></msgtext>
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:
@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:
@closure: #GClosure to decrement the reference count on
<!-- ##### FUNCTION g_closure_invoke ##### -->
@ -196,10 +223,12 @@ Closures
<!-- ##### 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.
</para>
@closure:
@closure: GClosure to invalidate
<!-- ##### FUNCTION g_closure_add_finalize_notifier ##### -->

27
docs/reference/gobject/tmpl/objects.sgml
View File

@ -389,6 +389,17 @@ to match the one used with g_object_add_weak_pointer().
@Returns:
<!-- ##### FUNCTION g_object_get_qdata ##### -->
<para>
This function gets back user data pointers stored via
g_object_set_qdata().
</para>
@object: The GObject to get a stored user data pointer from
@quark: A #GQuark, naming the user data pointer
@Returns: The user data pointer set, or %NULL
<!-- ##### FUNCTION g_object_set_qdata ##### -->
<para>
This sets an opaque, named pointer on an object.
@ -406,17 +417,6 @@ removes the data stored.
@data: An opaque user data pointer
<!-- ##### FUNCTION g_object_get_qdata ##### -->
<para>
This function gets back user data pointers stored via
g_object_set_qdata().
</para>
@object: The GObject to get a stored user data pointer from
@quark: A #GQuark, naming the user data pointer
@Returns: The user data pointer set, or %NULL
<!-- ##### FUNCTION g_object_set_qdata_full ##### -->
<para>
This function works like g_object_set_qdata(), but in addition,
@ -465,7 +465,7 @@ free_string_list (gpointer data)
g_list_free (list);
}
</programlisting></msgtext>
Using g_object_get_qdata() in teh above example, instead of g_object_steal_qdata()
Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata()
would have left the destroy function set, and thus the partial string list would
have been freed upon g_object_set_qdata_full().
</para>
@ -540,7 +540,8 @@ as closure data.
</para>
@object: GObject restricting lifetime of @closure
@closure: GClosure to watch
@closure: GClosure to watch
<!-- ##### FUNCTION g_object_run_dispose ##### -->
<para>