:right-sidebar: True AsyncInitable =================================================================== .. currentmodule:: gi.repository.Gio .. versionadded:: 2.22 .. class:: AsyncInitable(*args, **kwargs) :no-contents-entry: Implementations: :class:`~gi.repository.Gio.DBusConnection`, :class:`~gi.repository.Gio.DBusObjectManagerClient`, :class:`~gi.repository.Gio.DBusProxy` ``GAsyncInitable`` is an interface for asynchronously initializable objects. This is the asynchronous version of :obj:`~gi.repository.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 :obj:`~gi.repository.Gio.AsyncInitable.new_async` directly, or indirectly via a foo_thing_new_async() wrapper. This will call :obj:`~gi.repository.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: .. code-block:: c :dedent: 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 ------- .. rst-class:: interim-class .. class:: AsyncInitable :no-index: .. method:: init_async(io_priority: int, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> 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 :obj:`~gi.repository.Gio.Initable` you can optionally call :func:`~gi.repository.Gio.Initable.init` instead. This method is intended for language bindings. If writing in C, :func:`~gi.repository.Gio.AsyncInitable.new_async` should typically be used instead. When the initialization is finished, ``callback`` will be called. You can then call :func:`~gi.repository.Gio.AsyncInitable.init_finish` to get the result of the initialization. Implementations may also support cancellation. If ``cancellable`` is not :const:`None`, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error :const:`~gi.repository.Gio.IOErrorEnum.CANCELLED` will be returned. If ``cancellable`` is not :const:`None`, and the object doesn't support cancellable initialization, the error :const:`~gi.repository.Gio.IOErrorEnum.NOT_SUPPORTED` will be returned. As with :obj:`~gi.repository.Gio.Initable`\, if the object is not initialized, or initialization returns with an error, then all operations on the object except :func:`~gi.repository.GObject.GObject.Object.ref` and :func:`~gi.repository.GObject.GObject.Object.unref` are considered to be invalid, and have undefined behaviour. They will often fail with :func:`~gi.repository.GLib.critical` or :func:`~gi.repository.GLib.warning`, but this must not be relied on. Callers should not assume that a class which implements :obj:`~gi.repository.Gio.AsyncInitable` can be initialized multiple times; for more information, see :func:`~gi.repository.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 :obj:`~gi.repository.Gio.Initable` interface, the default implementation of this method will run the :func:`~gi.repository.Gio.Initable.init` function in a thread, so if you want to support asynchronous initialization via threads, just implement the :obj:`~gi.repository.Gio.AsyncInitable` interface without overriding any interface methods. .. versionadded:: 2.22 :param io_priority: the `I/O priority `__ of the operation :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore. :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the request is satisfied :param user_data: the data to pass to callback function .. method:: init_finish(res: ~gi.repository.Gio.AsyncResult) -> bool Finishes asynchronous initialization and returns the result. See :func:`~gi.repository.Gio.AsyncInitable.init_async`. .. versionadded:: 2.22 :param res: a :obj:`~gi.repository.Gio.AsyncResult`\. .. method:: new_finish(res: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.GObject.Object Finishes the async construction for the various g_async_initable_new calls, returning the created object or :const:`None` on error. .. versionadded:: 2.22 :param res: the :obj:`~gi.repository.Gio.AsyncResult` from the callback .. classmethod:: newv_async(n_parameters: int, parameters: ~gi.repository.GObject.Parameter, io_priority: int, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Helper function for constructing :obj:`~gi.repository.Gio.AsyncInitable` object. This is similar to :func:`~gi.repository.GObject.GObject.Object.newv` but also initializes the object asynchronously. When the initialization is finished, ``callback`` will be called. You can then call :func:`~gi.repository.Gio.AsyncInitable.new_finish` to get the new object and check for any errors. .. versionadded:: 2.22 .. deprecated:: 2.54 Use :func:`~gi.repository.GObject.GObject.Object.new_with_properties` and :func:`~gi.repository.Gio.AsyncInitable.init_async` instead. See :obj:`~gi.repository.GObject.Parameter` for more information. :param n_parameters: the number of parameters in ``parameters`` :param parameters: the parameters to use to construct the object :param io_priority: the `I/O priority `__ of the operation :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore. :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the initialization is finished :param user_data: the data to pass to callback function Virtual Methods --------------- .. rst-class:: interim-class .. class:: AsyncInitable :no-index: .. method:: do_init_async(io_priority: int, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> 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 :obj:`~gi.repository.Gio.Initable` you can optionally call :func:`~gi.repository.Gio.Initable.init` instead. This method is intended for language bindings. If writing in C, :func:`~gi.repository.Gio.AsyncInitable.new_async` should typically be used instead. When the initialization is finished, ``callback`` will be called. You can then call :func:`~gi.repository.Gio.AsyncInitable.init_finish` to get the result of the initialization. Implementations may also support cancellation. If ``cancellable`` is not :const:`None`, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error :const:`~gi.repository.Gio.IOErrorEnum.CANCELLED` will be returned. If ``cancellable`` is not :const:`None`, and the object doesn't support cancellable initialization, the error :const:`~gi.repository.Gio.IOErrorEnum.NOT_SUPPORTED` will be returned. As with :obj:`~gi.repository.Gio.Initable`\, if the object is not initialized, or initialization returns with an error, then all operations on the object except :func:`~gi.repository.GObject.GObject.Object.ref` and :func:`~gi.repository.GObject.GObject.Object.unref` are considered to be invalid, and have undefined behaviour. They will often fail with :func:`~gi.repository.GLib.critical` or :func:`~gi.repository.GLib.warning`, but this must not be relied on. Callers should not assume that a class which implements :obj:`~gi.repository.Gio.AsyncInitable` can be initialized multiple times; for more information, see :func:`~gi.repository.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 :obj:`~gi.repository.Gio.Initable` interface, the default implementation of this method will run the :func:`~gi.repository.Gio.Initable.init` function in a thread, so if you want to support asynchronous initialization via threads, just implement the :obj:`~gi.repository.Gio.AsyncInitable` interface without overriding any interface methods. .. versionadded:: 2.22 :param io_priority: the `I/O priority `__ of the operation :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore. :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the request is satisfied :param user_data: the data to pass to callback function .. method:: do_init_finish(res: ~gi.repository.Gio.AsyncResult) -> bool Finishes asynchronous initialization and returns the result. See :func:`~gi.repository.Gio.AsyncInitable.init_async`. .. versionadded:: 2.22 :param res: a :obj:`~gi.repository.Gio.AsyncResult`\.