luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-08-01 15:03:39 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: Expand introduction to mention using async calls over sync ones

Browse Source 
As discussed on the mailing list (see the whole thread):
    https://mail.gnome.org/archives/desktop-devel-list/2015-February/msg00126.html

Expand the GIO documentation introduction to talk a little about when to
use async and sync functions, and how the former should almost always be
preferred over the latter.

Link to this from the GFile documentation, which is an entry point for a
lot of async calls.

https://bugzilla.gnome.org/show_bug.cgi?id=744722
This commit is contained in:
Philip Withnall
2015-02-18 17:01:18 +00:00
parent f829bde76a
commit 430814992d
2 changed files with 61 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
docs/reference/gio/overview.xml
View File

@@ -190,6 +190,58 @@
</simplesect>
<simplesect id="async-programming"><title>Asynchronous Programming</title>
<para>
Many GIO functions come in two versions: synchronous and asynchronous,
denoted by an <code>_async</code> suffix. It is important to use these
appropriately: synchronous calls should not be used from
within a main loop which is shared with other code, such as one in the
application’s main thread. Synchronous calls block until they complete,
and I/O operations can take noticeable amounts of time (even on ‘fast’
SSDs). Blocking a main loop iteration while waiting for I/O means that
other sources in the main loop will not be dispatched, such as input and
redraw handlers for the application’s UI. This can cause the application
to ‘freeze’ until I/O completes.
</para>
<para>
A few self-contained groups of functions, such as code generated by
<link linkend="gdbus-codegen"><application>gdbus-codegen</application></link>,
use a different convention: functions are asynchronous default, and it is
the <emphasis>synchronous</emphasis> version which has a
<code>_sync</code>
suffix. Aside from naming differences, they should be treated the same
way as functions following the normal convention above.
</para>
<para>
The asynchronous (<code>_async</code>) versions of functions return
control to the caller immediately, after scheduling the I/O in the kernel
and adding a callback for it to the main loop. This callback will be
invoked when the operation has completed. From the callback, the paired
<code>_finish</code> function should be called to retrieve the return
value of the I/O operation, and any errors which occurred. For more
information on using and implementing asynchronous functions, see
<link linkend="GAsyncResult.description"><type>GAsyncResult</type></link>
and <link linkend="GTask.description"><type>GTask</type></link>.
</para>
<para>
By starting multiple asynchronous operations in succession, they will be
executed in parallel (up to an arbitrary limit imposed by GIO’s internal
worker thread pool).
</para>
<para>
The synchronous versions of functions can be used early in application
startup when there is no main loop to block, for example to load initial
configuration files. They can also be used for I/O on files which are
guaranteed to be small and on the local disk. Note that the user’s home
directory is not guaranteed to be on the local disk.
</para>
</simplesect>
<simplesect><title>Security</title>
<para>