Gio.AsyncInitable¶

Implementations:: Gio.DBusConnection, Gio.DBusObjectManagerClient, Gio.DBusProxy

Methods¶

class	`newv_async` (object_type, n_parameters, parameters, io_priority, cancellable, callback, *user_data)
	`init_async` (io_priority, cancellable, callback, *user_data)
	`init_finish` (res)
	`new_finish` (res)

Virtual Methods¶

	`do_init_async` (io_priority, cancellable, callback, *user_data)
	`do_init_finish` (res)

Properties¶

None

Signals¶

None

Fields¶

None

Class Details¶

class Gio.AsyncInitable¶

Bases:: GObject.GInterface
Structure:: Gio.AsyncInitableIface

GAsyncInitable is an interface for asynchronously initializable objects.

This is the asynchronous version of [iface`Gio`.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 [func`Gio`.AsyncInitable.new_async] directly, or indirectly via a foo_thing_new_async() wrapper. This will call [method`Gio`.AsyncInitable.init_async] under the covers, calling back with NULL and a set GError on failure.

A typical implementation might look something like this:

```c enum { NOT_INITIALIZED, INITIALIZING, INITIALIZED };

static void _foo_ready_cb (Foo *self) { GLib.List *l;

self->priv->state = INITIALIZED;

for (l = self->priv->init_results; l != None; l = l->next) { Gio.Task *task = l->data;

if (self->priv->success) Gio.Task.return_boolean (task, True); else g_task_return_new_error (task, …); GObject.Object.unref (task); }

g_list_free (self->priv->init_results); self->priv->init_results = None; }

static void foo_init_async (Gio.AsyncInitable *initable, int io_priority, Gio.Cancellable *cancellable, Gio.AsyncReadyCallback callback, object user_data) { Foo *self = FOO (initable); Gio.Task *task;

task = Gio.Task.new (initable, cancellable, callback, user_data); Gio.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 Gio.Task.return_boolean (task, True); GObject.Object.unref (task); break; } }

static bool foo_init_finish (Gio.AsyncInitable *initable, Gio.AsyncResult *result, GLib.Error **error) { g_return_val_if_fail (Gio.Task.is_valid (result, initable), False);

return Gio.Task.propagate_boolean (G_TASK (result), error); }

static void foo_async_initable_iface_init (object g_iface, object data) { Gio.AsyncInitableIface *iface = g_iface;

iface->init_async = foo_init_async; iface->init_finish = foo_init_finish; } ```

New in version 2.22.

classmethod newv_async(object_type, n_parameters, parameters, io_priority, cancellable, callback, *user_data)[source]¶

Parameters:

object_type (GObject.GType) – a GObject.GType supporting Gio.AsyncInitable.
n_parameters (int) – the number of parameters in parameters
parameters (GObject.Parameter) – the parameters to use to construct the object
io_priority (int) – the I/O priority of the operation
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the initialization is finished
user_data (object or None) – the data to pass to callback function

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

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

New in version 2.22.

Deprecated since version 2.54: Use g_object_new_with_properties() and Gio.AsyncInitable.init_async() instead. See GObject.Parameter for more information.

init_async(io_priority, cancellable, callback, *user_data)[source]¶

Parameters:

io_priority (int) – the I/O priority of the operation
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is satisfied
user_data (object or None) – the data to pass to callback function

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 Gio.Initable you can optionally call Gio.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 Gio.AsyncInitable.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 Gio.IOErrorEnum.CANCELLED will be returned. If cancellable is not None, and the object doesn’t support cancellable initialization, the error Gio.IOErrorEnum.NOT_SUPPORTED will be returned.

As with Gio.Initable, if the object is not initialized, or initialization returns with an error, then all operations on the object except GObject.Object.ref() and GObject.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 Gio.AsyncInitable can be initialized multiple times; for more information, see Gio.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 Gio.Initable interface, the default implementation of this method will run the Gio.Initable.init() function in a thread, so if you want to support asynchronous initialization via threads, just implement the Gio.AsyncInitable interface without overriding any interface methods.

New in version 2.22.

init_finish(res)[source]¶

Parameters:: res (Gio.AsyncResult) – a Gio.AsyncResult.
Raises:: GLib.Error
Returns:: True if successful. If an error has occurred, this function will return False and set error appropriately if present.
Return type:: bool

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

New in version 2.22.

new_finish(res)[source]¶

Parameters:: res (Gio.AsyncResult) – the Gio.AsyncResult from the callback
Raises:: GLib.Error
Returns:: a newly created GObject.Object, or None on error. Free with GObject.Object.unref().
Return type:: GObject.Object

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

New in version 2.22.

do_init_async(io_priority, cancellable, callback, *user_data) virtual¶

Parameters:

io_priority (int) – the I/O priority of the operation
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.
callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the request is satisfied
user_data (object or None) – the data to pass to callback function

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 Gio.Initable you can optionally call Gio.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 Gio.AsyncInitable.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 Gio.IOErrorEnum.CANCELLED will be returned. If cancellable is not None, and the object doesn’t support cancellable initialization, the error Gio.IOErrorEnum.NOT_SUPPORTED will be returned.

As with Gio.Initable, if the object is not initialized, or initialization returns with an error, then all operations on the object except GObject.Object.ref() and GObject.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 Gio.AsyncInitable can be initialized multiple times; for more information, see Gio.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 Gio.Initable interface, the default implementation of this method will run the Gio.Initable.init() function in a thread, so if you want to support asynchronous initialization via threads, just implement the Gio.AsyncInitable interface without overriding any interface methods.

New in version 2.22.

do_init_finish(res) virtual¶

Parameters:: res (Gio.AsyncResult) – a Gio.AsyncResult.
Returns:: True if successful. If an error has occurred, this function will return False and set error appropriately if present.
Return type:: bool

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

New in version 2.22.