From c73fba247b1a0894b901f4d9203281126b55ddb5 Mon Sep 17 00:00:00 2001 From: Tim Janik Date: Mon, 4 Feb 2002 18:08:23 +0000 Subject: [PATCH] doc common functions like ref/ sink/unref/invalidate. Mon Feb 4 17:55:39 2002 Tim Janik * gobject/tmpl/closures.sgml: doc common functions like ref/ sink/unref/invalidate. --- docs/reference/ChangeLog | 5 ++- docs/reference/gobject/tmpl/gclosure.sgml | 53 ++++++++++++++++++++++++------- docs/reference/gobject/tmpl/objects.sgml | 27 ++++++++-------- 3 files changed, 59 insertions(+), 26 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 3d603f7..8e04a1b 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,6 +1,9 @@ Mon Feb 4 17:55:39 2002 Tim Janik + + * 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 diff --git a/docs/reference/gobject/tmpl/gclosure.sgml b/docs/reference/gobject/tmpl/gclosure.sgml index 54f7733..5c26553 100644 --- a/docs/reference/gobject/tmpl/gclosure.sgml +++ b/docs/reference/gobject/tmpl/gclosure.sgml @@ -58,7 +58,7 @@ Closures -@is_invalid: +@is_invalid: Indicates whether the closure has been invalidated by g_closure_invalidate() @@ -159,27 +159,54 @@ Closures - +Increment the reference count on a closure to force it staying +alive while the caller holds a pointer to it. -@closure: -@Returns: +@closure: #GClosure to increment the reference count on +@Returns: The @closure passed in, for convenience - - - -@closure: +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: + +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); + } +} + +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. + + +@closure: #GClosure to decrement the initial reference count on, if it's + still being held - +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. -@closure: +@closure: #GClosure to decrement the reference count on @@ -196,10 +223,12 @@ Closures - +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. -@closure: +@closure: GClosure to invalidate diff --git a/docs/reference/gobject/tmpl/objects.sgml b/docs/reference/gobject/tmpl/objects.sgml index c1f0a2f..73e11c4 100644 --- a/docs/reference/gobject/tmpl/objects.sgml +++ b/docs/reference/gobject/tmpl/objects.sgml @@ -389,6 +389,17 @@ to match the one used with g_object_add_weak_pointer(). @Returns: + + +This function gets back user data pointers stored via +g_object_set_qdata(). + + +@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 + + This sets an opaque, named pointer on an object. @@ -406,17 +417,6 @@ removes the data stored. @data: An opaque user data pointer - - -This function gets back user data pointers stored via -g_object_set_qdata(). - - -@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 - - This function works like g_object_set_qdata(), but in addition, @@ -465,7 +465,7 @@ free_string_list (gpointer data) g_list_free (list); } -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(). @@ -540,7 +540,8 @@ as closure data. @object: GObject restricting lifetime of @closure -@closure: GClosure to watch +@closure: GClosure to watch + -- 2.7.4