GAsyncInitable: GIO Reference Manual

## GAsyncInitable GAsyncInitable — Asynchronously failable object initialization interface |

## Functions

void | g_async_initable_init_async ()
gboolean | g_async_initable_init_finish ()
void | g_async_initable_new_async ()
GObject * | g_async_initable_new_finish ()
void | g_async_initable_new_valist_async ()
void | g_async_initable_newv_async ()

## Types and Values

| GAsyncInitable
struct | GAsyncInitableIface

## Object Hierarchy

        GInterface
        ╰── GAsyncInitable

## Prerequisites

GAsyncInitable requires GObject.

## Known Implementations

GAsyncInitable is implemented by GDBusConnection, GDBusObjectManagerClient and GDBusProxy.

## Includes

    #include <gio/gio.h>

## 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
    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)
        {
          GTask *task = l->data;

          if (self->priv->success)
            g_task_return_boolean (task, TRUE);
          else
            g_task_return_new_error (task, ...);
          g_object_unref (task);
        }

      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);
      GTask *task;

      task = g_task_new (initable, cancellable, callback, user_data);

      switch (self->priv->state)
        {
          case NOT_INITIALIZED:
            _foo_get_ready (self);
            self->priv->init_results = g_list_append (self->priv->init_results,
                                                      task);
            self->priv->state = INITIALIZING;
            break;
          case INITIALIZING:
            self->priv->init_results = g_list_append (self->priv->init_results,
                                                      task);
            break;
          case INITIALIZED:
            if (!self->priv->success)
              g_task_return_new_error (task, ...);
            else
              g_task_return_boolean (task, TRUE);
            g_object_unref (task);
            break;
        }
    }

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

      return g_task_propagate_boolean (G_TASK (result), error);
    }

    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;
    }

## Functions

### 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.

As with GInitable, if the object is not initialized, or initialization returns with an error, then all operations on the object except `g_object_ref()` and `g_object_unref()` are considered to be invalid, and have undefined behaviour. They will often fail with `g_critical()` or `g_warning()`, but this must not be relied on.

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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. | [allow-none]
... | 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.

#### Parameters

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()`.

[type GObject.Object][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.

#### Parameters

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.

#### Parameters

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

## Types and Values

### 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.

#### Members

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

Since: 2.22

## See Also

GInitable