Commit d80f0923 authored by Matthias Clasen's avatar Matthias Clasen

More doc improvements

svn path=/trunk/; revision=5997
parent 7d85d557
2007-11-29 Matthias Clasen <mclasen@redhat.com>
* gasyncresult.c: Add another paragraph to the intro,
adjust coding style of example.
2007-11-29 A. Walton <awalton@svn.gnome.org>
* gappinfo.c:
......
......@@ -35,54 +35,70 @@
*
* 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 asynchronous
* function. This callback will be triggered when the operation has completed,
* and will be passed a #GAsyncReady 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()" operation with the
* object the function was called for, and the #GAsyncReady instance, and optionally,
* 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 with the object the function
* was called for, and the #GAsyncResult instance, and optionally,
* an @error to grab any error conditions that may have occurred.
*
* The purpose of the "_finish()" function is to take the generic
* result of type #GAsyncResult and return the specific result
* that the operation in question yields (e.g. a #GFileEnumerator 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()" function, GIO will take care of cleaning up the
* result and error information after the #GAsyncReadyCallback
* returns.
*
* Example of a typical asynchronous operation flow:
* <informalexample>
* <programlisting>
* void _theoretical_frobnitz_async (Theoretical *t,
* GCancellable *c,
* |[
* void _theoretical_frobnitz_async (Theoretical *t,
* GCancellable *c,
* GAsyncReadyCallback *cb,
* gpointer u);
* gpointer u);
*
* gboolean _theoretical_frobnitz_finish (Theoretical *t,
* GAsyncResult *res,
* GError **e);
* gboolean _theoretical_frobnitz_finish (Theoretical *t,
* GAsyncResult *res,
* GError **e);
*
* static void
* frobnitz_result_func (GObject *source_object,
* frobnitz_result_func (GObject *source_object,
* GAsyncResult *res,
* gpointer user_data)
* gpointer user_data)
* {
* gboolean success = FALSE;
* success = _theoretical_frobnitz_finish( source_object, res, NULL );
*
* success = _theoretical_frobnitz_finish (source_object, res, NULL);
*
* if (success)
* g_printf("Hurray!/n");
* g_printf ("Hurray!/n");
* else
* g_printf("Uh oh!/n");
* g_printf ("Uh oh!/n");
*
* /<!-- -->* ... *<!-- -->/
* g_free(res);
*
* g_free (res);
* }
*
* int main (int argc, void *argv[])
* {
* /<!-- -->* ... *<!-- -->/
* _theoretical_frobnitz_async (theoretical_data, NULL, frobnitz_result_func, NULL);
*
* _theoretical_frobnitz_async (theoretical_data,
* NULL,
* frobnitz_result_func,
* NULL);
*
* /<!-- -->* ... *<!-- -->/
* </programlisting>
* </informalexample>
* }
* ]|
*
* Asynchronous jobs are threaded if #GThread is available, but also may
* be sent to the Main Event Loop and processed in an idle function.
*
**/
static void g_async_result_base_init (gpointer g_class);
......
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