Top |
Functions
void | g_async_initable_init_async () |
gboolean | g_async_initable_init_finish () |
void | g_async_initable_new_async () |
GObject * | g_async_initable_new_finish () |
void | g_async_initable_new_valist_async () |
void | g_async_initable_newv_async () |
Known Implementations
GAsyncInitable is implemented by GDBusConnection, GDBusObjectManagerClient and GDBusProxy.
Description
This is the asynchronous version of GInitable; 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 g_async_initable_new_async()
directly, or indirectly via a foo_thing_new_async()
wrapper. This will call
g_async_initable_init_async()
under the cover, calling back with NULL
and
a set GError
on failure.
A typical implementation might look something like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 |
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; } |
Functions
g_async_initable_init_async ()
void g_async_initable_init_async (GAsyncInitable *initable
,int io_priority
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
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
G_IO_ERROR_CANCELLED
will be returned. If cancellable
is not NULL
, and
the object doesn't support cancellable initialization, the error
G_IO_ERROR_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
initable |
||
io_priority |
the I/O priority of the operation |
|
cancellable |
optional GCancellable object, |
|
callback |
a GAsyncReadyCallback to call when the request is satisfied |
|
user_data |
the data to pass to callback function |
Since: 2.22
g_async_initable_init_finish ()
gboolean g_async_initable_init_finish (GAsyncInitable *initable
,GAsyncResult *res
,GError **error
);
Finishes asynchronous initialization and returns the result.
See g_async_initable_init_async()
.
Parameters
initable |
||
res |
a GAsyncResult. |
|
error |
a GError location to store the error occurring, or |
Returns
TRUE
if successful. If an error has occurred, this function
will return FALSE
and set error
appropriately if present.
Since: 2.22
g_async_initable_new_async ()
void g_async_initable_new_async (GType object_type
,int io_priority
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
,const gchar *first_property_name
,...
);
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
object_type |
a GType supporting GAsyncInitable. |
|
io_priority |
the I/O priority of the operation |
|
cancellable |
optional GCancellable object, |
|
callback |
a GAsyncReadyCallback to call when the initialization is finished |
|
user_data |
the data to pass to callback function |
|
first_property_name |
the name of the first property, or |
[nullable] |
... |
the value of the first property, followed by other property
value pairs, and ended by |
Since: 2.22
g_async_initable_new_finish ()
GObject * g_async_initable_new_finish (GAsyncInitable *initable
,GAsyncResult *res
,GError **error
);
Finishes the async construction for the various g_async_initable_new
calls, returning the created object or NULL
on error.
Parameters
initable |
the GAsyncInitable from the callback |
|
res |
the GAsyncResult from the callback |
|
error |
return location for errors, or |
Returns
a newly created GObject,
or NULL
on error. Free with g_object_unref()
.
[type GObject.Object][transfer full]
Since: 2.22
g_async_initable_new_valist_async ()
void g_async_initable_new_valist_async (GType object_type
,const gchar *first_property_name
,va_list var_args
,int io_priority
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Helper function for constructing GAsyncInitable object. This is
similar to g_object_new_valist()
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
object_type |
a GType supporting GAsyncInitable. |
|
first_property_name |
the name of the first property, followed by
the value, and other property value pairs, and ended by |
|
var_args |
The var args list generated from |
|
io_priority |
the I/O priority of the operation |
|
cancellable |
optional GCancellable object, |
|
callback |
a GAsyncReadyCallback to call when the initialization is finished |
|
user_data |
the data to pass to callback function |
Since: 2.22
g_async_initable_newv_async ()
void g_async_initable_newv_async (GType object_type
,guint n_parameters
,GParameter *parameters
,int io_priority
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
g_async_initable_newv_async
has been deprecated since version 2.54 and should not be used in newly-written code.
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
object_type |
a GType supporting GAsyncInitable. |
|
n_parameters |
the number of parameters in |
|
parameters |
the parameters to use to construct the object |
|
io_priority |
the I/O priority of the operation |
|
cancellable |
optional GCancellable object, |
|
callback |
a GAsyncReadyCallback to call when the initialization is finished |
|
user_data |
the data to pass to callback function |
Since: 2.22
Types and Values
GAsyncInitable
typedef struct _GAsyncInitable GAsyncInitable;
Interface for asynchronously initializable objects.
Since: 2.22
struct GAsyncInitableIface
struct GAsyncInitableIface { GTypeInterface g_iface; /* Virtual Table */ void (* init_async) (GAsyncInitable *initable, int io_priority, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); gboolean (* init_finish) (GAsyncInitable *initable, GAsyncResult *res, GError **error); };
Provides an interface for asynchronous initializing object such that initialization may fail.
Since: 2.22