From 90ec3d3499d4e6de2deb503bc8c1772a670dcd45 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 6 Feb 2024 15:43:12 +0000 Subject: [PATCH] gtask: Clarify when GTask:completed is suitable to use MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It’s not suitable to use to check if your own code has already called `g_task_return_*()`, as it doesn’t directly correlate to that. Signed-off-by: Philip Withnall --- gio/gtask.c | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/gio/gtask.c b/gio/gtask.c index dd5730bd5..e6815e2d0 100644 --- a/gio/gtask.c +++ b/gio/gtask.c @@ -2454,9 +2454,18 @@ g_task_class_init (GTaskClass *klass) * GTask:completed: * * Whether the task has completed, meaning its callback (if set) has been - * invoked. This can only happen after g_task_return_pointer(), + * invoked. + * + * This can only happen after g_task_return_pointer(), * g_task_return_error() or one of the other return functions have been called - * on the task. + * on the task. However, it is not guaranteed to happen immediately after + * those functions are called, as the task’s callback may need to be scheduled + * to run in a different thread. + * + * That means it is **not safe** to use this property to track whether a + * return function has been called on the #GTask. Callers must do that + * tracking themselves, typically by linking the lifetime of the #GTask to the + * control flow of their code. * * This property is guaranteed to change from %FALSE to %TRUE exactly once. *