GAsyncInitable

## GAsyncInitable GAsyncInitable — Asynchronously failable object initialization interface |

## Synopsis

    #include <gio/gio.h>

                        GAsyncInitable;
    struct              GAsyncInitableIface;
    void                g_async_initable_init_async         (GAsyncInitable *initable,
                                                             int io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            g_async_initable_init_finish        (GAsyncInitable *initable,
                                                             GAsyncResult *res,
                                                             GError **error);
    void                g_async_initable_new_async          (GType object_type,
                                                             int io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data,
                                                             const gchar *first_property_name,
                                                             ...);
    GObject *           g_async_initable_new_finish         (GAsyncInitable *initable,
                                                             GAsyncResult *res,
                                                             GError **error);
    void                g_async_initable_new_valist_async   (GType object_type,
                                                             const gchar *first_property_name,
                                                             va_list var_args,
                                                             int io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    void                g_async_initable_newv_async         (GType object_type,
                                                             guint n_parameters,
                                                             GParameter *parameters,
                                                             int io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

## Object Hierarchy

      GInterface
       +----GAsyncInitable

## Prerequisites

GAsyncInitable requires GObject.

## Known Implementations

GAsyncInitable is implemented by GDBusConnection, GDBusObjectManagerClient and GDBusProxy.

## Description

This is the asynchronous version of GInitable; it behaves the same in all ways except that initialization is asynchronous. For more details see the descriptions on GInitable.

A class may implement both the GInitable and GAsyncInitable interfaces.

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 `g_async_initable_new_async()` directly, or indirectly via a `foo_thing_new_async()` wrapper. This will call `g_async_initable_init_async()` under the cover, calling back with `NULL` and a set `GError` on failure.

A typical implementation might look something like this:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    enum {
       NOT_INITIALIZED,
       INITIALIZING,
       INITIALIZED
    };

    static void
    _foo_ready_cb (Foo *self)
    {
      GList *l;

      self->priv->state = INITIALIZED;

      for (l = self->priv->init_results; l != NULL; l = l->next)
        {
          GSimpleAsyncResult *simple = l->data;

          if (!self->priv->success)
            g_simple_async_result_set_error (simple, ...);

          g_simple_async_result_complete (simple);
          g_object_unref (simple);
        }

      g_list_free (self->priv->init_results);
      self->priv->init_results = NULL;
    }

    static void
    foo_init_async (GAsyncInitable       *initable,
                    int                   io_priority,
                    GCancellable         *cancellable,
                    GAsyncReadyCallback   callback,
                    gpointer              user_data)
    {
      Foo *self = FOO (initable);
      GSimpleAsyncResult *simple;

      simple = g_simple_async_result_new (G_OBJECT (initable)
                                          callback,
                                          user_data,
                                          foo_init_async);

      switch (self->priv->state)
        {
          case NOT_INITIALIZED:
            _foo_get_ready (self);
            self->priv->init_results = g_list_append (self->priv->init_results,
                                                      simple);
            self->priv->state = INITIALIZING;
            break;
          case INITIALIZING:
            self->priv->init_results = g_list_append (self->priv->init_results,
                                                      simple);
            break;
          case INITIALIZED:
            if (!self->priv->success)
              g_simple_async_result_set_error (simple, ...);

            g_simple_async_result_complete_in_idle (simple);
            g_object_unref (simple);
            break;
        }
    }

    static gboolean
    foo_init_finish (GAsyncInitable       *initable,
                     GAsyncResult         *result,
                     GError              **error)
    {
      g_return_val_if_fail (g_simple_async_result_is_valid (result,
          G_OBJECT (initable), foo_init_async), FALSE);

      if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (result),
              error))
        return FALSE;

      return TRUE;
    }

    static void
    foo_async_initable_iface_init (gpointer g_iface,
                                   gpointer data)
    {
      GAsyncInitableIface *iface = g_iface;

      iface->init_async = foo_init_async;
      iface->init_finish = foo_init_finish;
    }

## Details

### GAsyncInitable

    typedef struct _GAsyncInitable GAsyncInitable;

Interface for asynchronously initializable objects.

Since 2.22

### struct GAsyncInitableIface

    struct GAsyncInitableIface {
      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);
    };

Provides an interface for asynchronous initializing object such that initialization may fail.

GTypeInterface `g_iface`; | The parent interface.
`init_async` () | Starts initialization of the object.
`init_finish` () | Finishes initialization of the object.

Since 2.22

