Module: Gio::AsyncInitable

Defined in:
(unknown)

Overview

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 GAsync::Initable 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 nil and a set %GError on failure.

A typical implementation might look something like this:

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

Instance Method Summary collapse

Instance Method Details

#init_async(initable, io_priority, cancellable, callback, user_data) ⇒ nil

Parameters:

  • initable (Gio::AsyncInitable)

    a GAsync::Initable.

  • io_priority (Integer)

    the [I/O priority] of the operation

  • cancellable (Gio::Cancellable)

    optional #GCancellable object, nil to ignore.

  • callback (Gio::AsyncReadyCallback)

    a GAsync::ReadyCallback to call when the request is satisfied

  • user_data (GObject)

    the data to pass to callback function

Returns:

  • (nil)

#init_finish(initable, res) ⇒ TrueClass

will return false and set error appropriately if present.

Parameters:

Returns:

  • (TrueClass)

    true if successful. If an error has occurred, this function

#new_finish(res) ⇒ GObject::Object

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

Parameters:

Returns:

  • (GObject::Object)

    a newly created #GObject, or nil on error. Free with g_object_unref().