Gio.SimpleAsyncResult
Description: Reference for Gio.SimpleAsyncResult

### 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);
    }

#### Ancestors

- GObject

#### Implements

- GAsyncResult

#### Constructors

###### g_simple_async_result_new

Creates a `GSimpleAsyncResult`.

deprecated: 2.46

###### g_simple_async_result_new_error

Creates a new `GSimpleAsyncResult` with a set error.

deprecated: 2.46

###### 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 (see `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_from_error

Sets the result from a `GError`.

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 GObject (43)

Please see GObject for a full list of methods.

##### 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.

#### Class structure

    struct GioSimpleAsyncResultClass {
      /* no available fields */
    }

No description available.