Create  Edit  FrontPage  Index  Search  Changes  History  RSS  Login

GLib::SimpleAsyncResult

class GLib::SimpleAsyncResult

Implements GLib::AsyncResult for simple cases. Most of the time, this will be all an application needs, and will be used transparently. Because of this, GLib::SimpleAsyncResult is used throughout GIO for handling asynchronous functions.

GLib::SimpleAsyncResult handles GLib::AsyncResult blocks, error reporting, operation cancellation and the final state of an operation, completely transparent to the application. Results can be returned as a pointer, for example, 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 GLib::AsyncResult’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.

GLib::SimpleAsyncResults? are tagged with the calling function to ensure that asynchronous functions and their finishing functions are used together correctly.

To create a new GLib::SimpleAsyncResult, call GLib::SimpleAsyncResult#new.

An asynchronous operation can be made to ignore a cancellation event by calling Glib::SimpleAsyncResult#set_handle_cancellation. This is useful for operations that are dangerous to cancel, such as close (which would cause a leak if cancelled before being run).

GLib::SimpleAsyncResult can integrate into GLib’s event loop, GLib::MainLoop, or it can use GLib::Threads? if available. Glib::SimpleAsyncResult#complete will finish an I/O task directly from the point where it is called. GLib::SimpleAsyncResult#complete_in_idle will finish it from an idle handler in the thread-default main context. GLib::SimpleAsyncResult#run_in_thread will run the job in a separate thread and then deliver the result to the thread-default main context.

To set the results of an asynchronous function, GLib::SimpleAsyncResult#set_op_res_gboolean and GLib::SimpleAsyncResult#set_op_res_gssize, setting the operation’s result to a gboolean or gssize, respectively.

Likewise, to get the result of an asynchronous function, GLib::SimpleAsyncResult#op_res_gboolean and GLib::SimpleAsyncResult#op_res_gssize are provided, getting the operation’s result as a gboolean or gssize, respectively.

For the details of the requirements implementations must respect, see GLib::AsyncResult.

Class Methods

GLib::SimpleAsyncResult.new(object){ |result| }
Creates a GLib::SimpleAsyncResult.

Instance Methods

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 GLib::SimpleAsyncResult#complete_in_idle.
  • Returns: self
complete_in_idle
Completes an asynchronous function in an idle handler in the thread-default main loop of the thread that this GLib::SimpleAsyncResult was initially created in.
  • Returns: self
handle_cancellation=(handle_cancellation)
Same as GLib::SimpleAsyncResult#set_handle_cancellation.
  • handle_cancellation: Whether or not to handle cancellation
  • Returns: handle_cancellation
op_res_gboolean
Gets the operation result boolean from within the asynchronous result.
  • Returns: true if the operation’s result was true, false if the operation’s result was false
op_res_gboolean=(op_res)
Same as GLib::SimpleAsyncResult#set_op_res_gboolean.
  • op_res: A Boolean
  • Returns op_res
op_res_gssize
Gets a Fixnum or Bignum from the asynchronous result.
  • Returns: A Fixnum or Bignum returned from the asynchronous function
op_res_gssize=(op_res)
Same as GLib::SimpleAsyncResult#set_op_res_gssize.
  • op_res: A Fixnum or Bignum
set_handle_cancellation(handle_cancellation)
Sets whether to handle cancellation within the asynchronous operation.
  • handle_cancellation: Whether or not to handle cancellation
  • Returns: self
set_op_res_gboolean(op_res)
Sets the operation result to a Boolean within the asynchronous result.
  • op_res: A Boolean
  • Returns: self
set_op_res_gssize(op_res)
Sets the operation result within the asynchronous result to the given op_res.
  • op_res: A Fixnum or Bignum
  • Returns: self
source_object
See GLib::AsyncResult#source_object.
source_tag
Gets the source tag for the GLib::SimpleAsyncResult. This is actually the block associated with the GLib::SimpleAsyncResult.
valid?(source, source_tag)

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

First, source is checked to ensure that it matches the source object of this GLib::SimpleAsyncResult. Second, source_tag is checked to ensure that it is either nil or equal to the block passed to to GLib::SimpleAsyncResult.new.

  • source: The GLib::Object passed to the “_finish” function
  • source_tag: The block Proc
  • Returns: true if all checks passed or false if any failed
Last modified:2010/12/27 21:59:23
Keyword(s):
References:[Ruby/GIO] [index-ruby-glib2] [GLib::AsyncResult] [GLib::SimpleAsyncResult] [index-ruby-gio2]