gi-gio-2.0.38: Gio bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gio.Interfaces.AsyncInitable

Contents

- Exported types
- Methods
  - initAsync
  - initFinish
  - newFinish
  - newvAsync

Description

`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 `AsyncInitable`.`new_async`() directly, or indirectly via a `foo_thing_new_async()` wrapper. This will call `asyncInitableInitAsync` under the covers, calling back with `NULL` 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);
      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;
    }

Since: 2.22

Synopsis

- newtype AsyncInitable = AsyncInitable (ManagedPtr AsyncInitable)
- class (GObject o, IsDescendantOf AsyncInitable o) => IsAsyncInitable o
- toAsyncInitable :: (MonadIO m, IsAsyncInitable o) => o -> m AsyncInitable
- asyncInitableInitAsync :: (HasCallStack, MonadIO m, IsAsyncInitable a, IsCancellable b) => a -> Int32 -> Maybe b -> Maybe AsyncReadyCallback -> m ()
- asyncInitableInitFinish :: (HasCallStack, MonadIO m, IsAsyncInitable a, IsAsyncResult b) => a -> b -> m ()
- asyncInitableNewFinish :: (HasCallStack, MonadIO m, IsAsyncInitable a, IsAsyncResult b) => a -> b -> m Object
- asyncInitableNewvAsync :: (HasCallStack, MonadIO m, IsCancellable a) => GType -> Word32 -> Parameter -> Int32 -> Maybe a -> Maybe AsyncReadyCallback -> m ()

# Exported types

newtype AsyncInitable Source #

Memory-managed wrapper type.

Constructors

AsyncInitable (ManagedPtr AsyncInitable) |

#### Instances

Instances details

Eq AsyncInitable Source # |
Instance details Defined in GI.Gio.Interfaces.AsyncInitable Methods (==) :: AsyncInitable -> AsyncInitable -> Bool Source # (/=) :: AsyncInitable -> AsyncInitable -> Bool Source #
GObject AsyncInitable Source # |
Instance details Defined in GI.Gio.Interfaces.AsyncInitable
ManagedPtrNewtype AsyncInitable Source # |
Instance details Defined in GI.Gio.Interfaces.AsyncInitable Methods toManagedPtr :: AsyncInitable -> ManagedPtr AsyncInitable Source #
TypedObject AsyncInitable Source # |
Instance details Defined in GI.Gio.Interfaces.AsyncInitable Methods glibType :: IO GType Source #
HasParentTypes AsyncInitable Source # |
Instance details Defined in GI.Gio.Interfaces.AsyncInitable
IsGValue (Maybe AsyncInitable) Source # | Convert `AsyncInitable` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gio.Interfaces.AsyncInitable Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe AsyncInitable -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe AsyncInitable) Source #
type ParentTypes AsyncInitable Source # |
Instance details Defined in GI.Gio.Interfaces.AsyncInitable type ParentTypes AsyncInitable = '[Object]

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

Instances details

(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

### Click to display all available methods, including inherited ones

Expand

#### Methods

bindProperty, bindPropertyFull, forceFloating, freezeNotify, getv, initAsync, initFinish, isFloating, newFinish, notify, notifyByPspec, ref, refSink, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure.

#### Getters

getData, getProperty, getQdata.

#### Setters

setData, setDataFull, setProperty.

## initAsync

asyncInitableInitAsync Source #

Arguments

:: (HasCallStack, MonadIO m, IsAsyncInitable a, IsCancellable b) |
=> a | `initable`: a `AsyncInitable`.
-> Int32 | `ioPriority`: the I/O priority of the operation
-> Maybe b | `cancellable`: optional `Cancellable` object, `Nothing` to ignore.
-> Maybe AsyncReadyCallback | `callback`: a `AsyncReadyCallback` 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 `Initable` 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 `Initable`, 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 `AsyncInitable` 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 `Initable` 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 `AsyncInitable` interface without overriding any interface methods.

Since: 2.22

## initFinish

asyncInitableInitFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsAsyncInitable a, IsAsyncResult b) |
=> a | `initable`: a `AsyncInitable`.
-> b | `res`: a `AsyncResult`.
-> 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 `AsyncInitable` from the callback
-> b | `res`: the `AsyncResult` from the callback
-> m Object | Returns: a newly created `Object`, 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 `GType` supporting `AsyncInitable`.
-> Word32 | `nParameters`: the number of parameters in `parameters`
-> Parameter | `parameters`: the parameters to use to construct the object
-> Int32 | `ioPriority`: the I/O priority of the operation
-> Maybe a | `cancellable`: optional `Cancellable` object, `Nothing` to ignore.
-> Maybe AsyncReadyCallback | `callback`: a `AsyncReadyCallback` to call when the initialization is finished
-> m () |

Deprecated: (Since version 2.54)Use `g_object_new_with_properties()` and`asyncInitableInitAsync` instead. See `Parameter` for more information.

Helper function for constructing `AsyncInitable` 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