async_methods 1.0.0

data/.gitignore

@@ -0,0 +1 @@
+pkg

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Brian Durand
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,35 @@
+== AsyncMethods
+
+For those times you application is bound on I/O...
+
+== Enter AsyncMethods.
+
+This plugin adds a virtual asynchronous version of every method on every class. Asynchronouse methods have the same name as the original method name but prefixed with "async_". An asynchronous method will invoke to original method in a new thread and immediately return a proxy object that looks and acts just like the result from calling the actual method. When this proxy object is accessed for the first time, it will only then wait for the thread executing the method to finish.
+
+If you add fragment caching to your views and the cache returns a value and bypasses your view code, the method will never be invoked. Thanks to the magic of Ruby the proxy object will even act like the class it is proxying in class to class and kind_of?
+
+A simple example:
+
+The normal way to do it:
+
+  def index
+    @record_1 = MyResource.load(:first, :conditions => {:name => params[:name_1]})
+    @record_2 = MyResource.load(:first, :conditions => {:name => params[:name_2]})
+    @record_3 = MyResource.load(:first, :conditions => {:name => params[:name_3]})
+  end
+
+If the calls to load the resource each takes an average of 0.1 seconds, loading all three will take 0.3 seconds. In a web application this can start adding up quickly, especially under a heavy load. However, by using asynchronous methods like this, all three calls will happen in parallel and they should all complete in 0.1 seconds.
+
+  def index
+    @record_1 = MyResource.async_load(:first, :conditions => {:name => params[:name_1]})
+    @record_2 = MyResource.async_load(:first, :conditions => {:name => params[:name_2]})
+    @record_3 = MyResource.async_load(:first, :conditions => {:name => params[:name_3]})
+  end
+
+== Be Careful
+
+Because underneath it all new threads are being spawned, you must be careful to make sure that the code you are calling is thread safe. For example, the default configuration for ActiveRecord is not thread safe so loading several calls from the database at once would cause you problems. This plugin was originally written to speed up parallel loads of ActiveResource records, so that should be safe to do.
+
+== Testing
+
+Since the proxy object looks and acts just like the real result object, all your view tests should still pass. Your controller tests should pass will little or no tweaking.

data/Rakefile

@@ -0,0 +1,46 @@
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+begin
+  require 'spec/rake/spectask'
+  desc 'Test the gem.'
+  Spec::Rake::SpecTask.new(:test) do |t|
+    t.spec_files = FileList.new('spec/**/*_spec.rb')
+  end
+rescue LoadError
+  tast :test do
+    STDERR.puts "You must have rspec >= 1.3.0 to run the tests"
+  end
+end
+
+desc 'Generate documentation for the gem.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.options << '--title' << 'Async Methods' << '--line-numbers' << '--inline-source' << '--main' << 'README.rdoc'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "async_methods"
+    gem.summary = %Q{Gem that adds asynchronous method calls for all methods on every object to aid in throughput on I/O bound processes.}
+    gem.description = %Q(Gem that adds asynchronous method calls for all methods on every object to aid in throughput on I/O bound processes. This is intended to improve throughput on I/O bound processes like making several HTTP calls in row.)
+    gem.email = "brian@embellishedvisions.com"
+    gem.homepage = "http://github.com/bdurand/acts_as_revisionable"
+    gem.authors = ["Brian Durand"]
+    gem.rdoc_options = ["--charset=UTF-8", "--main", "README.rdoc"]
+    
+    gem.add_development_dependency('rspec', '>= 1.3.0')
+    gem.add_development_dependency('jeweler')
+  end
+
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+end
+

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/async_methods.gemspec

