await 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,8 @@
+source "http://rubygems.org"
+
+gem 'eventmachine'
+
+group :development do
+  gem 'bundler'
+  gem 'jeweler'
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Scott Tadman, The Working Group Inc.
+
+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.md

@@ -0,0 +1,107 @@
+# await
+
+This implements the await/defer pattern in Ruby using fibers within the
+EventMachine environment.
+
+In general terms, `await` is used to define a group of operations that must
+be completed before processing can continue, and `defer` is used to define
+these individual operations.
+
+This can be used to simplify otherwise complicated callback structures where
+a number of operations can be performed in parallel. Further complexity arises
+when some of these operations have optional steps.
+
+## Examples
+
+In order to execute properly, an `await` call must be created within a fiber
+that can yield. Since the root fiber cannot yield, a secondary fiber must be
+created.
+
+A very simple example shows how a number of timers can be set to simulate
+some long-running asynchronous operations:
+
+```ruby
+require 'await'
+require 'eventmachine'
+
+EventMachine.run do
+  Fiber.new do
+    include Await
+
+    now = Time.now
+    await do
+      EventMachine::Timer.new(5, &defer)
+      EventMachine::Timer.new(2, &defer)
+      EventMachine::Timer.new(3, &defer)
+    end
+
+    puts "Took %.1fs to complete" % (Time.now - now).to_f
+
+    EventMachine.stop_event_loop
+  end.resume
+end
+```
+
+In the end you should see that it took only as long as the longest timer.
+
+In its default state, `defer` is simply used as a trigger. It can also wrap
+around a callback block to add additional functionality:
+
+```ruby
+require 'await'
+require 'eventmachine'
+
+EventMachine.run do
+  Fiber.new do
+    include Await
+    
+    now = Time.now
+    await do
+      trigger = defer do |x, y|
+        puts "Received arguments: #{[ x, y ].inspect}"
+      end
+      
+      EventMachine::Timer.new(4) do
+        trigger.call(1, '2')
+      end
+      
+      EventMachine::Timer.new(
+        3,
+        &defer do
+          EventMachine::Timer.new(
+            2,
+            &defer
+          )
+        end
+      )
+    end
+
+    puts "Took %.1fs to complete" % (Time.now - now).to_f
+
+    EventMachine.stop_event_loop
+  end.resume
+end
+```
+
+Since the `defer` method returns a standard Proc callback, it is possible to
+pass it through as a callback method or to trigger it at an arbitrary time
+with `call`.
+
+More examples of callback structures are available in the various unit tests.
+
+## Troubleshooting
+
+If the secondary fiber has not been created you will see errors like:
+
+    FiberError: can't yield from root fiber
+
+Keep in mind that unless a `defer` call is made within a callback then the
+operation is considered completed. If an additional asynchronous operation
+must be performed before it is complete, be sure to wrap any and all of these
+calls with `defer` as well to tag and track them properly.
+
+## Copyright
+
+Copyright (c) 2012 Scott Tadman, The Working Group Inc.
+See LICENSE.txt for further details.
+

data/Rakefile

@@ -0,0 +1,35 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require 'rake'
+require 'jeweler'
+
+Jeweler::Tasks.new do |gem|
+  gem.name = "await"
+  gem.homepage = "http://github.com/twg/await"
+  gem.license = "MIT"
+  gem.summary = %Q{Asynchronous await/defer methods for organizing callbacks}
+  gem.description = %Q{Implements the await/defer pattern for event-driven or asynchronous Ruby}
+  gem.email = "scott@twg.ca"
+  gem.authors = [ "Scott Tadman" ]
+end
+
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/await.gemspec

@@ -0,0 +1,55 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "await"
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Scott Tadman"]
+  s.date = "2012-11-13"
+  s.description = "Implements the await/defer pattern for event-driven or asynchronous Ruby"
+  s.email = "scott@twg.ca"
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "await.gemspec",
+    "lib/await.rb",
+    "test/helper.rb",
+    "test/test_await.rb"
+  ]
+  s.homepage = "http://github.com/twg/await"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.24"
+  s.summary = "Asynchronous await/defer methods for organizing callbacks"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<eventmachine>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, [">= 0"])
+    else
+      s.add_dependency(%q<eventmachine>, [">= 0"])
+      s.add_dependency(%q<bundler>, [">= 0"])
+      s.add_dependency(%q<jeweler>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<eventmachine>, [">= 0"])
+    s.add_dependency(%q<bundler>, [">= 0"])
+    s.add_dependency(%q<jeweler>, [">= 0"])
+  end
+end
+

