[glib] gsignal: Document memory management best practices for signal handlers

[Philip Withnall <pwithnall src gnome org>]

commit ef1ba452b3302e75f767d6160cf8d379af55d90d
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Fri Dec 19 15:21:09 2014 +0000

    gsignal: Document memory management best practices for signal handlers
    
    It’s quite common to see naked g_signal_connect() calls without a paired
    g_signal_handler_disconnect(). This is commonly a bug which could lead
    to uses of the callback user data after it’s been freed.
    
    Document the best practices for avoiding this kind of bug by properly
    disconnecting all signal handlers.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=741779

 gobject/gsignal.c |   26 ++++++++++++++++++++++++++
 gobject/gsignal.h |    3 +++
 2 files changed, 29 insertions(+), 0 deletions(-)
---
diff --git a/gobject/gsignal.c b/gobject/gsignal.c
index b1d6e38..b52ce8c 100644
--- a/gobject/gsignal.c
+++ b/gobject/gsignal.c
@@ -97,6 +97,32 @@
  * Specification of no detail argument for signal handlers (omission of the
  * detail part of the signal specification upon connection) serves as a
  * wildcard and matches any detail argument passed in to emission.
+ *
+ * ## Memory management of signal handlers # {#signal-memory-management}
+ *
+ * If you are connecting handlers to signals and using a #GObject instance as
+ * your signal handler user data, you should remember to pair calls to
+ * g_signal_connect() with calls to g_signal_handler_disconnect() or
+ * g_signal_handlers_disconnect_by_func(). While signal handlers are
+ * automatically disconnected when the object emitting the signal is finalised,
+ * they are not automatically disconnected when the signal handler user data is
+ * destroyed. If this user data is a #GObject instance, using it from a
+ * signal handler after it has been finalised is an error.
+ *
+ * There are two strategies for managing such user data. The first is to
+ * disconnect the signal handler (using g_signal_handler_disconnect() or
+ * g_signal_handlers_disconnect_by_func()) when the user data (object) is
+ * finalised; this has to be implemented manually. For non-threaded programs,
+ * g_signal_connect_object() can be used to implement this automatically.
+ * Currently, however, it is unsafe to use in threaded programs.
+ *
+ * The second is to hold a strong reference on the user data until after the
+ * signal is disconnected for other reasons. This can be implemented
+ * automatically using g_signal_connect_data().
+ *
+ * The first approach is recommended, as the second approach can result in
+ * effective memory leaks of the user data if the signal handler is never
+ * disconnected for some reason.
  */
 
 
diff --git a/gobject/gsignal.h b/gobject/gsignal.h
index c0b0681..c934b42 100644
--- a/gobject/gsignal.h
+++ b/gobject/gsignal.h
@@ -465,6 +465,9 @@ void   g_signal_chain_from_overridden_handler (gpointer           instance,
  * Connects a #GCallback function to a signal for a particular object.
  * 
  * The handler will be called before the default handler of the signal.
+ *
+ * See [memory management of signal handlers][signal-memory-management] for
+ * details on how to handle the return value and memory management of @data.
  * 
  * Returns: the handler id (always greater than 0 for successful connections)
  */