Class
GioSimpleAsyncResult
Description
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 GAsyncReadyCallbacks
, 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.
GSimpleAsyncResults 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’s 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 GThreads
.
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][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.