Class: Gio::SimpleAsyncResult

Inherits:
Object
  • Object
show all
Defined in:
(unknown)

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(source_object, callback, user_data, error) ⇒ Gio::SimpleAsyncResult

Creates a GSimple::AsyncResult from an error condition, and takes over the caller's ownership of error, so the caller does not need to free it anymore.

Parameters:

  • source_object (GObject::Object) —

    a #GObject, or nil

  • callback (Gio::AsyncReadyCallback) —

    a GAsync::ReadyCallback.

  • user_data (GObject) —

    user data passed to callback.

  • error (GLib::Error) —

    a #GError

Class Method Details

.is_valid(result, source, source_tag) ⇒ Boolean

Ensures that the data passed to the _finish function of an async operation is consistent. Three checks are performed.

First, result is checked to ensure that it is really a GSimple::AsyncResult. Second, source is checked to ensure that it matches the source object of result. Third, source_tag is checked to ensure that it is equal to the source_tag argument given to g_simple_async_result_new() (which, by convention, is a pointer to the _async function corresponding to the _finish function from which this function is called). (Alternatively, if either source_tag or result's source tag is nil, then the source tag check is skipped.)

Parameters:

  • result (Gio::AsyncResult) —

    the GAsync::Result passed to the _finish function.

  • source (GObject::Object) —

    the #GObject passed to the _finish function.

  • source_tag (GObject) —

    the asynchronous function.

Returns:

  • (Boolean) —

    #TRUE if all checks passed or #FALSE if any failed.

Instance Method Details

#check_cancellable=(check_cancellable) ⇒ nil

Sets a #GCancellable to check before dispatching results.

This function has one very specific purpose: the provided cancellable is checked at the time of g_simple_async_result_propagate_error() If it is cancelled, these functions will return an "Operation was cancelled" error (%G_IO_ERROR_CANCELLED).

Implementors of cancellable asynchronous functions should use this in order to provide a guarantee to their callers that cancelling an async operation will reliably result in an error being returned for that operation (even if a positive result for the operation has already been sent as an idle to the main context to be dispatched).

The checking described above is done regardless of any call to the unrelated g_simple_async_result_set_handle_cancellation() function.

Parameters:

  • check_cancellable (Gio::Cancellable) —

    a #GCancellable to check, or nil to unset

Returns:

  • (nil)

#complete ⇒ nil

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().

Calling this function takes a reference to simple for as long as is needed to complete the call.

Returns:

  • (nil)

#complete_in_idle ⇒ nil

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

Calling this function takes a reference to simple for as long as is needed to complete the call.

Returns:

  • (nil)

#from_error=(error) ⇒ nil

Sets the result from a #GError.

Parameters:

  • error (GLib::Error) —

    #GError.

Returns:

  • (nil)

#handle_cancellation=(handle_cancellation) ⇒ nil

Sets whether to handle cancellation within the asynchronous operation.

This function has nothing to do with g_simple_async_result_set_check_cancellable(). It only refers to the #GCancellable passed to g_simple_async_result_run_in_thread().

Parameters:

  • handle_cancellation (Boolean) —

    a #gboolean.

Returns:

  • (nil)

#op_res_gboolean ⇒ Boolean

Gets the operation result boolean from within the asynchronous result.

Returns:

  • (Boolean) —

    true if the operation's result was true, false if the operation's result was false.

#op_res_gboolean=(op_res) ⇒ nil

Sets the operation result to a boolean within the asynchronous result.

Parameters:

  • op_res (Boolean) —

    a #gboolean.

Returns:

  • (nil)

#op_res_gpointer ⇒ GObject

Gets a pointer result as returned by the asynchronous function.

Returns:

  • (GObject) —

    a pointer from the result.

#op_res_gssize ⇒ Gio::gssize

Gets a gssize from the asynchronous result.

Returns:

  • (Gio::gssize) —

    a gssize returned from the asynchronous function.

#op_res_gssize=(op_res) ⇒ nil

Sets the operation result within the asynchronous result to the given op_res.

Parameters:

  • op_res (Gio::gssize) —

    a #gssize.

Returns:

  • (nil)

#propagate_error ⇒ Boolean

Propagates an error from within the simple asynchronous result to a given destination.

If the #GCancellable given to a prior call to g_simple_async_result_set_check_cancellable() is cancelled then this function will return true with dest set appropriately.

Returns:

  • (Boolean) —

    true if the error was propagated to dest. false otherwise.

#run_in_thread(func, io_priority, cancellable) ⇒ nil

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.

Calling this function takes a reference to simple for as long as is needed to run the job and report its completion.

Parameters:

  • func (Gio::SimpleAsyncThreadFunc) —

    a GSimple::AsyncThreadFunc.

  • io_priority (Integer) —

    the io priority of the request.

  • cancellable (Gio::Cancellable) —

    optional #GCancellable object, nil to ignore.

Returns:

  • (nil)

#set_error(domain, code, format, array) ⇒ nil

Sets an error within the asynchronous result without a #GError.

Parameters:

  • domain (GLib::Quark) —

    a #GQuark (usually %G_IO_ERROR).

  • code (Integer) —

    an error code.

  • format (String) —

    a formatted error reporting string.

  • array (Array) —

    a list of variables to fill in format.

Returns:

  • (nil)

#set_error_va(domain, code, format, args) ⇒ nil

Sets an error within the asynchronous result without a #GError. Unless writing a binding, see g_simple_async_result_set_error().

Parameters:

  • domain (GLib::Quark) —

    a #GQuark (usually %G_IO_ERROR).

  • code (Integer) —

    an error code.

  • format (String) —

    a formatted error reporting string.

  • args (Gio::va_list) —

    va_list of arguments.

Returns:

  • (nil)

#set_op_res_gpointer(op_res, destroy_op_res) ⇒ nil

Sets the operation result within the asynchronous result to a pointer.

Parameters:

  • op_res (GObject) —

    a pointer result from an asynchronous function.

  • destroy_op_res (GLib::DestroyNotify) —

    a GDestroy::Notify function.

Returns:

  • (nil)

#source_tag ⇒ GObject

Gets the source tag for the GSimple::AsyncResult.

Returns:

  • (GObject) —

    a #gpointer to the source object for the GSimple::AsyncResult.

#take_error(error) ⇒ nil

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.

Parameters:

  • error (GLib::Error) —

    a #GError

Returns:

  • (nil)