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 callinit()
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 callinit_finish()
to get the result of the initialization.Implementations may also support cancellation. If
cancellable
is notNone
, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned. Ifcancellable
is notNone
, and the object doesn’t support cancellable initialization, the errorNOT_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 exceptref()
andunref()
are considered to be invalid, and have undefined behaviour. They will often fail withcritical()
orwarning()
, 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, seeinit()
. 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 theinit()
function in a thread, so if you want to support asynchronous initialization via threads, just implement theAsyncInitable
interface without overriding any interface methods.Added in version 2.22.
- Parameters:
io_priority – the I/O priority of the operation
cancellable – optional
Cancellable
object,None
to ignore.callback – a
AsyncReadyCallback
to call when the request is satisfieduser_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 tonewv()
but also initializes the object asynchronously.When the initialization is finished,
callback
will be called. You can then callnew_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()
andinit_async()
instead. SeeParameter
for more information.- Parameters:
object_type – a
Type
supportingAsyncInitable
.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
Cancellable
object,None
to ignore.callback – a
AsyncReadyCallback
to call when the initialization is finisheduser_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
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 callinit()
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 callinit_finish()
to get the result of the initialization.Implementations may also support cancellation. If
cancellable
is notNone
, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the errorCANCELLED
will be returned. Ifcancellable
is notNone
, and the object doesn’t support cancellable initialization, the errorNOT_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 exceptref()
andunref()
are considered to be invalid, and have undefined behaviour. They will often fail withcritical()
orwarning()
, 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, seeinit()
. 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 theinit()
function in a thread, so if you want to support asynchronous initialization via threads, just implement theAsyncInitable
interface without overriding any interface methods.Added in version 2.22.
- Parameters:
io_priority –
the I/O priority of the operation
cancellable – optional
Cancellable
object,None
to ignore.callback – a
AsyncReadyCallback
to call when the request is satisfieduser_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
.