Commit 7339a093 authored by Debarshi Ray's avatar Debarshi Ray

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
parent 09d936c5
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment