[geany/geany] 95edb9: Add a warning about using plugin_signal_connect() on short-lived objects

[Colomban Wendling]

Branch:      refs/heads/master
Author:      Colomban Wendling <ban at herbesfolles.org>
Committer:   Colomban Wendling <ban at herbesfolles.org>
Date:        Fri, 11 Apr 2014 21:23:35 UTC
Commit:      95edb95a38dad3755a0b6fd5820b82d25c021f8f
             https://github.com/geany/geany/commit/95edb95a38dad3755a0b6fd5820b82d25c021f8f

Log Message:
-----------
Add a warning about using plugin_signal_connect() on short-lived objects


Modified Paths:
--------------
    src/pluginutils.c

Modified: src/pluginutils.c
15 files changed, 14 insertions(+), 1 deletions(-)
===================================================================
@@ -103,7 +103,20 @@ void plugin_module_make_resident(GeanyPlugin *plugin)
  * (if supported by @a signal_name).
  * @param callback The function to call when the signal is emitted.
  * @param user_data The user data passed to the signal handler.
- * @see plugin_callbacks. */
+ * @see plugin_callbacks.
+ *
+ * @warning This should only be used on objects that outlive the plugin, never on
+ *          objects that will get destroyed before the plugin is unloaded.  For objects
+ *          created and destroyed by the plugin, you can simply use @c g_signal_connect(),
+ *          since all handlers are disconnected when the object is destroyed anyway.
+ *          For objects that may or may not outlive the plugin (like @link GeanyEditor.sci
+ *          a document's @c ScintillaObject @endlink, which is destroyed when the document
+ *          is closed), you currently have to manually handle both situations, when the
+ *          plugin is unloaded before the object is destroyed (and then, you have to
+ *          disconnect the signal on @c plugin_cleanup()), and when the object is destroyed
+ *          during the plugin's lifetime (in which case you cannot and should not disconnect
+ *          manually in @c plugin_cleanup() since it already has been disconnected and the
+ *          object has been destroyed), and disconnect yourself or not as appropriate. */
 void plugin_signal_connect(GeanyPlugin *plugin,
 		GObject *object, const gchar *signal_name, gboolean after,
 		GCallback callback, gpointer user_data)



--------------
This E-Mail was brought to you by github_commit_mail.py (Source: https://github.com/geany/infrastructure).