<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="GAsyncInitable">
<refmeta>
<refentrytitle role="top_of_page" id="GAsyncInitable.top_of_page">GAsyncInitable</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GIO Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GAsyncInitable</refname>
<refpurpose>Asynchronously failable object initialization interface</refpurpose>
</refnamediv>

<refsynopsisdiv id="GAsyncInitable.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;gio/gio.h&gt;

                    <link linkend="GAsyncInitable-struct">GAsyncInitable</link>;
                    <link linkend="GAsyncInitableIface">GAsyncInitableIface</link>;
<link linkend="void">void</link>                <link linkend="g-async-initable-init-async">g_async_initable_init_async</link>         (<link linkend="GAsyncInitable">GAsyncInitable</link> *initable,
                                                         <link linkend="int">int</link> io_priority,
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
                                                         <link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
                                                         <link linkend="gpointer">gpointer</link> user_data);
<link linkend="gboolean">gboolean</link>            <link linkend="g-async-initable-init-finish">g_async_initable_init_finish</link>        (<link linkend="GAsyncInitable">GAsyncInitable</link> *initable,
                                                         <link linkend="GAsyncResult">GAsyncResult</link> *res,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="void">void</link>                <link linkend="g-async-initable-new-async">g_async_initable_new_async</link>          (<link linkend="GType">GType</link> object_type,
                                                         <link linkend="int">int</link> io_priority,
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
                                                         <link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
                                                         <link linkend="gpointer">gpointer</link> user_data,
                                                         const <link linkend="gchar">gchar</link> *first_property_name,
                                                         ...);
<link linkend="GObject">GObject</link> *           <link linkend="g-async-initable-new-finish">g_async_initable_new_finish</link>         (<link linkend="GAsyncInitable">GAsyncInitable</link> *initable,
                                                         <link linkend="GAsyncResult">GAsyncResult</link> *res,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="void">void</link>                <link linkend="g-async-initable-new-valist-async">g_async_initable_new_valist_async</link>   (<link linkend="GType">GType</link> object_type,
                                                         const <link linkend="gchar">gchar</link> *first_property_name,
                                                         <link linkend="va-list">va_list</link> var_args,
                                                         <link linkend="int">int</link> io_priority,
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
                                                         <link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
                                                         <link linkend="gpointer">gpointer</link> user_data);
<link linkend="void">void</link>                <link linkend="g-async-initable-newv-async">g_async_initable_newv_async</link>         (<link linkend="GType">GType</link> object_type,
                                                         <link linkend="guint">guint</link> n_parameters,
                                                         <link linkend="GParameter">GParameter</link> *parameters,
                                                         <link linkend="int">int</link> io_priority,
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
                                                         <link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
                                                         <link linkend="gpointer">gpointer</link> user_data);
</synopsis>
</refsynopsisdiv>

<refsect1 id="GAsyncInitable.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>
  <link linkend="GInterface">GInterface</link>
   +----GAsyncInitable
</synopsis>
</refsect1>

<refsect1 id="GAsyncInitable.prerequisites" role="prerequisites">
<title role="prerequisites.title">Prerequisites</title>
<para>
GAsyncInitable requires
 <link linkend="GObject">GObject</link>.</para>
</refsect1>







<refsect1 id="GAsyncInitable.description" role="desc">
<title role="desc.title">Description</title>
<para>
This is the asynchronous version of <link linkend="GInitable"><type>GInitable</type></link>, it behaves the same
in all ways except that initialization is asynchronous. For more details
see the descriptions on <link linkend="GInitable"><type>GInitable</type></link>.
</para>
<para>
A class may implement both the <link linkend="GInitable"><type>GInitable</type></link> and <link linkend="GAsyncInitable"><type>GAsyncInitable</type></link> interfaces.
</para>
<para>
Users of objects implementing this are not intended to use the interface
method directly, instead it will be used automatically in various ways.
For C applications you generally just call <link linkend="g-async-initable-new-async"><function>g_async_initable_new_async()</function></link>
directly, or indirectly via a <link linkend="foo-thing-new-async"><function>foo_thing_new_async()</function></link> wrapper. This will call
<link linkend="g-async-initable-init-async"><function>g_async_initable_init_async()</function></link> under the cover, calling back with <link linkend="NULL--CAPS"><literal>NULL</literal></link> and
a set <link linkend="GError"><literal>GError</literal></link> on failure.</para>
<para>
</para>
</refsect1>

<refsect1 id="GAsyncInitable.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GAsyncInitable-struct" role="struct">
<title>GAsyncInitable</title>
<indexterm zone="GAsyncInitable-struct" role="2.22"><primary sortas="AsyncInitable">GAsyncInitable</primary></indexterm><programlisting>typedef struct _GAsyncInitable GAsyncInitable;</programlisting>
<para>
Interface for asynchronously initializable objects.</para>
<para>
</para><para role="since">Since 2.22</para></refsect2>
<refsect2 id="GAsyncInitableIface" role="struct" condition="since:2.22">
<title>GAsyncInitableIface</title>
<indexterm zone="GAsyncInitableIface" role="2.22"><primary sortas="AsyncInitableIface">GAsyncInitableIface</primary></indexterm><programlisting>typedef struct {
  GTypeInterface g_iface;

  /* Virtual Table */

  void     (* init_async)  (GAsyncInitable      *initable,
			    int                  io_priority,
			    GCancellable        *cancellable,
			    GAsyncReadyCallback  callback,
			    gpointer             user_data);
  gboolean (* init_finish) (GAsyncInitable      *initable,
			    GAsyncResult        *res,
			    GError             **error);
} GAsyncInitableIface;
</programlisting>
<para>
Provides an interface for asynchronous initializing object such that
initialization may fail.</para>
<para>
</para><variablelist role="struct">
<varlistentry>
<term><link linkend="GTypeInterface">GTypeInterface</link>&#160;<structfield>g_iface</structfield>;</term>
<listitem><simpara> The parent interface.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>init_async</structfield>&#160;()</term>
<listitem><simpara> Starts initialization of the object.
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>init_finish</structfield>&#160;()</term>
<listitem><simpara> Finishes initialization of the object.
</simpara></listitem>
</varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-async-initable-init-async" role="function" condition="since:2.22">
<title>g_async_initable_init_async ()</title>
<indexterm zone="g-async-initable-init-async" role="2.22"><primary sortas="async_initable_init_async">g_async_initable_init_async</primary></indexterm><programlisting><link linkend="void">void</link>                g_async_initable_init_async         (<link linkend="GAsyncInitable">GAsyncInitable</link> *initable,
                                                         <link linkend="int">int</link> io_priority,
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
                                                         <link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Starts asynchronous initialization of the object implementing the
interface. This must be done before any real use of the object after
initial construction. If the object also implements <link linkend="GInitable"><type>GInitable</type></link> you can
optionally call <link linkend="g-initable-init"><function>g_initable_init()</function></link> instead.
</para>
<para>
When the initialization is finished, <parameter>callback</parameter> will be called. You can
then call <link linkend="g-async-initable-init-finish"><function>g_async_initable_init_finish()</function></link> to get the result of the
initialization.
</para>
<para>
Implementations may also support cancellation. If <parameter>cancellable</parameter> is not
<link linkend="NULL--CAPS"><literal>NULL</literal></link>, then initialization can be cancelled by triggering the cancellable
object from another thread. If the operation was cancelled, the error
<link linkend="G-IO-ERROR-CANCELLED--CAPS"><literal>G_IO_ERROR_CANCELLED</literal></link> will be returned. If <parameter>cancellable</parameter> is not <link linkend="NULL--CAPS"><literal>NULL</literal></link> and
the object doesn't support cancellable initialization the error
<link linkend="G-IO-ERROR-NOT-SUPPORTED--CAPS"><literal>G_IO_ERROR_NOT_SUPPORTED</literal></link> will be returned.
</para>
<para>
If this function is not called, or returns with an error then all
operations on the object should fail, generally returning the
error <link linkend="G-IO-ERROR-NOT-INITIALIZED--CAPS"><literal>G_IO_ERROR_NOT_INITIALIZED</literal></link>.
</para>
<para>
Implementations of this method must be idempotent, i.e. multiple calls
to this function with the same argument should return the same results.
Only the first call initializes the object, further calls return the result
of the first call. This is so that its safe to implement the singleton
pattern in the GObject constructor function.
</para>
<para>
For classes that also support the <link linkend="GInitable"><type>GInitable</type></link> interface the default
implementation of this method will run the <link linkend="g-initable-init"><function>g_initable_init()</function></link> function
in a thread, so if you want to support asynchronous initialization via
threads, just implement the <link linkend="GAsyncInitable"><type>GAsyncInitable</type></link> interface without overriding
any interface methods.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>initable</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncInitable"><type>GAsyncInitable</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>io_priority</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="io-priority">I/O priority</link>
    of the operation.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellable</parameter>&#160;:</term>
<listitem><simpara> optional <link linkend="GCancellable"><type>GCancellable</type></link> object, <link linkend="NULL--CAPS"><literal>NULL</literal></link> to ignore.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncReadyCallback"><type>GAsyncReadyCallback</type></link> to call when the request is satisfied
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> the data to pass to callback function
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-async-initable-init-finish" role="function" condition="since:2.22">
<title>g_async_initable_init_finish ()</title>
<indexterm zone="g-async-initable-init-finish" role="2.22"><primary sortas="async_initable_init_finish">g_async_initable_init_finish</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_async_initable_init_finish        (<link linkend="GAsyncInitable">GAsyncInitable</link> *initable,
                                                         <link linkend="GAsyncResult">GAsyncResult</link> *res,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Finishes asynchronous initialization and returns the result.
See <link linkend="g-async-initable-init-async"><function>g_async_initable_init_async()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>initable</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncInitable"><type>GAsyncInitable</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>res</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncResult"><type>GAsyncResult</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GError"><type>GError</type></link> location to store the error occuring, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to
ignore.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if successful. If an error has occurred, this function
will return <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> and set <parameter>error</parameter> appropriately if present.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-async-initable-new-async" role="function" condition="since:2.22">
<title>g_async_initable_new_async ()</title>
<indexterm zone="g-async-initable-new-async" role="2.22"><primary sortas="async_initable_new_async">g_async_initable_new_async</primary></indexterm><programlisting><link linkend="void">void</link>                g_async_initable_new_async          (<link linkend="GType">GType</link> object_type,
                                                         <link linkend="int">int</link> io_priority,
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
                                                         <link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
                                                         <link linkend="gpointer">gpointer</link> user_data,
                                                         const <link linkend="gchar">gchar</link> *first_property_name,
                                                         ...);</programlisting>
<para>
Helper function for constructing <link linkend="GAsyncInitiable"><type>GAsyncInitiable</type></link> object. This is
similar to <link linkend="g-object-new"><function>g_object_new()</function></link> but also initializes the object asyncronously.
</para>
<para>
When the initialization is finished, <parameter>callback</parameter> will be called. You can
then call <link linkend="g-async-initable-new-finish"><function>g_async_initable_new_finish()</function></link> to get new object and check for
any errors.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>object_type</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GType"><type>GType</type></link> supporting <link linkend="GAsyncInitable"><type>GAsyncInitable</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>io_priority</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="io-priority">I/O priority</link>
    of the operation.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellable</parameter>&#160;:</term>
<listitem><simpara> optional <link linkend="GCancellable"><type>GCancellable</type></link> object, <link linkend="NULL--CAPS"><literal>NULL</literal></link> to ignore.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncReadyCallback"><type>GAsyncReadyCallback</type></link> to call when the initialization is
    finished
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> the data to pass to callback function
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>first_property_name</parameter>&#160;:</term>
<listitem><simpara> the name of the first property, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if no
    properties
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>...</parameter>&#160;:</term>
<listitem><simpara>  the value if the first property, followed by and other property
   value pairs, and ended by <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-async-initable-new-finish" role="function" condition="since:2.22">
<title>g_async_initable_new_finish ()</title>
<indexterm zone="g-async-initable-new-finish" role="2.22"><primary sortas="async_initable_new_finish">g_async_initable_new_finish</primary></indexterm><programlisting><link linkend="GObject">GObject</link> *           g_async_initable_new_finish         (<link linkend="GAsyncInitable">GAsyncInitable</link> *initable,
                                                         <link linkend="GAsyncResult">GAsyncResult</link> *res,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
Finishes the async construction for the various g_async_initable_new calls,
returning the created object or <link linkend="NULL--CAPS"><literal>NULL</literal></link> on error.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>initable</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GAsyncInitable"><type>GAsyncInitable</type></link> from the callback
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>res</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GAsyncResult"><type>GAsyncResult</type></link>.from the callback
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GError"><type>GError</type></link> location to store the error occuring, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to
    ignore.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly created <link linkend="GObject"><type>GObject</type></link>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> on error. Free with
    <link linkend="g-object-unref"><function>g_object_unref()</function></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-async-initable-new-valist-async" role="function" condition="since:2.22">
<title>g_async_initable_new_valist_async ()</title>
<indexterm zone="g-async-initable-new-valist-async" role="2.22"><primary sortas="async_initable_new_valist_async">g_async_initable_new_valist_async</primary></indexterm><programlisting><link linkend="void">void</link>                g_async_initable_new_valist_async   (<link linkend="GType">GType</link> object_type,
                                                         const <link linkend="gchar">gchar</link> *first_property_name,
                                                         <link linkend="va-list">va_list</link> var_args,
                                                         <link linkend="int">int</link> io_priority,
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
                                                         <link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Helper function for constructing <link linkend="GAsyncInitiable"><type>GAsyncInitiable</type></link> object. This is
similar to <link linkend="g-object-new-valist"><function>g_object_new_valist()</function></link> but also initializes the object
asyncronously.
</para>
<para>
When the initialization is finished, <parameter>callback</parameter> will be called. You can
then call <link linkend="g-async-initable-new-finish"><function>g_async_initable_new_finish()</function></link> to get new object and check for
any errors.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>object_type</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GType"><type>GType</type></link> supporting <link linkend="GAsyncInitable"><type>GAsyncInitable</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>first_property_name</parameter>&#160;:</term>
<listitem><simpara> the name of the first property, followed by
the value, and other property value pairs, and ended by <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>var_args</parameter>&#160;:</term>
<listitem><simpara> The var args list generated from <parameter>first_property_name</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>io_priority</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="io-priority">I/O priority</link>
    of the operation.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellable</parameter>&#160;:</term>
<listitem><simpara> optional <link linkend="GCancellable"><type>GCancellable</type></link> object, <link linkend="NULL--CAPS"><literal>NULL</literal></link> to ignore.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncReadyCallback"><type>GAsyncReadyCallback</type></link> to call when the initialization is
    finished
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> the data to pass to callback function
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>
<refsect2 id="g-async-initable-newv-async" role="function" condition="since:2.22">
<title>g_async_initable_newv_async ()</title>
<indexterm zone="g-async-initable-newv-async" role="2.22"><primary sortas="async_initable_newv_async">g_async_initable_newv_async</primary></indexterm><programlisting><link linkend="void">void</link>                g_async_initable_newv_async         (<link linkend="GType">GType</link> object_type,
                                                         <link linkend="guint">guint</link> n_parameters,
                                                         <link linkend="GParameter">GParameter</link> *parameters,
                                                         <link linkend="int">int</link> io_priority,
                                                         <link linkend="GCancellable">GCancellable</link> *cancellable,
                                                         <link linkend="GAsyncReadyCallback">GAsyncReadyCallback</link> callback,
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Helper function for constructing <link linkend="GAsyncInitiable"><type>GAsyncInitiable</type></link> object. This is
similar to <link linkend="g-object-newv"><function>g_object_newv()</function></link> but also initializes the object asyncronously.
</para>
<para>
When the initialization is finished, <parameter>callback</parameter> will be called. You can
then call <link linkend="g-async-initable-new-finish"><function>g_async_initable_new_finish()</function></link> to get new object and check for
any errors.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>object_type</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GType"><type>GType</type></link> supporting <link linkend="GAsyncInitable"><type>GAsyncInitable</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>n_parameters</parameter>&#160;:</term>
<listitem><simpara> the number of parameters in <parameter>parameters</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>parameters</parameter>&#160;:</term>
<listitem><simpara> the parameters to use to construct the object
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>io_priority</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="io-priority">I/O priority</link>
    of the operation.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>cancellable</parameter>&#160;:</term>
<listitem><simpara> optional <link linkend="GCancellable"><type>GCancellable</type></link> object, <link linkend="NULL--CAPS"><literal>NULL</literal></link> to ignore.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>callback</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncReadyCallback"><type>GAsyncReadyCallback</type></link> to call when the initialization is
    finished
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> the data to pass to callback function
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.22</para></refsect2>

</refsect1>



<refsect1 id="GAsyncInitable.see-also">
<title>See Also</title>
#GInitable
</refsect1>

</refentry>