@@ -0,0 +1,58 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{async_methods}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Brian Durand"]
+  s.date = %q{2010-06-22}
+  s.description = %q{Gem that adds asynchronous method calls for all methods on every object to aid in throughput on I/O bound processes. This is intended to improve throughput on I/O bound processes like making several HTTP calls in row.}
+  s.email = %q{brian@embellishedvisions.com}
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "MIT-LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "async_methods.gemspec",
+     "lib/async_methods.rb",
+     "lib/async_methods/async_methods.rb",
+     "spec/async_method_spec.rb",
+     "spec/method_tester.rb",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/bdurand/acts_as_revisionable}
+  s.rdoc_options = ["--charset=UTF-8", "--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Gem that adds asynchronous method calls for all methods on every object to aid in throughput on I/O bound processes.}
+  s.test_files = [
+    "spec/async_method_spec.rb",
+     "spec/method_tester.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 1.3.0"])
+      s.add_development_dependency(%q<jeweler>, [">= 0"])
+    else
+      s.add_dependency(%q<rspec>, [">= 1.3.0"])
+      s.add_dependency(%q<jeweler>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 1.3.0"])
+    s.add_dependency(%q<jeweler>, [">= 0"])
+  end
+end
+

data/lib/async_methods/async_methods.rb

@@ -0,0 +1,95 @@
+# Including this module will provide the asynchronous method handling for the class where any method can be
+# prefixed with async_ to continue execution without waiting for results. By default, the plugin includes
+# it in Object so it is universally available.
+module AsyncMethods
+  
+  module InstanceMethods
+    def self.included (base)
+      base.send :alias_method, :method_missing_without_async, :method_missing
+      base.send :alias_method, :method_missing, :method_missing_with_async
+    end
+    
+    # Override missing method to add the async method handling
+    def method_missing_with_async (method, *args, &block)
+      if method.to_s[0, 6] == 'async_'
+        method = method.to_s
+        return Proxy.new(self, method[6 , method.length].to_sym, args, &block)
+      else
+        # Keep track of the current missing method calls to keep out of an infinite loop
+        stack = Thread.current[:async_method_missing_methods] ||= []
+        sig = MethodSignature.new(self, method)
+        raise NoMethodError.new("undefined method `#{method}' for #{self}") if stack.include?(sig)
+        begin
+          stack.push(sig)
+          return method_missing_without_async(method, *args, &block)
+        ensure
+          stack.pop
+        end
+      end
+    end
+    
+    # Call a block asynchronously.
+    def asynchronous_block (&block)
+      Proxy.new(nil, nil, nil, &block)
+    end
+  end
+  
+  # This class is used to keep track of methods being called.
+  class MethodSignature
+    
+    attr_reader :object, :method
+    
+    def initialize (obj, method)
+      @object = obj
+      @method = method.to_sym
+    end
+    
+    def eql? (sig)
+      sig.kind_of(MethodSignature) and sig.object == @object and sig.method == @method
+    end
+    
+  end
+  
+  # The proxy object does all the heavy lifting.
+  class Proxy
+    # These methods we don't want to override. All other existing methods will be redefined.
+    PROTECTED_METHODS = %w(initialize __proxy_result__ __proxy_loaded__ method_missing)
+    
+    def initialize (obj, method, args = [], &block)
+      # Override already defined methods on Object to proxy them to the result object
+      methods.each do |m|
+        eval "def self.#{m} (*args, &block); __proxy_result__.send(:#{m}, *args, &block); end" unless PROTECTED_METHODS.include?(m)
+      end
+      
+      @thread = Thread.new do
+        begin
+          if obj and method
+            @proxy_result = obj.send(method, *args, &block)
+          else
+            @proxy_result = block.call
+          end
+        rescue Object => e
+          @proxy_exception = e
+        end
+      end
+    end
+    
+    # Get the result of the original method call. The original method will only be called once.
+    def __proxy_result__
+      @thread.join if @thread && @thread.alive?
+      @thread = nil
+      raise @proxy_exception if @proxy_exception
+      return @proxy_result
+    end
+    
+    def __proxy_loaded__
+      !(@thread && @thread.alive?)
+    end
+    
+    # All missing methods are proxied to the original result object.
+    def method_missing (method, *args, &block)
+      __proxy_result__.send(method, *args, &block)
+    end
+  end
+  
+end

data/lib/async_methods.rb

@@ -0,0 +1,2 @@
+require File.expand_path('../async_methods/async_methods', __FILE__)
+Object.send(:include, AsyncMethods::InstanceMethods) unless Object.include?(AsyncMethods::InstanceMethods)

data/spec/async_method_spec.rb

@@ -0,0 +1,102 @@
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'async_methods', 'async_methods'))
+Object.send(:include, AsyncMethods::InstanceMethods) unless Object.include?(AsyncMethods::InstanceMethods)
+require File.expand_path(File.dirname(__FILE__) + '/method_tester')
+
+context "AsyncMethods InstanceMethods" do
+  
+  let(:object) { AsyncMethods::Tester.new }
+  
+  specify "should inject async method handling" do
+    proxy = object.async_test("arg")
+    proxy.to_s.should == "ARG"
+    proxy.__proxy_loaded__.should == true
+  end
+  
+  specify "should return a proxy object that has not been invoked yet" do
+    proxy = object.async_test("arg", 1)
+    proxy.__proxy_loaded__.should == false
+  end
+  
+  specify "should be able to run a block asynchronously" do
+    proxy = asynchronous_block{object.test("arg", 0.1)}
+    proxy.__proxy_loaded__.should == false
+    proxy.to_s.should == "ARG"
+    proxy.__proxy_loaded__.should == true
+  end
+  
+end
+
+context "AsyncMethods Proxy" do
+  
+  let(:object) { AsyncMethods::Tester.new }
+  
+  specify "should be able to wrap a method without waiting for it to finish" do
+    proxy = object.async_test("arg", 1)
+    object.test_called.should == 0
+  end
+  
+  specify "should execute the wrapped method when it needs to" do
+    proxy = object.async_test("arg")
+    proxy.to_s
+    object.test_called.should == 1
+  end
+  
+  specify "should only execute the wrapped method once" do
+    proxy = object.async_test("arg")
+    proxy.to_s
+    proxy.to_s
+    object.test_called.should == 1
+  end
+  
+  specify "should allow nil as a valid proxied value" do
+    proxy = object.async_test(nil)
+    proxy.should_not
+    object.test_called.should == 1
+  end
+  
+  specify "should allow blocks in the async method" do
+    n = 1
+    proxy = object.async_test("arg", 0.1) do
+      n = 2
+    end
+    n.should == 1
+    proxy.to_s
+    n.should == 2
+  end
+  
+  specify "should be indistinguishable from the real object" do
+    proxy = object.async_test("arg")
+    proxy.class.should == String
+    proxy.kind_of?(String).should == true
+  end
+  
+  specify "should proxy core methods on Object" do
+    proxy = "xxx".async_to_s
+    proxy.should == "xxx"
+  end
+  
+  specify "should proxy missing methods" do
+    proxy = object.async_find_test
+    proxy.to_s.should == "FINDER"
+  end
+  
+  specify "should allow blocks in the async missing methods" do
+    n = 1
+    proxy = object.async_find_test do
+      n = 2
+    end
+    n.should == 2
+  end
+  
+  specify "should not interfere with the proxied object's method_missing" do
+    real = object.find_test
+    real.to_s.should == "FINDER"
+  end
+  
+  specify "should not interfere with real methods that begin with async_" do
+    object.async_real_method_called.should == false
+    object.async_real_method
+    object.async_real_method_called.should == true
+  end
+  
+end

