Class
GioSimpleAsyncResult
Description [src]
final class Gio.SimpleAsyncResult : GObject.Object
implements Gio.AsyncResult {
/* No available fields */
}
As of GLib 2.46, GSimpleAsyncResult
is deprecated in favor of
GTask
, which provides a simpler API.
GSimpleAsyncResult
implements GAsyncResult
.
GSimpleAsyncResult
handles GAsyncReadyCallback
s, error
reporting, operation cancellation and the final state of an operation,
completely transparent to the application. Results can be returned
as a pointer e.g. for functions that return data that is collected
asynchronously, a boolean value for checking the success or failure
of an operation, or a gssize
for operations which return the number
of bytes modified by the operation; all of the simple return cases
are covered.
Most of the time, an application will not need to know of the details
of this API; it is handled transparently, and any necessary operations
are handled by GAsyncResult
’s interface. However, if implementing
a new GIO module, for writing language bindings, or for complex
applications that need better control of how asynchronous operations
are completed, it is important to understand this functionality.
GSimpleAsyncResult
s are tagged with the calling function to ensure
that asynchronous functions and their finishing functions are used
together correctly.
To create a new GSimpleAsyncResult
, call g_simple_async_result_new()
.
If the result needs to be created for a GError
, use
g_simple_async_result_new_from_error()
or
g_simple_async_result_new_take_error()
. If a GError
is not available
(e.g. the asynchronous operation doesn’t take a GError
argument),
but the result still needs to be created for an error condition, use
g_simple_async_result_new_error()
(or
g_simple_async_result_set_error_va()
if your application or binding
requires passing a variable argument list directly), and the error can then
be propagated through the use of
g_simple_async_result_propagate_error()
.
An asynchronous operation can be made to ignore a cancellation event by
calling g_simple_async_result_set_handle_cancellation()
with a
GSimpleAsyncResult
for the operation and FALSE
. This is useful for
operations that are dangerous to cancel, such as close (which would
cause a leak if cancelled before being run).
GSimpleAsyncResult
can integrate into GLib’s event loop,
GMainLoop
, or it can use GThread
s.
g_simple_async_result_complete()
will finish an I/O task directly
from the point where it is called.
g_simple_async_result_complete_in_idle()
will finish it from an idle
handler in the thread-default main context (see
g_main_context_push_thread_default()
) where the GSimpleAsyncResult
was created. g_simple_async_result_run_in_thread()
will run the job in
a separate thread and then use
g_simple_async_result_complete_in_idle()
to deliver the result.
To set the results of an asynchronous function,
g_simple_async_result_set_op_res_gpointer()
,
g_simple_async_result_set_op_res_gboolean()
, and
g_simple_async_result_set_op_res_gssize()
are provided, setting the operation’s result to a gpointer
, gboolean
, or
gssize
, respectively.
Likewise, to get the result of an asynchronous function,
g_simple_async_result_get_op_res_gpointer()
,
g_simple_async_result_get_op_res_gboolean()
, and
g_simple_async_result_get_op_res_gssize()
are
provided, getting the operation’s result as a gpointer
, gboolean
, and
gssize
, respectively.
For the details of the requirements implementations must respect, see
GAsyncResult
. A typical implementation of an asynchronous
operation using GSimpleAsyncResult
looks something like this:
static void
baked_cb (Cake *cake,
gpointer user_data)
{
// In this example, this callback is not given a reference to the cake,
// so the GSimpleAsyncResult has to take a reference to it.
GSimpleAsyncResult *result = user_data;
if (cake == NULL)
g_simple_async_result_set_error (result,
BAKER_ERRORS,
BAKER_ERROR_NO_FLOUR,
"Go to the supermarket");
else
g_simple_async_result_set_op_res_gpointer (result,
g_object_ref (cake),
g_object_unref);
// In this example, we assume that baked_cb is called as a callback from
// the mainloop, so it's safe to complete the operation synchronously here.
// If, however, _baker_prepare_cake () might call its callback without
// first returning to the mainloop — inadvisable, but some APIs do so —
// we would need to use g_simple_async_result_complete_in_idle().
g_simple_async_result_complete (result);
g_object_unref (result);
}
void
baker_bake_cake_async (Baker *self,
guint radius,
GAsyncReadyCallback callback,
gpointer user_data)
{
GSimpleAsyncResult *simple;
Cake *cake;
if (radius < 3)
{
g_simple_async_report_error_in_idle (G_OBJECT (self),
callback,
user_data,
BAKER_ERRORS,
BAKER_ERROR_TOO_SMALL,
"%ucm radius cakes are silly",
radius);
return;
}
simple = g_simple_async_result_new (G_OBJECT (self),
callback,
user_data,
baker_bake_cake_async);
cake = _baker_get_cached_cake (self, radius);
if (cake != NULL)
{
g_simple_async_result_set_op_res_gpointer (simple,
g_object_ref (cake),
g_object_unref);
g_simple_async_result_complete_in_idle (simple);
g_object_unref (simple);
// Drop the reference returned by _baker_get_cached_cake();
// the GSimpleAsyncResult has taken its own reference.
g_object_unref (cake);
return;
}
_baker_prepare_cake (self, radius, baked_cb, simple);
}
Cake *
baker_bake_cake_finish (Baker *self,
GAsyncResult *result,
GError **error)
{
GSimpleAsyncResult *simple;
Cake *cake;
g_return_val_if_fail (g_simple_async_result_is_valid (result,
G_OBJECT (self),
baker_bake_cake_async),
NULL);
simple = (GSimpleAsyncResult *) result;
if (g_simple_async_result_propagate_error (simple, error))
return NULL;
cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple));
return g_object_ref (cake);
}
Constructors
g_simple_async_result_new_from_error
Creates a GSimpleAsyncResult
from an error condition.
deprecated: 2.46
g_simple_async_result_new_take_error
Creates a GSimpleAsyncResult
from an error condition, and takes over the
caller’s ownership of error
, so the caller does not need to free it anymore.
deprecated: 2.46 since: 2.28
Functions
g_simple_async_result_is_valid
Ensures that the data passed to the _finish function of an async operation is consistent. Three checks are performed.
deprecated: 2.46 since: 2.20
Instance methods
g_simple_async_result_complete
Completes an asynchronous I/O job immediately. Must be called in the thread where the asynchronous result was to be delivered, as it invokes the callback directly. If you are in a different thread use g_simple_async_result_complete_in_idle().
deprecated: 2.46
g_simple_async_result_complete_in_idle
Completes an asynchronous function in an idle handler in the
[thread-default main context][g-main-context-push-thread-default]
of the thread that simple
was initially created in
(and re-pushes that context around the invocation of the callback).
deprecated: 2.46
g_simple_async_result_get_op_res_gboolean
Gets the operation result boolean from within the asynchronous result.
deprecated: 2.46
g_simple_async_result_get_op_res_gpointer
Gets a pointer result as returned by the asynchronous function.
deprecated: 2.46
g_simple_async_result_get_op_res_gssize
Gets a gssize from the asynchronous result.
deprecated: 2.46
g_simple_async_result_get_source_tag
Gets the source tag for the GSimpleAsyncResult
.
deprecated: 2.46.
g_simple_async_result_propagate_error
Propagates an error from within the simple asynchronous result to a given destination.
deprecated: 2.46
g_simple_async_result_run_in_thread
Runs the asynchronous job in a separate thread and then calls
g_simple_async_result_complete_in_idle()
on simple
to return
the result to the appropriate main loop.
deprecated: 2.46
g_simple_async_result_set_check_cancellable
Sets a GCancellable
to check before dispatching results.
deprecated: 2.46 since: 2.32
g_simple_async_result_set_error
Sets an error within the asynchronous result without a GError
.
deprecated: 2.46
g_simple_async_result_set_error_va
Sets an error within the asynchronous result without a GError
.
Unless writing a binding, see g_simple_async_result_set_error().
deprecated: 2.46
g_simple_async_result_set_handle_cancellation
Sets whether to handle cancellation within the asynchronous operation.
deprecated: 2.46
g_simple_async_result_set_op_res_gboolean
Sets the operation result to a boolean within the asynchronous result.
deprecated: 2.46
g_simple_async_result_set_op_res_gpointer
Sets the operation result within the asynchronous result to a pointer.
deprecated: 2.46
g_simple_async_result_set_op_res_gssize
Sets the operation result within the asynchronous result to
the given op_res
.
deprecated: 2.46
g_simple_async_result_take_error
Sets the result from error
, and takes over the caller’s ownership
of error
, so the caller does not need to free it any more.
deprecated: 2.46 since: 2.28
Methods inherited from GAsyncResult (4)
g_async_result_get_source_object
Gets the source object from a GAsyncResult
.
g_async_result_get_user_data
Gets the user data from a GAsyncResult
.
g_async_result_is_tagged
Checks if res
has the given source_tag
(generally a function
pointer indicating the function res
was created by).
since: 2.34
g_async_result_legacy_propagate_error
If res
is a GSimpleAsyncResult
, this is equivalent to
g_simple_async_result_propagate_error()
. Otherwise it returns
FALSE
.
since: 2.34
Signals
Signals inherited from GObject (1)
GObject::notify
The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.