Add gio.AsyncResult in docs.

2009-03-24  Gian Mario Tagliaretti  <gianmt@gnome.org>

	* docs/Makefile.am:
	* docs/reference/pygio-classes.xml:
	* docs/reference/pygio-asyncresult.xml: Add gio.AsyncResult in docs.


svn path=/trunk/; revision=1032

3 files changed, 124 insertions, 0 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index e65dea5..50a7724 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -2,6 +2,12 @@
 
 	* docs/Makefile.am:
 	* docs/reference/pygio-classes.xml:
+	* docs/reference/pygio-asyncresult.xml: Add gio.AsyncResult in docs.
+
+2009-03-24  Gian Mario Tagliaretti  <gianmt@gnome.org>
+
+	* docs/Makefile.am:
+	* docs/reference/pygio-classes.xml:
 	* docs/reference/pygio-appinfo.xml:
 	* docs/reference/pygio-constants.xml:
 	* docs/reference/pygio-fileattributeinfo.xml: Add gio.AppInfo and
diff --git a/docs/reference/pygio-asyncresult.xml b/docs/reference/pygio-asyncresult.xml
new file mode 100644
index 0000000..abe56ce
--- /dev/null
+++ b/docs/reference/pygio-asyncresult.xml
@@ -0,0 +1,117 @@
+<?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-gioasyncresult">
+    <refnamediv>
+        <refname>gio.AsyncResult</refname>
+        <refpurpose>Asynchronous Function Results.</refpurpose>
+    </refnamediv>
+
+    <refsect1>
+        <title>Synopsis</title>
+
+    <classsynopsis language="python">
+        <ooclass><classname>gio.AsyncResult</classname></ooclass>
+        <ooclass><classname><link linkend="class-gobjectginterface">gobject.GInterface</link></classname></ooclass>
+
+    <methodsynopsis language="python">
+        <methodname><link linkend="method-gioasyncresult--get-source-object">get_source_object</link></methodname>
+        <methodparam></methodparam>
+    </methodsynopsis>
+    
+    </classsynopsis>
+
+    </refsect1>
+
+    <refsect1>
+        <title>Ancestry</title>
+
+<synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link>
+  +-- <link linkend="class-gioasyncresult">gio.AsyncResult</link>
+</synopsis>
+
+    </refsect1>
+    
+    <refsect1>
+	<title>Prerequisites</title>
+        <para>
+            <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> is required by
+            <link linkend="class-gobject"><classname>gobject.GObject</classname></link>.
+        </para>
+    </refsect1>
+    
+    <refsect1>
+	<title>Known Implementation</title>
+        <para>
+            <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> is implemented by
+            <link linkend="class-giosimpleasyncresult"><classname>gio.SimpleAsyncResult</classname></link>.
+        </para>
+    </refsect1>
+
+    <refsect1>
+        <title>Description</title>
+
+        <para>
+            <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>
+            provides a base class for implementing asynchronous function results.
+        </para>
+        <para>
+            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 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 <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>
+            instance, and optionally, an error to grab any error conditions that may have occurred. 
+        </para>
+        <para>
+            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
+            <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link>
+            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. It is also allowed to take a reference to the
+            <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>
+            and call "_finish()" later. 
+        </para>
+        <para>
+            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 gio.ERROR_CANCELLED error. 
+        </para>
+        <para>
+            Some ascynchronous operations are implemented using synchronous calls. These are run in a
+            separate thread, if GThread has been initialized, but otherwise they are sent to the Main Event
+            Loop and processed in an idle function. So, if you truly need asynchronous operations, make
+            sure to initialize GThread.
+        </para>
+    </refsect1>
+
+    <refsect1>
+        <title>Methods</title>
+
+        <refsect2 id="method-gioasyncresult--get-source-object">
+            <title>gio.AsyncResult.get_source_object</title>
+
+            <programlisting><methodsynopsis language="python">
+                <methodname>get_source_object</methodname>
+                <methodparam></methodparam>
+            </methodsynopsis></programlisting>
+            
+            <variablelist>
+                <varlistentry>
+                    <term><emphasis>Returns</emphasis>&nbsp;:</term>
+                    <listitem><simpara>the source object for the res.                        
+                    </simpara></listitem>
+                </varlistentry>
+            </variablelist>
+    
+            <para>
+                The <methodname>get_source_object</methodname>() method gets the source object
+                from a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>
+            </para>
+        </refsect2>
+    </refsect1>
+</refentry>
diff --git a/docs/reference/pygio-classes.xml b/docs/reference/pygio-classes.xml
index b3ecda5..f401bf9 100644
--- a/docs/reference/pygio-classes.xml
+++ b/docs/reference/pygio-classes.xml
@@ -9,6 +9,7 @@
 <!-- GIO CLASSES -->
 <xi:include href="pygio-appinfo.xml"/>
 <xi:include href="pygio-applaunchcontext.xml"/>
+<xi:include href="pygio-asyncresult.xml"/>
 <xi:include href="pygio-cancellable.xml"/>
 <xi:include href="pygio-emblem.xml"/>
 <xi:include href="pygio-icon.xml"/>