data/spec/method_tester.rb

@@ -0,0 +1,32 @@
+# This class is used for testing the async_methods plugin functionality.
+
+class AsyncMethods::Tester
+  
+  attr_reader :test_called, :async_real_method_called
+  
+  def initialize
+    @test_called = 0
+    @async_real_method_called = false
+  end
+  
+  def test (arg, delay = 0)
+    sleep(delay) if delay > 0
+    @test_called += 1
+    yield if block_given?
+    arg.upcase if arg
+  end
+  
+  def async_real_method
+    @async_real_method_called = true
+  end
+  
+  def method_missing (method, *args, &block)
+    if method.to_s[0, 5] == 'find_'
+      yield if block_given?
+      "FINDER"
+    else
+      super
+    end
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,26 @@
+# This file is copied to ~/spec when you run 'ruby script/generate rspec'
+# from the project root directory.
+ENV["RAILS_ENV"] ||= "test"
+require File.expand_path(File.dirname(__FILE__) + "/../../../../config/environment")
+require 'spec/rails'
+
+Spec::Runner.configure do |config|
+  config.use_transactional_fixtures = true
+  config.use_instantiated_fixtures  = false
+  config.fixture_path = RAILS_ROOT + '/spec/fixtures'
+  config.before(:each, :behaviour_type => :controller) do
+    raise_controller_errors
+  end
+
+  # You can declare fixtures for each behaviour like this:
+  #   describe "...." do
+  #     fixtures :table_a, :table_b
+  #
+  # Alternatively, if you prefer to declare them only once, you can
+  # do so here, like so ...
+  #
+  #   config.global_fixtures = :table_a, :table_b
+  #
+  # If you declare global fixtures, be aware that they will be declared
+  # for all of your examples, even those that don't use them.
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification 
+name: async_methods
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Brian Durand
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-06-22 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 1
+        - 3
+        - 0
+        version: 1.3.0
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: jeweler
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: Gem that adds asynchronous method calls for all methods on every object to aid in throughput on I/O bound processes. This is intended to improve throughput on I/O bound processes like making several HTTP calls in row.
+email: brian@embellishedvisions.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- .gitignore
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- async_methods.gemspec
+- lib/async_methods.rb
+- lib/async_methods/async_methods.rb
+- spec/async_method_spec.rb
+- spec/method_tester.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/bdurand/acts_as_revisionable
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Gem that adds asynchronous method calls for all methods on every object to aid in throughput on I/O bound processes.
+test_files: 
+- spec/async_method_spec.rb
+- spec/method_tester.rb
+- spec/spec_helper.rb