A declarative syntax for creating asynchronous methods.
Find yourself writing the same boilerplate for all your asynchronous methods? Get dry with asynchronize.
Just add to your Gemfile and
bundle or install globally with
gem install asynchronize
Create a class with asynchronized methods
require 'asynchronize' class Test include Asynchronize # Can be called before or after method definitions. I prefer it at the top of classes. asynchronize :my_test, :my_other_test def my_test return 'testing' end def my_other_test #do stuff here too end end
Now, to call those methods.
The method's return value can be accessed either with
Thread#value or through
the thread param
:return_value (make sure the thread is finished first!)
thread = Test.new.my_test puts thread.value # > testing puts thread[:return_value] # > testing
Or if called with a block, the method's return value will be passed as a
parameter. In this case, the original function's return value is still
Thread#value contains the value returned
from the block.
thread = Test.new.my_test do |return_value| return_value.length end puts thread.value # > 7 puts thread[:return_value] # > testing
As you can see, it's just a regular thread. Make sure you call either
Thread#join to ensure it completes before your process exits,
and to catch any exceptions that may have been thrown!
While working on another project, I found myself writing this way too often:
def method_name(args) Thread.new(args) do |targs| # Actual code. end end
It's extra typing, and adds an unneeded extra layer of nesting. I couldn't find an existing library that wasn't trying to add new layers of abstraction I didn't need; sometimes you just want a normal thread. Now, just call asynchronize to make any method asynchronous.
Beginning with version 1.0.0, this project will follow Semantic Versioning. Until then, the patch number (0.0.x) will be updated for any changes that do not affect the public interface. Versions that increment the minor number (0.x.0) will have at least one of the following. A new feature will be added, some feature will be deprecated, or some previously deprecated feature will be removed. Deprecated features will be removed on the very next version that increments the minor version number.
Doesn't metaprogramming hurt performance?
Not at all! What we're doing in this project actually works exactly like inheritance, so it won't be a problem.
So, how does it work?
include Asynchronize it creates an
asynchronize method on your
require 'asynchronize' class Test include Asynchronize end Test.methods - Object.methods # > [:asynchronize]
The first time you call this method with any arguments, it creates a new
module with the methods you define. It uses
Module#prepend to insert itself at the top of the
class's inheritance chain. This means that its methods are called before the class's own methods.
class Test asynchronize :my_test def my_test return 'testing' end end Test.constants # > [:Asynchronized] Test::Asynchronized.instance_methods # > [:my_test] Test.ancestors # > [Test::Asynchronized, Test, Asynchronize, Object, Kernel, BasicObject]
Where the implementation of Test::Asynchronized#my_test (and any other method) is like
return Thread.new(args, block) do |thread_args, thread_block| Thread.current[:return_value] = super(*thread_args) next thread_block.call(Thread.current[:return_value]) if thread_block Thread.current[:return_value] end
This implementation allows you to call asynchronize at the top of the class and then define the methods below. Since it changes how you interact with those method's return values, I thought it was important to allow this.
Why do I need another gem? My code's bloated enough as it is?
It's super tiny. Just a light wrapper around the existing language features. Seriously, it's just around forty lines of code. Actually, according to cloc there's almost four times as many lines in the tests as the source. You should read it. I'd love feedback!
Do you accept contributions?
- Fork it (https://github.com/kennycoc/asynchronize/fork)
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Add some feature')
- Push to the branch (git push origin my-new-feature)
- Create a new pull request.
bundle to install dependencies, and
rake to run the tests.
What's the difference between asynchronize and promises/async..await?
Those and other similar projects aim to create an entirely new abstraction to use for interacting with threads. This project aims to be a light convenience wrapper around the existing language features. Just define a regular method, then interact with its result like a regular thread.
What Ruby versions are supported?
Ruby 2.3 and up. Unfortunately, Ruby versions prior to 2.0 do not support
Module#prepend and are not supported. Ruby versions prior to 2.3 have a bug
preventing usage of
define_method. I'm unable to find a suitable
workaround for this issue. (
problems when a method inherits from the asynchronized class.)
Luckily, all major Ruby implementations support Ruby language version 2.3, so I don't see this as a huge problem. If anyone wants support for older versions, and knows how to work around this issue, feel free to submit a pull request.
We explicitly test against the following versions:
- Matz Ruby 2.6.0
- Matz Ruby 2.3.8
- JRuby 220.127.116.11 (ruby language version 2.5.x)
- Rubinius 3.100 (ruby language version 2.3.1)
Is it any good?
Does anyone like it?