Package org.gnome.gio

Interface AsyncInitable

All Superinterfaces:

Proxy

All Known Implementing Classes:

AsyncInitable.AsyncInitableImpl, DBusConnection, DBusObjectManagerClient, DBusProxy

@Generated("io.github.jwharm.JavaGI")
public interface AsyncInitable
extends Proxy

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 newAsync(org.gnome.glib.Type, int, org.gnome.gio.Cancellable, org.gnome.gio.AsyncReadyCallback, java.lang.String, java.lang.Object...) directly, or indirectly via a foo_thing_new_async() wrapper. This will call initAsync(int, org.gnome.gio.Cancellable, org.gnome.gio.AsyncReadyCallback) 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;
 }
 

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	AsyncInitable.AsyncInitableIface	Provides an interface for asynchronous initializing object such that initialization may fail.
static class	AsyncInitable.AsyncInitableImpl	The AsyncInitableImpl type represents a native instance of the AsyncInitable interface.

Method Summary

Modifier and Type	Method	Description
static Type	getType()	Get the GType of the AsyncInitable class
default void	initAsync(int ioPriority, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	Starts asynchronous initialization of the object implementing the interface.
default boolean	initFinish(AsyncResult res)	Finishes asynchronous initialization and returns the result.
static void	newAsync(Type objectType, int ioPriority, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback, @Nullable String firstPropertyName, Object... varargs)	Helper function for constructing GAsyncInitable object.
static void	newvAsync(Type objectType, int nParameters, Parameter parameters, int ioPriority, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	Deprecated. Use g_object_new_with_properties() and g_async_initable_init_async() instead.

Methods inherited from interface io.github.jwharm.javagi.base.Proxy

handle

Method Details

getType

static Type getType()

Get the GType of the AsyncInitable class

Returns:

the GType

newAsync

static void newAsync(Type objectType,
 int ioPriority,
 @Nullable
 @Nullable Cancellable cancellable,
 @Nullable
 @Nullable AsyncReadyCallback callback,
 @Nullable
 @Nullable String firstPropertyName,
 Object... varargs)

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:

objectType - a GType supporting GAsyncInitable.

ioPriority - the I/O priority of the operation

cancellable - optional GCancellable object, null to ignore.

callback - a GAsyncReadyCallback to call when the initialization is finished

firstPropertyName - the name of the first property, or null if no properties

varargs - the value of the first property, followed by other property value pairs, and ended by null.

newvAsync

@Deprecated
static void newvAsync(Type objectType,
 int nParameters,
 Parameter parameters,
 int ioPriority,
 @Nullable
 @Nullable Cancellable cancellable,
 @Nullable
 @Nullable AsyncReadyCallback callback)

Deprecated.

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:

objectType - a GType supporting GAsyncInitable.

nParameters - the number of parameters in parameters

parameters - the parameters to use to construct the object

ioPriority - the I/O priority of the operation

cancellable - optional GCancellable object, null to ignore.

callback - a GAsyncReadyCallback to call when the initialization is finished

initAsync

default void initAsync(int ioPriority,
 @Nullable
 @Nullable Cancellable cancellable,
 @Nullable
 @Nullable AsyncReadyCallback callback)

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 IOErrorEnum.CANCELLED will be returned. If cancellable is not null, and the object doesn't support cancellable initialization, the error IOErrorEnum.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:

ioPriority - the I/O priority of the operation

cancellable - optional GCancellable object, null to ignore.

callback - a GAsyncReadyCallback to call when the request is satisfied

initFinish

default boolean initFinish(AsyncResult res)
                    throws GErrorException

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

Parameters:

res - a GAsyncResult.

Returns:

true if successful. If an error has occurred, this function will return false and set error appropriately if present.

Throws:

GErrorException - see GError