From: Owen Taylor <otaylor@redhat.com>
Date: Sun, 14 Mar 2004 16:34:23 +0000 (+0000)
Subject: Document the fact that g_signal_connect_object() does *not* remove the
X-Git-Tag: GLIB_2_4_0~8
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=8e4b5453a7e96576904a3e004cf1366b483af46f;p=platform%2Fupstream%2Fglib.git

Document the fact that g_signal_connect_object() does *not* remove the

Sun Mar 14 11:00:41 2004  Owen Taylor  <otaylor@redhat.com>

        * gobject/tmpl/signals.sgml: Document the fact that
        g_signal_connect_object() does *not* remove the signal
        when the object is disconnected currently and describe
        a workaround to prevent memory leaks.
---

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index ff716dc..db6294c 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,10 @@
+Sun Mar 14 11:00:41 2004  Owen Taylor  <otaylor@redhat.com>
+
+	* gobject/tmpl/signals.sgml: Document the fact that
+	g_signal_connect_object() does *not* remove the signal
+	when the object is disconnected currently and describe
+	a workaround to prevent memory leaks.
+
 Tue Mar  9 09:16:11 2004  Owen Taylor  <otaylor@redhat.com>
 
 	* === Released 2.3.6 ===
diff --git a/docs/reference/gobject/tmpl/signals.sgml b/docs/reference/gobject/tmpl/signals.sgml
index 963220b..12ada40 100644
--- a/docs/reference/gobject/tmpl/signals.sgml
+++ b/docs/reference/gobject/tmpl/signals.sgml
@@ -490,7 +490,29 @@ calling the handler.
 <!-- ##### FUNCTION g_signal_connect_object ##### -->
 <para>
  This is similar to g_signal_connect_data(), but uses a closure which
- ensures that the object stays alive during the call to @c_handler.
+ ensures that the @gobject stays alive during the call to @c_handler
+ by temporarily adding a reference count to @gobject.
+</para>
+<para>
+ Note that there this a bug in GObject that makes this function
+ much less useful than it might seem otherwise. Once @gobject is
+ disposed, the callback will no longer be called, but, the signal
+ handler is <emphasis>not</emphasis> currently disconnected. If the
+ @instance is itself being freed at the same time than this doesn't
+ matter, since the signal will automatically be removed, but
+ if @instance persists, then the signal handler will leak. You
+ should not remove the signal yourself because in a future versions of
+ GObject, the handler <emphasis>will</emphasis> automatically
+ be disconnected.
+</para>
+<para>
+ It's possible to work around this problem in a way that will
+ continue to work with future versions of GObject by checking
+ that the signal handler is still connected before disconnected it:
+<informalexample><programlisting>
+ if (g_signal_handler_is_connected (instance, id))
+   g_signal_handler_disconnect (instance, id);
+</informalexample></example>
 </para>
 
 @instance: the instance to connect to.