gi-gio-2.0.25: Gio bindings

CopyrightWill Thompson Iñaki García Etxebarria and Jonas Platte
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria
Safe HaskellNone
LanguageHaskell2010

GI.Gio.Interfaces.AsyncInitable

Contents

Description

This is the asynchronous version of tInitable; it behaves the same in all ways except that initialization is asynchronous. For more details see the descriptions on tInitable.

A class may implement both the tInitable and tAsyncInitable 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 g_async_initable_new_async() directly, or indirectly via a foo_thing_new_async() wrapper. This will call asyncInitableInitAsync under the cover, calling back with Nothing and a set GError on failure.

A typical implementation might look something like this:

C code

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);

  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;
}

Since: 2.22

Synopsis

Exported types

newtype AsyncInitable Source #

Memory-managed wrapper type.

Constructors

AsyncInitable (ManagedPtr AsyncInitable) 
Instances
Eq AsyncInitable Source # 
Instance details

Defined in GI.Gio.Interfaces.AsyncInitable

GObject AsyncInitable Source # 
Instance details

Defined in GI.Gio.Interfaces.AsyncInitable

Methods

gobjectType :: IO GType

IsGValue AsyncInitable Source #

Convert AsyncInitable to and from GValue with toGValue and fromGValue.

Instance details

Defined in GI.Gio.Interfaces.AsyncInitable

Methods

toGValue :: AsyncInitable -> IO GValue

fromGValue :: GValue -> IO AsyncInitable

HasParentTypes AsyncInitable Source # 
Instance details

Defined in GI.Gio.Interfaces.AsyncInitable

type ParentTypes AsyncInitable Source # 
Instance details

Defined in GI.Gio.Interfaces.AsyncInitable

type ParentTypes AsyncInitable = Object ': ([] :: [Type])

noAsyncInitable :: Maybe AsyncInitable Source #

A convenience alias for Nothing :: Maybe AsyncInitable.

class (GObject o, IsDescendantOf AsyncInitable o) => IsAsyncInitable o Source #

Type class for types which can be safely cast to AsyncInitable, for instance with toAsyncInitable.

Instances
(GObject o, IsDescendantOf AsyncInitable o) => IsAsyncInitable o Source # 
Instance details

Defined in GI.Gio.Interfaces.AsyncInitable

toAsyncInitable :: (MonadIO m, IsAsyncInitable o) => o -> m AsyncInitable Source #

Cast to AsyncInitable, for types for which this is known to be safe. For general casts, use castTo.

Methods

Overloaded methods

initAsync

asyncInitableInitAsync Source #

Arguments

:: (HasCallStack, MonadIO m, IsAsyncInitable a, IsCancellable b) 
=> a

initable: a tAsyncInitable.

-> Int32

ioPriority: the [I/O priority][io-priority] of the operation

-> Maybe b

cancellable: optional tCancellable object, Nothing to ignore.

-> Maybe AsyncReadyCallback

callback: a tAsyncReadyCallback to call when the request is satisfied

-> m () 

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 tInitable you can optionally call initableInit 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 asyncInitableInitFinish to get the result of the initialization.

Implementations may also support cancellation. If cancellable is not Nothing, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error IOErrorEnumCancelled will be returned. If cancellable is not Nothing, and the object doesn't support cancellable initialization, the error IOErrorEnumNotSupported will be returned.

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

Since: 2.22

initFinish

asyncInitableInitFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsAsyncInitable a, IsAsyncResult b) 
=> a

initable: a tAsyncInitable.

-> b

res: a tAsyncResult.

-> m ()

(Can throw GError)

Finishes asynchronous initialization and returns the result. See asyncInitableInitAsync.

Since: 2.22

newFinish

asyncInitableNewFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsAsyncInitable a, IsAsyncResult b) 
=> a

initable: the tAsyncInitable from the callback

-> b

res: the tAsyncResult from the callback

-> m Object

Returns: a newly created tObject, or Nothing on error. Free with objectUnref. (Can throw GError)

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

Since: 2.22

newvAsync

asyncInitableNewvAsync Source #

Arguments

:: (HasCallStack, MonadIO m, IsCancellable a) 
=> GType

objectType: a tGType supporting tAsyncInitable.

-> Word32

nParameters: the number of parameters in parameters

-> Parameter

parameters: the parameters to use to construct the object

-> Int32

ioPriority: the [I/O priority][io-priority] of the operation

-> Maybe a

cancellable: optional tCancellable object, Nothing to ignore.

-> Maybe AsyncReadyCallback

callback: a tAsyncReadyCallback to call when the initialization is finished

-> m () 

Deprecated: (Since version 2.54)Use g_object_new_with_properties() andasyncInitableInitAsync instead. See tParameter for more information.

Helper function for constructing tAsyncInitable object. This is similar to objectNewv but also initializes the object asynchronously.

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

Since: 2.22