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 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 occuring, 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 GAsyncInitiable 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 :

a GError location to store the error occuring, 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 GAsyncInitiable 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 GAsyncInitiable 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