pygobject r1032 - in trunk/docs: . reference

[gianmt svn gnome org]

Author: gianmt
Date: Tue Mar 24 22:17:04 2009
New Revision: 1032
URL: http://svn.gnome.org/viewvc/pygobject?rev=1032&view=rev

Log:
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.



Added:
   trunk/docs/reference/pygio-asyncresult.xml
Modified:
   trunk/docs/Makefile.am
   trunk/docs/reference/ChangeLog
   trunk/docs/reference/pygio-classes.xml

Modified: trunk/docs/Makefile.am
==============================================================================
--- trunk/docs/Makefile.am	(original)
+++ trunk/docs/Makefile.am	Tue Mar 24 22:17:04 2009
@@ -18,6 +18,7 @@
 	html/glib-class-reference.html		\
 	html/class-gioapplaunchcontext.html	\
 	html/class-gioappinfo.html		\
+	html/class-gioasyncresult.html		\
 	html/class-giocancellable.html		\
 	html/class-gioemblem.html		\
 	html/class-gioemblemedicon.html		\
@@ -54,6 +55,7 @@
 	reference/pygio-constants.xml		\
 	reference/pygio-applaunchcontext.xml 	\
 	reference/pygio-appinfo.xml 		\
+	reference/pygio-asyncresult.xml 	\
 	reference/pygio-emblem.xml		\
 	reference/pygio-emblemedicon.xml	\
 	reference/pygio-icon.xml		\

Added: trunk/docs/reference/pygio-asyncresult.xml
==============================================================================
--- (empty file)
+++ trunk/docs/reference/pygio-asyncresult.xml	Tue Mar 24 22:17:04 2009
@@ -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>

Modified: trunk/docs/reference/pygio-classes.xml
==============================================================================
--- trunk/docs/reference/pygio-classes.xml	(original)
+++ trunk/docs/reference/pygio-classes.xml	Tue Mar 24 22:17:04 2009
@@ -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"/>