gtask: Document that g_task_run_in_thread() uses a shared resource

It’s a bad idea to use it without some care for how much it’s being
called in parallel, or dependencies between tasks. If the thread pool
gets exhausted by too many inter-dependent calls to
`g_task_run_in_thread()` then the process will livelock.

Signed-off-by: Philip Withnall <pwithnall@endlessos.org>

1 files changed, 7 insertions, 0 deletions

diff --git a/gio/gtask.c b/gio/gtask.c
index 80df75286..5038cc57e 100644
--- a/gio/gtask.c
+++ b/gio/gtask.c
@@ -1634,6 +1634,13 @@ g_task_start_task_thread (GTask           *task,
  * tasks), but don't want them to all run at once, you should only queue a
  * limited number of them (around ten) at a time.
  *
+ * Be aware that if your task depends on other tasks to complete, use of this
+ * function could lead to a livelock if the other tasks also use this function
+ * and enough of them (around 10) execute in a dependency chain, as that will
+ * exhaust the thread pool. If this situation is possible, consider using a
+ * separate worker thread or thread pool explicitly, rather than using
+ * g_task_run_in_thread().
+ *
  * Since: 2.36
  */
 void