diff options
Diffstat (limited to 'docs/reference/pygio-simpleasyncresult.xml')
| -rw-r--r-- | docs/reference/pygio-simpleasyncresult.xml | 317 |
1 files changed, 317 insertions, 0 deletions
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> :</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> |