### g_async_initable_init_async ()

    void                g_async_initable_init_async         (GAsyncInitable *initable,
                                                             int io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

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 GInitable you can optionally call `g_initable_init()` instead.

When the initialization is finished, `callback` will be called. You can then call `g_async_initable_init_finish()` to get the result of the initialization.

Implementations may also support cancellation. If `cancellable` is not `NULL`, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be returned. If `cancellable` is not `NULL`, and the object doesn't support cancellable initialization, the error `G_IO_ERROR_NOT_SUPPORTED` will be returned.

If this function is not called, or returns with an error, then all operations on the object should fail, generally returning the error `G_IO_ERROR_NOT_INITIALIZED`.

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 it's safe to implement the singleton pattern in the GObject constructor function.

For classes that also support the GInitable interface, the default implementation of this method will run the `g_initable_init()` function in a thread, so if you want to support asynchronous initialization via threads, just implement the GAsyncInitable interface without overriding any interface methods.

`initable` : | a GAsyncInitable.
`io_priority` : | the I/O priority of the operation.
`cancellable` : | optional GCancellable object, `NULL` to ignore.
`callback` : | a GAsyncReadyCallback to call when the request is satisfied
`user_data` : | the data to pass to callback function

Since 2.22

### g_async_initable_init_finish ()

    gboolean            g_async_initable_init_finish        (GAsyncInitable *initable,
                                                             GAsyncResult *res,
                                                             GError **error);

Finishes asynchronous initialization and returns the result. See `g_async_initable_init_async()`.

`initable` : | a GAsyncInitable.
`res` : | a GAsyncResult.
`error` : | a GError location to store the error occurring, or `NULL` to ignore.
Returns : | `TRUE` if successful. If an error has occurred, this function will return `FALSE` and set `error` appropriately if present.

Since 2.22

### g_async_initable_new_async ()

    void                g_async_initable_new_async          (GType object_type,
                                                             int io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data,
                                                             const gchar *first_property_name,
                                                             ...);

Helper function for constructing GAsyncInitable object. This is similar to `g_object_new()` but also initializes the object asynchronously.

When the initialization is finished, `callback` will be called. You can then call `g_async_initable_new_finish()` to get the new object and check for any errors.

`object_type` : | a GType supporting GAsyncInitable.
`io_priority` : | the I/O priority of the operation.
`cancellable` : | optional GCancellable object, `NULL` to ignore.
`callback` : | a GAsyncReadyCallback to call when the initialization is finished
`user_data` : | the data to pass to callback function
`first_property_name` : | the name of the first property, or `NULL` if no properties
`...` : | the value of the first property, followed by other property value pairs, and ended by `NULL`.

Since 2.22

### g_async_initable_new_finish ()

    GObject *           g_async_initable_new_finish         (GAsyncInitable *initable,
                                                             GAsyncResult *res,
                                                             GError **error);

Finishes the async construction for the various g_async_initable_new calls, returning the created object or `NULL` on error.

`initable` : | the GAsyncInitable from the callback
`res` : | the GAsyncResult from the callback
`error` : | return location for errors, or `NULL` to ignore
Returns : | a newly created GObject, or `NULL` on error. Free with `g_object_unref()`. [transfer full]

Since 2.22

### g_async_initable_new_valist_async ()

    void                g_async_initable_new_valist_async   (GType object_type,
                                                             const gchar *first_property_name,
                                                             va_list var_args,
                                                             int io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Helper function for constructing GAsyncInitable object. This is similar to `g_object_new_valist()` but also initializes the object asynchronously.

When the initialization is finished, `callback` will be called. You can then call `g_async_initable_new_finish()` to get the new object and check for any errors.

`object_type` : | a GType supporting GAsyncInitable.
`first_property_name` : | the name of the first property, followed by the value, and other property value pairs, and ended by `NULL`.
`var_args` : | The var args list generated from `first_property_name`.
`io_priority` : | the I/O priority of the operation.
`cancellable` : | optional GCancellable object, `NULL` to ignore.
`callback` : | a GAsyncReadyCallback to call when the initialization is finished
`user_data` : | the data to pass to callback function

Since 2.22

### g_async_initable_newv_async ()

    void                g_async_initable_newv_async         (GType object_type,
                                                             guint n_parameters,
                                                             GParameter *parameters,
                                                             int io_priority,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Helper function for constructing GAsyncInitable object. This is similar to `g_object_newv()` but also initializes the object asynchronously.

When the initialization is finished, `callback` will be called. You can then call `g_async_initable_new_finish()` to get the new object and check for any errors.

`object_type` : | a GType supporting GAsyncInitable.
`n_parameters` : | the number of parameters in `parameters`
`parameters` : | the parameters to use to construct the object
`io_priority` : | the I/O priority of the operation.
`cancellable` : | optional GCancellable object, `NULL` to ignore.
`callback` : | a GAsyncReadyCallback to call when the initialization is finished
`user_data` : | the data to pass to callback function

Since 2.22

## See Also

GInitable