luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-23 12:41:50 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Move the GAsyncResult SECTION

Browse Source 
Move the content to the struct docs.

Helps: #3037
This commit is contained in:
Matthias Clasen 2023-09-25 21:14:29 -04:00 committed by Philip Withnall
parent 331c137ee1
commit f7b5e3b37e
2 changed files with 25 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
gio/gasyncresult.c
View File

@ -27,42 +27,40 @@
/**
* SECTION:gasyncresult
* @short_description: Asynchronous Function Results
* @include: gio/gio.h
* @see_also: #GTask
* GAsyncResult:
*
* Provides a base class for implementing asynchronous function results.
* `GAsyncResult` provides a base class for implementing asynchronous function results.
*
* Asynchronous operations are broken up into two separate operations
* which are chained together by a #GAsyncReadyCallback. To begin
* an asynchronous operation, provide a #GAsyncReadyCallback to the
* 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 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()"
* the thread-default main context (see
* [method@GLib.MainContext.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
* `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
* operation in question yields (e.g. a #GFileEnumerator for a
* The `_finish()` function for an operation takes the generic result
* (of type `GAsyncResult`) and returns the specific result that the
* operation in question yields (e.g. a [struct@Gio.FileEnumerator] for a
* "enumerate children" operation). If the result or error status of the
* operation is not needed, there is no need to call the "_finish()"
* operation is not needed, there is no need to call the `_finish()`
* function; GIO will take care of cleaning up the result and error
* information after the #GAsyncReadyCallback returns. You can pass
* %NULL for the #GAsyncReadyCallback if you don't need to take any
* information after the `GAsyncReadyCallback` returns. You can pass
* `NULL` for the `GAsyncReadyCallback` if you don't need to take any
* action at all after the operation completes. Applications may also
* take a reference to the #GAsyncResult and call "_finish()" later;
* however, the "_finish()" function may be called at most once.
* take a reference to the `GAsyncResult` and call `_finish()` later;
* however, the `_finish()` function may be called at most once.
*
* Example of a typical asynchronous operation flow:
* |[<!-- language="C" -->
*
* ```c
* void _theoretical_frobnitz_async (Theoretical *t,
* GCancellable *c,
* GAsyncReadyCallback cb,
@ -101,20 +99,20 @@
*
* ...
* }
* ]|
* ```
*
* The callback for an asynchronous operation is called only once, and is
* always called, even in the case of a cancelled operation. On cancellation
* the result is a %G_IO_ERROR_CANCELLED error.
* the result is a `G_IO_ERROR_CANCELLED` error.
*
* ## I/O Priority # {#io-priority}
* ## I/O Priority
*
* Many I/O-related asynchronous operations have a priority parameter,
* which is used in certain cases to determine the order in which
* operations are executed. They are not used to determine system-wide
* I/O scheduling. Priorities are integers, with lower numbers indicating
* higher priority. It is recommended to choose priorities between
* %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT
* `G_PRIORITY_LOW` and `G_PRIORITY_HIGH`, with `G_PRIORITY_DEFAULT`
* as a default.
*/

6
gio/gasyncresult.h
View File

@ -36,12 +36,6 @@ G_BEGIN_DECLS
#define G_IS_ASYNC_RESULT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_ASYNC_RESULT))
#define G_ASYNC_RESULT_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_ASYNC_RESULT, GAsyncResultIface))
/**
* GAsyncResult:
*
* Holds results information for an asynchronous operation,
* usually passed directly to an asynchronous _finish() operation.
**/
typedef struct _GAsyncResultIface GAsyncResultIface;