diff options
author | Gian Mario Tagliaretti <gianmt@gnome.org> | 2009-03-24 23:56:09 +0000 |
---|---|---|
committer | Gian Mario Tagliaretti <gianmt@src.gnome.org> | 2009-03-24 23:56:09 +0000 |
commit | 3ed45914ee441d76822c26bf2f34d79fd3c2d7df (patch) | |
tree | e3bd14f496de18bbc4a6691592190a0bf9f37962 | |
parent | 1f8e8b0535dc82dc8b3a6ba9d4bc54ec426dc601 (diff) | |
download | pygobject-3ed45914ee441d76822c26bf2f34d79fd3c2d7df.tar.gz |
Add gio.SimpleAsyncResult in docs.
2009-03-25 Gian Mario Tagliaretti <gianmt@gnome.org>
* docs/Makefile.am:
* docs/reference/pygio-classes.xml:
* docs/reference/pygio-simpleasyncresult.xml:
Add gio.SimpleAsyncResult in docs.
svn path=/trunk/; revision=1034
-rw-r--r-- | docs/Makefile.am | 4 | ||||
-rw-r--r-- | docs/reference/ChangeLog | 7 | ||||
-rw-r--r-- | docs/reference/pygio-classes.xml | 1 | ||||
-rw-r--r-- | docs/reference/pygio-simpleasyncresult.xml | 317 |
4 files changed, 328 insertions, 1 deletions
diff --git a/docs/Makefile.am b/docs/Makefile.am index b974e67e..adb7672e 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -26,6 +26,7 @@ HTML_FILES = \ html/class-giofileenumerator.html \ html/class-giofileicon.html \ html/class-gioicon.html \ + html/class-giosimpleasyncresult.html \ html/gio-constants.html \ html/gio-class-reference.html \ html/gobject-constants.html \ @@ -61,7 +62,8 @@ XML_FILES = \ reference/pygio-icon.xml \ reference/pygio-fileattributeinfo.xml \ reference/pygio-fileenumerator.xml \ - reference/pygio-fileicon.xml + reference/pygio-fileicon.xml \ + reference/pygio-simpleasyncresult.xml XSL_FILES = \ xsl/common.xsl \ diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index a5c7943a..7ad8485d 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,10 @@ +2009-03-25 Gian Mario Tagliaretti <gianmt@gnome.org> + + * docs/Makefile.am: + * docs/reference/pygio-classes.xml: + * docs/reference/pygio-simpleasyncresult.xml: + Add gio.SimpleAsyncResult in docs. + 2009-03-24 Gian Mario Tagliaretti <gianmt@gnome.org> * docs/reference/pygio-classes.xml: diff --git a/docs/reference/pygio-classes.xml b/docs/reference/pygio-classes.xml index b6a3a7ae..e49d65fb 100644 --- a/docs/reference/pygio-classes.xml +++ b/docs/reference/pygio-classes.xml @@ -17,6 +17,7 @@ <xi:include href="pygio-fileenumerator.xml"/> <xi:include href="pygio-fileicon.xml"/> <xi:include href="pygio-icon.xml"/> +<xi:include href="pygio-simpleasyncresult.xml"/> <xi:include href="pygio-constants.xml"/> </chapter> diff --git a/docs/reference/pygio-simpleasyncresult.xml b/docs/reference/pygio-simpleasyncresult.xml new file mode 100644 index 00000000..f6a0787d --- /dev/null +++ b/docs/reference/pygio-simpleasyncresult.xml @@ -0,0 +1,317 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giosimpleasyncresult"> + <refnamediv> + <refname>gio.SimpleAsyncResult</refname> + <refpurpose>Simple asynchronous results implementation.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.SimpleAsyncResult</classname></ooclass> + <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giosimpleasyncresult--complete">complete</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giosimpleasyncresult--complete-in-idle">complete_in_idle</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giosimpleasyncresult--get-op-res-gboolean">get_op_res_gboolean</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giosimpleasyncresult--get-op-res-gssize">get_op_res_gssize</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giosimpleasyncresult--propagate-error">propagate_error</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giosimpleasyncresult--set-handle-cancellation">set_handle_cancellation</link></methodname> + <methodparam><parameter role="keyword">handle_cancellation</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giosimpleasyncresult--set-op-res-gboolean">set_op_res_gboolean</link></methodname> + <methodparam><parameter role="keyword">op_res</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giosimpleasyncresult--set-op-res-gssize">set_op_res_gssize</link></methodname> + <methodparam><parameter role="keyword">op_res</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-giosimpleasyncresult">gio.SimpleAsyncResult</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Implemented Interface</title> + <para> + <link linkend="class-giosimpleasyncresult"><classname>gio.SimpleAsyncResult</classname></link> implements + <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </para> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Implements <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> + 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. + </para> + <para> + <link linkend="class-giosimpleasyncresult"><classname>gio.SimpleAsyncResult</classname></link> + 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. + </para> + <para> + 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. + </para> + <para> + <link linkend="class-giosimpleasyncresult"><classname>gio.SimpleAsyncResult</classname></link> + are tagged with the calling function to ensure that asynchronous functions and + their finishing functions are used together correctly. + </para> + <!-- NEEDS LOVE + <para> + To create a new <link linkend="class-giosimpleasyncresult"><classname>gio.SimpleAsyncResult</classname></link>, + call g_simple_async_result_new(). If the result needs to be created for a GError, use g_simple_async_result_new_from_error(). + If a GError is not available (e.g. the asynchronous operation's doesn't take a GError argument), but the result still needs + to be created for an error condition, use g_simple_async_result_new_error() (or g_simple_async_result_set_error_va() + if your application or binding requires passing a variable argument list directly), and the error can then be propegated + through the use of g_simple_async_result_propagate_error(). + </para> + --> + <para> + An asynchronous operation can be made to ignore a cancellation event by calling + <methodname><link linkend="method-giosimpleasyncresult--set-handle-cancellation">gio.SimpleAsyncResult.set_handle_cancellation</link></methodname>() + with a + <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> + for the operation and <literal>False</literal>. This is useful for operations that are dangerous to cancel, + such as close (which would cause a leak if cancelled before being run). + </para> + <para> + <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> + can integrate into GLib's event loop, GMainLoop, or it can use GThreads if available. + <methodname><link linkend="method-giosimpleasyncresult--complete">gio.SimpleAsyncResult.complete</link></methodname>() + will finish an I/O task directly within the main event loop. + <methodname><link linkend="method-giosimpleasyncresult--complete-in-idle">gio.SimpleAsyncResult.complete_in_idle</link></methodname>() + will integrate the I/O task into the main event loop as an idle function. + <!-- + and g_simple_async_result_run_in_thread() + will run the job in a separate thread. + --> + </para> + <para> + To set the results of an asynchronous function, + <methodname><link linkend="method-giosimpleasyncresult--set-op-res-gboolean">gio.SimpleAsyncResult.set_op_res_gboolean</link></methodname>(), and + <methodname><link linkend="method-giosimpleasyncresult--set-op-res-gssize">gio.SimpleAsyncResult.set_op_res_gssize</link></methodname>() + are provided, setting the operation's result to a gboolean, or gssize, respectively. + </para> + <para> + Likewise, to get the result of an asynchronous function, + <methodname><link linkend="method-giosimpleasyncresult--get-op-res-gboolean">gio.SimpleAsyncResult.get_op_res_gboolean</link></methodname>() and + <methodname><link linkend="method-giosimpleasyncresult--get-op-res-gssize">gio.SimpleAsyncResult.get_op_res_gssize</link></methodname>() + are provided, getting the operation's result as a gboolean and gssize, respectively. + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giosimpleasyncresult--complete"> + <title>gio.SimpleAsyncResult.complete</title> + + <programlisting><methodsynopsis language="python"> + <methodname>complete</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + </variablelist> + + <para> + The <methodname>complete</methodname>() 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 + <methodname><link linkend="method-giosimpleasyncresult--complete-in-idle">gio.SimpleAsyncResult.complete_in_idle</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giosimpleasyncresult--complete-in-idle"> + <title>gio.SimpleAsyncResult.complete_in_idle</title> + + <programlisting><methodsynopsis language="python"> + <methodname>complete_in_idle</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + </variablelist> + + <para> + The <methodname>complete_in_idle</methodname>() method completes an asynchronous + function in the main event loop using an idle function. + </para> + </refsect2> + + <refsect2 id="method-giosimpleasyncresult--get-op-res-gboolean"> + <title>gio.SimpleAsyncResult.get_op_res_gboolean</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_op_res_gboolean</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the operation's result was + <literal>True</literal>, <literal>False</literal> if the operation's result + was <literal>False</literal>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_op_res_gboolean</methodname>() method gets the operation + result boolean from within the asynchronous result. + </para> + </refsect2> + + <refsect2 id="method-giosimpleasyncresult--get-op-res-gssize"> + <title>gio.SimpleAsyncResult.get_op_res_gssize</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_op_res_gssize</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a gssize returned from the asynchronous function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_op_res_gssize</methodname>() method gets a gssize + from the asynchronous result. + </para> + </refsect2> + + <refsect2 id="method-giosimpleasyncresult--propagate-error"> + <title>gio.SimpleAsyncResult.propagate_error</title> + + <programlisting><methodsynopsis language="python"> + <methodname>propagate_error</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the error was propegated + to dest. <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>propagate_error</methodname>() method propagates an error + from within the simple asynchronous result to a given destination. + </para> + </refsect2> + + <refsect2 id="method-giosimpleasyncresult--set-handle-cancellation"> + <title>gio.SimpleAsyncResult.set_handle_cancellation</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_handle_cancellation</methodname> + <methodparam><parameter role="keyword">handle_cancellation</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">handle_cancellation</parameter> :</term> + <listitem><simpara>a boolean. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_handle_cancellation</methodname>() method sets whether + to handle cancellation within the asynchronous operation. + </para> + </refsect2> + + <refsect2 id="method-giosimpleasyncresult--set-op-res-gboolean"> + <title>gio.SimpleAsyncResult.set_op_res_gboolean</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_op_res_gboolean</methodname> + <methodparam><parameter role="keyword">op_res</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">op_res</parameter> :</term> + <listitem><simpara>a boolean. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_op_res_gboolean</methodname>() method sets the operation + result to a boolean within the asynchronous result. + </para> + </refsect2> + + <refsect2 id="method-giosimpleasyncresult--set-op-res-gssize"> + <title>gio.SimpleAsyncResult.set_op_res_gssize</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_op_res_gssize</methodname> + <methodparam><parameter role="keyword">op_res</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">op_res</parameter> :</term> + <listitem><simpara>a gssize. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_op_res_gssize</methodname>() method sets the operation + result within the asynchronous result to the given op_res. + </para> + </refsect2> + </refsect1> +</refentry> |