AsyncInitable

Added in version 2.22.

class AsyncInitable(*args, **kwargs)

Implementations: DBusConnection, DBusObjectManagerClient, DBusProxy

GAsyncInitable is an interface for asynchronously initializable objects.

This is the asynchronous version of Initable; 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 new_async directly, or indirectly via a foo_thing_new_async() wrapper. This will call init_async under the covers, calling back with NULL 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);
  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;
}

Methods

class AsyncInitable

init_async(io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

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 Initable you can optionally call init() instead.

This method is intended for language bindings. If writing in C, new_async() should typically be used instead.

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

Implementations may also support cancellation. If cancellable is not None, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error CANCELLED will be returned. If cancellable is not None, and the object doesn’t support cancellable initialization, the error NOT_SUPPORTED will be returned.

As with Initable, if the object is not initialized, or initialization returns with an error, then all operations on the object except ref() and unref() are considered to be invalid, and have undefined behaviour. They will often fail with critical() or warning(), but this must not be relied on.

Callers should not assume that a class which implements AsyncInitable can be initialized multiple times; for more information, see 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 Initable interface, the default implementation of this method will run the init() function in a thread, so if you want to support asynchronous initialization via threads, just implement the AsyncInitable interface without overriding any interface methods.

Added in version 2.22.

Parameters:

io_priority – the [I/O priority][io-priority] of the operation
cancellable – optional Cancellable object, None to ignore.
callback – a AsyncReadyCallback to call when the request is satisfied
user_data – the data to pass to callback function

init_finish(res: AsyncResult) → bool

Finishes asynchronous initialization and returns the result. See init_async().

Added in version 2.22.

Parameters:: res – a AsyncResult.

new_finish(res: AsyncResult) → Object

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

Added in version 2.22.

Parameters:: res – the AsyncResult from the callback

newv_async(object_type: type, n_parameters: int, parameters: Parameter, io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

Helper function for constructing AsyncInitable object. This is similar to newv() but also initializes the object asynchronously.

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

Added in version 2.22.

Deprecated since version 2.54: Use new_with_properties() and init_async() instead. See Parameter for more information.

Parameters:

object_type – a Type supporting AsyncInitable.
n_parameters – the number of parameters in parameters
parameters – the parameters to use to construct the object
io_priority – the [I/O priority][io-priority] of the operation
cancellable – optional Cancellable object, None to ignore.
callback – a AsyncReadyCallback to call when the initialization is finished
user_data – the data to pass to callback function

Virtual Methods

class AsyncInitable

do_init_async(io_priority: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

This method is intended for language bindings. If writing in C, new_async() should typically be used instead.

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

Added in version 2.22.

Parameters:

io_priority – the [I/O priority][io-priority] of the operation
cancellable – optional Cancellable object, None to ignore.
callback – a AsyncReadyCallback to call when the request is satisfied
user_data – the data to pass to callback function

do_init_finish(res: AsyncResult) → bool

Finishes asynchronous initialization and returns the result. See init_async().

Added in version 2.22.

Parameters:: res – a AsyncResult.