gtask: Document signal handler reference counting

Explain why the signal handler holds a reference to the GTask, even
though that causes a reference loop at first glance.

https://bugzilla.gnome.org/show_bug.cgi?id=736806

diff --git a/gio/gtask.c b/gio/gtask.c
index ffa4dae..cc8de9b 100644 (file)
--- a/gio/gtask.c
+++ b/gio/gtask.c
@@ -1274,6 +1274,14 @@ g_task_start_task_thread (GTask           *task,
           return;
         }
 
+      /* This introduces a reference count loop between the GTask and
+       * GCancellable, but is necessary to avoid a race on finalising the GTask
+       * between task_thread_cancelled() (in one thread) and
+       * g_task_thread_complete() (in another).
+       *
+       * Accordingly, the signal handler *must* be removed once the task has
+       * completed.
+       */
       g_signal_connect_data (task->cancellable, "cancelled",
                              G_CALLBACK (task_thread_cancelled),
                              g_object_ref (task),