GAsyncInitable

GAsyncInitable — Asynchronously failable object initialization interface

Functions

Types and Values

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
82
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);
  g_task_set_name (task, G_STRFUNC);

  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.

This method is intended for language bindings. If writing in C, g_async_initable_new_async() should typically be used 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.

Callers should not assume that a class which implements GAsyncInitable can be initialized multiple times; for more information, see g_initable_init(). If a class explicitly supports being initialized multiple times, implementation requires yielding all subsequent calls to init_async() on the results of the first call.

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.

[nullable]

...

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

g_async_initable_newv_async has been deprecated since version 2.54 and should not be used in newly-written code.

Use g_object_new_with_properties() and g_async_initable_init_async() instead. See GParameter for more information.

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

init_async ()

Starts initialization of the object.

 

init_finish ()

Finishes initialization of the object.

 

Since: 2.22

See Also

GInitable