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

4 files changed, 328 insertions, 1 deletions

diff --git a/docs/Makefile.am b/docs/Makefile.am
index b974e67..adb7672 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 a5c7943..7ad8485 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 b6a3a7a..e49d65f 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 0000000..f6a0787
--- /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>&nbsp;:</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>&nbsp;:</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>&nbsp;:</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>&nbsp;:</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>&nbsp;:</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>&nbsp;:</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>