data/lib/await.rb

@@ -0,0 +1,94 @@
+require 'thread'
+require 'fiber'
+
+module Await
+  module ThreadExtension
+    def await
+      # Capture the current context to properly chain this await in
+      parent = @deferred
+      
+      deferred = @deferred = {
+        :fiber => Fiber.current
+      }
+
+      if (parent)
+        parent[deferred] = true
+      end
+
+      yield if (block_given?)
+      
+      # So long as there is at least one outstanding defer block, this fiber
+      # must continue to yield.
+      while (deferred.size > 1)
+        fiber, trigger, block, args = Fiber.yield
+        
+        deferred.delete(trigger)
+
+        if (block)
+          # Always introduce the correct context here by setting the
+          # thread-local @deferred instance variable.
+          @deferred = deferred
+          block.call(*args)
+        end
+      end
+      
+      # If this was part of an existing await call then remove the current
+      # await operation from the list of pending entries.
+      if (parent)
+        if (deferred[:fiber] == Fiber.current)
+          parent.delete(deferred)
+        else
+          parent[:fiber].transfer([ Fiber.current, deferred ])
+        end
+      end
+
+      true
+    end
+    
+    def defer(&block)
+      deferred = @deferred
+      
+      trigger = lambda do |*args|
+        if (deferred[:fiber] == Fiber.current)
+          # Within the same fiber, remove this from the pending list
+          deferred.delete(trigger)
+
+          block.call(*args)
+        else
+          # If this is executing in a different fiber, transfer control back
+          # to the original fiber for reasons of continuity.
+          deferred[:fiber].transfer([ Fiber.current, trigger, block, args ])
+        end
+      end
+      
+      deferred[trigger] = true
+      
+      trigger
+    end
+  end
+
+  # Define a group of operations that need to be completed before execution
+  # will continue. The current fiber is suspended until all of the defer
+  # operations have completed.
+  def await(&block)
+    Thread.current.await(&block)
+  end
+
+  # Used to define a deferred operation. The return value is a Proc that can
+  # be passed through as a callback argument to any method. Once the callback
+  # has been executed it is considered complete unless within that callback
+  # other defer or await calls are made.
+  def defer(*args, &block)
+    Thread.current.defer(*args, &block)
+  end
+  
+  # Import all mixin methods here as module methods so they can be used
+  # directly without requiring an import.
+  extend self
+end
+
+# == Hook Installation ======================================================
+
+class Thread
+  include Await::ThreadExtension
+end

data/test/helper.rb

@@ -0,0 +1,31 @@
+require 'rubygems'
+require 'bundler'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require 'test/unit'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+require 'await'
+
+require 'eventmachine'
+
+class Test::Unit::TestCase
+  def em
+    EventMachine.run do
+      Fiber.new do
+        yield
+      end.resume
+      
+      EventMachine.stop_event_loop
+    end
+  end
+end

data/test/test_await.rb

