From 3ed45914ee441d76822c26bf2f34d79fd3c2d7df Mon Sep 17 00:00:00 2001 From: Gian Mario Tagliaretti Date: Tue, 24 Mar 2009 23:56:09 +0000 Subject: Add gio.SimpleAsyncResult in docs. 2009-03-25 Gian Mario Tagliaretti * docs/Makefile.am: * docs/reference/pygio-classes.xml: * docs/reference/pygio-simpleasyncresult.xml: Add gio.SimpleAsyncResult in docs. svn path=/trunk/; revision=1034 --- docs/reference/ChangeLog | 7 + docs/reference/pygio-classes.xml | 1 + docs/reference/pygio-simpleasyncresult.xml | 317 +++++++++++++++++++++++++++++ 3 files changed, 325 insertions(+) create mode 100644 docs/reference/pygio-simpleasyncresult.xml (limited to 'docs/reference') diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index a5c7943..7ad8485 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,10 @@ +2009-03-25 Gian Mario Tagliaretti + + * docs/Makefile.am: + * docs/reference/pygio-classes.xml: + * docs/reference/pygio-simpleasyncresult.xml: + Add gio.SimpleAsyncResult in docs. + 2009-03-24 Gian Mario Tagliaretti * docs/reference/pygio-classes.xml: diff --git a/docs/reference/pygio-classes.xml b/docs/reference/pygio-classes.xml index b6a3a7a..e49d65f 100644 --- a/docs/reference/pygio-classes.xml +++ b/docs/reference/pygio-classes.xml @@ -17,6 +17,7 @@ + diff --git a/docs/reference/pygio-simpleasyncresult.xml b/docs/reference/pygio-simpleasyncresult.xml new file mode 100644 index 0000000..f6a0787 --- /dev/null +++ b/docs/reference/pygio-simpleasyncresult.xml @@ -0,0 +1,317 @@ + + + + + + gio.SimpleAsyncResult + Simple asynchronous results implementation. + + + + Synopsis + + + gio.SimpleAsyncResult + gobject.GObject + + + complete + + + + complete_in_idle + + + + get_op_res_gboolean + + + + get_op_res_gssize + + + + propagate_error + + + + set_handle_cancellation + handle_cancellation + + + set_op_res_gboolean + op_res + + + set_op_res_gssize + op_res + + + + + + + + Ancestry + ++-- gobject.GObject + +-- gio.SimpleAsyncResult + + + + + + Implemented Interface + + gio.SimpleAsyncResult implements + gio.AsyncResult. + + + + + Description + + + Implements gio.AsyncResult + for simple cases. Most of the time, this will be all an application needs, and will be used transparently + Because of this, GSimpleAsyncResult is used throughout GIO for handling asynchronous functions. + + + gio.SimpleAsyncResult + handles GAsyncReadyCallbacks, error reporting, operation cancellation and the final state of an + operation, completely transparent to the application. Results can be returned as a pointer e.g. + for functions that return data that is collected asynchronously, a boolean value for checking the + success or failure of an operation, or a gssize for operations which return the number of bytes modified + by the operation; all of the simple return cases are covered. + + + Most of the time, an application will not need to know of the details of this API; it is handled + transparently, and any necessary operations are handled by GAsyncResult's interface. However, if + implementing a new GIO module, for writing language bindings, or for complex applications that need + better control of how asynchronous operations are completed, it is important to understand this functionality. + + + gio.SimpleAsyncResult + are tagged with the calling function to ensure that asynchronous functions and + their finishing functions are used together correctly. + + + + An asynchronous operation can be made to ignore a cancellation event by calling + gio.SimpleAsyncResult.set_handle_cancellation() + with a + gio.AsyncResult + for the operation and False. This is useful for operations that are dangerous to cancel, + such as close (which would cause a leak if cancelled before being run). + + + gio.AsyncResult + can integrate into GLib's event loop, GMainLoop, or it can use GThreads if available. + gio.SimpleAsyncResult.complete() + will finish an I/O task directly within the main event loop. + gio.SimpleAsyncResult.complete_in_idle() + will integrate the I/O task into the main event loop as an idle function. + + + + To set the results of an asynchronous function, + gio.SimpleAsyncResult.set_op_res_gboolean(), and + gio.SimpleAsyncResult.set_op_res_gssize() + are provided, setting the operation's result to a gboolean, or gssize, respectively. + + + Likewise, to get the result of an asynchronous function, + gio.SimpleAsyncResult.get_op_res_gboolean() and + gio.SimpleAsyncResult.get_op_res_gssize() + are provided, getting the operation's result as a gboolean and gssize, respectively. + + + + + Methods + + + gio.SimpleAsyncResult.complete + + + complete + + + + + + + + The complete() method completes an asynchronous I/O job. + Must be called in the main thread, as it invokes the callback that should be called + in the main thread. If you are in a different thread use + gio.SimpleAsyncResult.complete_in_idle(). + + + + + gio.SimpleAsyncResult.complete_in_idle + + + complete_in_idle + + + + + + + + The complete_in_idle() method completes an asynchronous + function in the main event loop using an idle function. + + + + + gio.SimpleAsyncResult.get_op_res_gboolean + + + get_op_res_gboolean + + + + + + Returns : + True if the operation's result was + True, False if the operation's result + was False. + + + + + + The get_op_res_gboolean() method gets the operation + result boolean from within the asynchronous result. + + + + + gio.SimpleAsyncResult.get_op_res_gssize + + + get_op_res_gssize + + + + + + Returns : + a gssize returned from the asynchronous function. + + + + + + The get_op_res_gssize() method gets a gssize + from the asynchronous result. + + + + + gio.SimpleAsyncResult.propagate_error + + + propagate_error + + + + + + Returns : + True if the error was propegated + to dest. False otherwise. + + + + + + The propagate_error() method propagates an error + from within the simple asynchronous result to a given destination. + + + + + gio.SimpleAsyncResult.set_handle_cancellation + + + set_handle_cancellation + handle_cancellation + + + + + handle_cancellation : + a boolean. + + + + + + The set_handle_cancellation() method sets whether + to handle cancellation within the asynchronous operation. + + + + + gio.SimpleAsyncResult.set_op_res_gboolean + + + set_op_res_gboolean + op_res + + + + + op_res : + a boolean. + + + + + + The set_op_res_gboolean() method sets the operation + result to a boolean within the asynchronous result. + + + + + gio.SimpleAsyncResult.set_op_res_gssize + + + set_op_res_gssize + op_res + + + + + op_res : + a gssize. + + + + + + The set_op_res_gssize() method sets the operation + result within the asynchronous result to the given op_res. + + + + -- cgit