async-proxy

= async-proxy

An Async proxy is a wrapper around a real object that intercepts method calls and runs them in an asynchronous way.

=Construction

Async proxies will be generally constructed calling .async on any object.

=Behaviour

Calling any method in async proxy creates a new thread in charge of running the actual computation and control is immediately returned to the callee.

When the actual result of the method call is needed, call +sync+ on the returned value and this will wait (if necessary) for the thread to finish and provide the real value.

Example:

async_recommendations = user.async.recommendations # computing the recommendations is really slow!

#do other stuff

print async_recommendations.sync

=Chaining

The result of a method call in an async proxy will itself be an async proxy. This allows for chained computations:

my_async_result = object.async.some_slow_method.and_another_one(with_an_argument).and_a_third_one

currency = user.async.country.currency

Each chained method is run as soon as the previous level result is available. Calling sync in any dependent value will automatically wait for all dependencies.

=Dependent computations

Sometimes you want to run some code on the returned value as soon as it is available. With async proxy you do that with:

• register_callback: run the code but do not care about the return value

  async_proxy.slow_method.register_callback{|return_value| puts return_value}

• when_ready: returns yet another async proxy that lets you recover the block's returned value

  squared = async_proxy.slow_method.when_ready{|return_value| return_value * return_value } .. squared.sync

=Automatic synchronization

Some method calls automatically trigger synchronization:

• to_s
• inspect
• each

This means that in most cases you can treat an async object exactly in the same way that the wrapped object. You generally don't need to make explicit +sync+ calls (although you can if you want to control the exact moment the object will be "realized")

=Soft timeouts Sometimes you are interested in a value only if it can be computed in a certain time.

async_result = async_proxy.slow_method .. result = async_result.sync(:soft_timeout => 0.30)

= Locking and thread safety

Async Proxy makes no attempt to guarantee thread safety. It can be considered as just syntactic sugar to automate the creations of threads, so if your code is not thread-safe or uses libraries that are not thread-safe mischief will happen.

== Note on Patches/Pull Requests

• Fork the project.
• Make your feature addition or bug fix.
• Add tests for it. This is important so I don't break it in a future version unintentionally.
• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
• Send me a pull request. Bonus points for topic branches.

== Copyright

Copyright (c) 2010 Angel Faus. See LICENSE for details.