@@ -0,0 +1,259 @@
+require File.expand_path('helper', File.dirname(__FILE__))
+
+class TestAwait < Test::Unit::TestCase
+  include Await
+  
+  def test_module
+    assert_equal true, Await.respond_to?(:await)
+    assert_equal true, Await.respond_to?(:defer)
+  end
+  
+  def test_await_default_state
+    triggered = false
+
+    em do
+      await do
+        triggered = true
+      end
+    end
+
+    assert_equal true, triggered
+  end
+  
+  def test_await_block_object
+    trigger = nil
+    exited = false
+    
+    em do
+      await do
+        trigger = defer
+      end
+    
+      exited = true
+    end
+    
+    assert_equal false, exited
+
+    trigger.call
+
+    assert_equal true, exited
+  end
+  
+  def test_await_single_defer
+    triggered = false
+
+    em do
+      await do
+        defer do
+          triggered = true
+        end.call
+      end
+    end
+
+    assert_equal true, triggered
+  end
+
+  def test_await_nested
+    triggered = 0
+
+    em do
+      await do
+        defer do
+          await do
+            defer do
+              triggered += 1
+            end.call
+          end
+
+          assert_equal 1, triggered
+
+          await do
+            defer do
+              triggered += 2
+            end.call
+          end
+        end.call
+      end
+
+      assert_equal 3, triggered
+    end
+
+    assert_equal 3, triggered
+  end
+
+  def test_await_delayed_defer
+    triggered = false
+    defer_block = nil
+
+    em do
+      await do
+        defer_block = defer do
+          triggered = true
+        end
+      end
+    end
+    
+    assert defer_block
+    assert_equal false, triggered
+
+    assert defer_block
+    defer_block.call
+    
+    assert_equal true, triggered
+  end
+
+  def test_await_delayed_double_defer
+    outer_trigger = nil
+    inner_trigger = nil
+    triggered = false
+    continued = false
+    
+    em do
+      await do
+        outer_trigger = defer do
+          inner_trigger = defer do
+            triggered = true
+          end
+        end
+      end
+      
+      continued = true
+    end
+
+    assert_equal false, triggered
+    assert_equal false, continued
+
+    assert !inner_trigger
+
+    outer_trigger.call
+    
+    assert_equal false, triggered
+    assert_equal false, continued
+
+    assert inner_trigger
+    
+    inner_trigger.call
+    
+    assert_equal true, triggered
+    assert_equal true, continued
+  end
+
+  def test_await_nested_delayed_trigger
+    outer_trigger = nil
+    inner_trigger = nil
+    triggered = false
+    continued = false
+    
+    em do
+      await do
+        outer_trigger = defer do
+          await do
+            inner_trigger = defer do
+              triggered = true
+            end
+          end
+        end
+      end
+      
+      continued = true
+    end
+
+    assert_equal false, triggered
+    assert_equal false, continued
+
+    assert !inner_trigger
+
+    outer_trigger.call
+    
+    assert_equal false, triggered
+    assert_equal false, continued
+
+    assert inner_trigger
+    
+    inner_trigger.call
+    
+    assert_equal true, triggered
+    assert_equal true, continued
+  end
+  
+  def test_await_delayed_defer_callback
+    triggered = false
+    trigger_callback = nil
+    results = nil
+
+    em do
+      await do
+        trigger_callback = defer do |*args|
+          results = args
+        end
+      end
+
+      triggered = true
+    end
+    
+    assert_equal false, triggered
+
+    assert trigger_callback
+    trigger_callback.call(1, :two, '3')
+    
+    assert_equal true, triggered
+    assert_equal [ 1, :two, '3' ], results
+  end
+
+  def test_await_multiple_defer
+    triggered = false
+    triggers = [ ]
+    count = 10
+    
+    em do
+      await do
+        count.times do
+          triggers << defer
+        end
+      end
+      
+      triggered = true
+    end
+    
+    assert_equal false, triggered
+
+    while (triggers.length > 1)
+      triggers.pop.call
+    end
+
+    assert_equal false, triggered
+
+    triggers.pop.call
+    
+    assert_equal true, triggered
+  end
+
+  def test_await_chained_defer
+    triggered = false
+    trigger_block_outer = nil
+    trigger_block_inner = nil
+    
+    em do
+      await do
+        trigger_block_outer = defer do
+          trigger_block_inner = defer do
+          end
+        end
+      end
+
+      triggered = true
+    end
+    
+    assert_equal false, triggered
+    
+    assert trigger_block_outer
+    trigger_block_outer.call
+
+    assert_equal false, triggered
+
+    assert trigger_block_inner
+    trigger_block_inner.call
+    
+    assert_equal true, triggered
+  end
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: await
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Scott Tadman
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-11-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: eventmachine
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Implements the await/defer pattern for event-driven or asynchronous Ruby
+email: scott@twg.ca
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.md
+files:
+- .document
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- VERSION
+- await.gemspec
+- lib/await.rb
+- test/helper.rb
+- test/test_await.rb
+homepage: http://github.com/twg/await
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Asynchronous await/defer methods for organizing callbacks
+test_files: []