From 7339a09376dfe39934e7f59b8760dbb7ebb731cd Mon Sep 17 00:00:00 2001 From: Debarshi Ray Date: Fri, 16 Jun 2017 14:47:33 +0200 Subject: [PATCH] docs: Mention the idiomatic way of invoking a GAsyncReadyCallback The GAsyncResult documentation didn't specify the context in which the GAsyncReadyCallback is expected to be invoked. Since asynchronous operations can be implemented in various ways involving GSources, threads and coroutines, it is useful to mention what the standard expections are. Unfortunately, since this was left undefined for so long, we can only phrase it as a suggestion, and not as a hard requirement. https://bugzilla.gnome.org/show_bug.cgi?id=783825 --- gio/gasyncresult.c | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/gio/gasyncresult.c b/gio/gasyncresult.c index cffe88964..b96f1eeab 100644 --- a/gio/gasyncresult.c +++ b/gio/gasyncresult.c @@ -36,13 +36,16 @@ * which are chained together by a #GAsyncReadyCallback. To begin * an asynchronous operation, provide a #GAsyncReadyCallback to the * asynchronous function. This callback will be triggered when the - * operation has completed, and will be passed a #GAsyncResult instance - * filled with the details of the operation's success or failure, the - * object the asynchronous function was started for and any error codes - * returned. The asynchronous callback function is then expected to call - * the corresponding "_finish()" function, passing the object the - * function was called for, the #GAsyncResult instance, and (optionally) - * an @error to grab any error conditions that may have occurred. + * operation has completed, and must be run in a later iteration of + * the [thread-default main context][g-main-context-push-thread-default] + * from where the operation was initiated. It will be passed a + * #GAsyncResult instance filled with the details of the operation's + * success or failure, the object the asynchronous function was + * started for and any error codes returned. The asynchronous callback + * function is then expected to call the corresponding "_finish()" + * function, passing the object the function was called for, the + * #GAsyncResult instance, and (optionally) an @error to grab any + * error conditions that may have occurred. * * The "_finish()" function for an operation takes the generic result * (of type #GAsyncResult) and returns the specific result that the