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 (file)
--- 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 (file)
--- 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.