Copyright | Will Thompson, Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com) |
Safe Haskell | None |
Language | Haskell2010 |
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 Initable
.
A class may implement both the Initable
and AsyncInitable
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; }
- newtype AsyncInitable = AsyncInitable (ManagedPtr AsyncInitable)
- noAsyncInitable :: Maybe AsyncInitable
- class GObject o => IsAsyncInitable o
- toAsyncInitable :: IsAsyncInitable o => o -> IO AsyncInitable
- data AsyncInitableInitAsyncMethodInfo
- asyncInitableInitAsync :: (HasCallStack, MonadIO m, IsAsyncInitable a, IsCancellable b) => a -> Int32 -> Maybe b -> Maybe AsyncReadyCallback -> m ()
- data AsyncInitableInitFinishMethodInfo
- asyncInitableInitFinish :: (HasCallStack, MonadIO m, IsAsyncInitable a, IsAsyncResult b) => a -> b -> m ()
- data AsyncInitableNewFinishMethodInfo
- 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 #
GObject AsyncInitable Source # | |
IsObject AsyncInitable Source # | |
IsAsyncInitable AsyncInitable Source # | |
((~) * info (ResolveAsyncInitableMethod t AsyncInitable), MethodInfo * info AsyncInitable p) => IsLabel t (AsyncInitable -> p) Source # | |
((~) * info (ResolveAsyncInitableMethod t AsyncInitable), MethodInfo * info AsyncInitable p) => IsLabelProxy t (AsyncInitable -> p) Source # | |
HasAttributeList * AsyncInitable Source # | |
type AttributeList AsyncInitable Source # | |
type SignalList AsyncInitable Source # | |
class GObject o => IsAsyncInitable o Source #
toAsyncInitable :: IsAsyncInitable o => o -> IO AsyncInitable Source #
Methods
initAsync
data AsyncInitableInitAsyncMethodInfo Source #
((~) * signature (Int32 -> Maybe b -> Maybe AsyncReadyCallback -> m ()), MonadIO m, IsAsyncInitable a, IsCancellable b) => MethodInfo * AsyncInitableInitAsyncMethodInfo a signature Source # | |
asyncInitableInitAsync Source #
:: (HasCallStack, MonadIO m, IsAsyncInitable a, IsCancellable b) | |
=> a |
|
-> Int32 |
|
-> Maybe b |
|
-> Maybe AsyncReadyCallback |
|
-> 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.
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.
Implementations of this method must be idempotent: i.e. multiple calls to this function with the same argument should return the same results. Only the first call initializes the object; further calls return the result of the first call. This is so that it's safe to implement the singleton pattern in the GObject constructor function.
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
data AsyncInitableInitFinishMethodInfo Source #
((~) * signature (b -> m ()), MonadIO m, IsAsyncInitable a, IsAsyncResult b) => MethodInfo * AsyncInitableInitFinishMethodInfo a signature Source # | |
asyncInitableInitFinish Source #
:: (HasCallStack, MonadIO m, IsAsyncInitable a, IsAsyncResult b) | |
=> a |
|
-> b |
|
-> m () | (Can throw |
Finishes asynchronous initialization and returns the result.
See asyncInitableInitAsync
.
Since: 2.22
newFinish
data AsyncInitableNewFinishMethodInfo Source #
((~) * signature (b -> m Object), MonadIO m, IsAsyncInitable a, IsAsyncResult b) => MethodInfo * AsyncInitableNewFinishMethodInfo a signature Source # | |
asyncInitableNewFinish Source #
:: (HasCallStack, MonadIO m, IsAsyncInitable a, IsAsyncResult b) | |
=> a |
|
-> b |
|
-> m Object | Returns: a newly created |
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 #
:: (HasCallStack, MonadIO m, IsCancellable a) | |
=> GType |
|
-> Word32 |
|
-> Parameter |
|
-> Int32 |
|
-> Maybe a |
|
-> Maybe AsyncReadyCallback |
|
-> m () |
Helper function for constructing AsyncInitable
object. This is
similar to objectNew
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