asynchro 0.1.5 → 0.4.0

data/README.rdoc

@@ -1,7 +1,7 @@
 = asynchro
 
-This is a set of extensions for Test::Unit::TestCase and any plain Ruby
-classes that will be operating inside the EventMachine framework.
+This is a set of extensions for event-driven, asynchronous Ruby applications
+and improved support for testing within the EventMachine engine.
 
 The two primary components are:
 
@@ -13,15 +13,15 @@ The two primary components are:
   
 == Installation
 
-The gem should be a good place to start:
+Using the gem installation tool is the easiest way to get started:
 
     gem install asynchro
     
-The best approach is to put this in your Gemfile:
+If you're using it within a bundler managed project, add to your Gemfile:
 
     gem 'asynchro'
 
-== State
+== Using Asynchro::State
 
 To define a state mapping, include the Asynchro::Extensions methods and
 then use the `async_state` method:
@@ -75,21 +75,35 @@ If this warning is undesirable, declare the state with an empty block.
 Be careful to avoid entering states for which there is no exit condition
 or the execution will never successfully complete.
 
-== Tracker
+== Using Asynchro::Tracker
 
 The tracker component is used to process multiple blocks independently, yet
-confirm that they have all completed before moving on. An example is:
+confirm that they have all completed before moving on. This control structure
+helps to avoid duplicating logic in callback methods.
 
+A simple example is:
+
+    require 'rubygems'
+    gem 'asynchro'
+    require 'asynchro'
+    
     include Asynchro::Extensions
+    
+    def example_async_call
+      yield
+    end
+    
     success = false
 
     async_tracker do |tracker|
       tracker.perform do |done|
-        done.call
+        example_async_call do
+          done.call
+        end
       end
 
       tracker.perform(4) do |done|
-        4.times do
+        example_async_call do
           done.call
         end
       end
@@ -98,6 +112,13 @@ confirm that they have all completed before moving on. An example is:
         success = true
       end
     end
+    
+The main `async_tracker` call will appear to block until all of the actions
+defined by `perform` are completed. More specifically, the `done` trigger
+must be called in order to carry forward. Generally this trigger is passed
+through to the final block that must be executed before the operation is
+completed. In this example the trigger is scoped such that the inner block
+has access to it.
 
 The `perform` method is used to declare something that must be performed,
 and the `finish` method will be executed once all of the declared blocks
@@ -107,13 +128,20 @@ The `perform` method takes a numerical argument that indicates the number of
 times the callback must be called in order to be completed. The default is 1.
 Negative or zero values will result in undefined behavior.
 
+It is possible to declare `perform` blocks at any time prior to the completion
+of the last block. This enables additional processing to be performed only
+if certain requirements are met, or for actions to be chained together as
+required.
+
 Just as multiple `perform` blocks can be declared, multiple `finish` blocks
-can be supplied. These will execute in order, once, upon completion.
+can be supplied. These will execute in the order they are defined, once, upon
+completion of all the prerequisite blocks.
 
 As there is no timeout, the tracker will wait for an indefinite period of
 time if something precludes one or more of the callbacks from being executed.
-This tracker is only suitable for asynchronous code that will always trigger
-a callback of some sort within an acceptable period of time.
+This tracker is only suitable for asynchronous code that is designed such that
+it will always trigger a callback of some sort within an acceptable period of
+time.
 
 == Other Notes
 
@@ -121,5 +149,5 @@ Additional demonstrations of these are included in the test/ directory.
 
 == Copyright
 
-Copyright (c) 2011 Scott Tadman, The Working Group Inc. See LICENSE.txt for
-further details.
+Copyright (c) 2011-2012 Scott Tadman, The Working Group Inc.
+See LICENSE.txt for further details.

data/VERSION

@@ -1 +1 @@
-0.1.5
+0.4.0

data/asynchro.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "asynchro"
-  s.version = "0.1.5"
+  s.version = "0.4.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Scott Tadman"]
-  s.date = "2011-09-27"
+  s.date = "2012-07-23"
   s.description = "Provides a number of tools to help make developing and testing asynchronous applications more manageable."
   s.email = "github@tadman.ca"
   s.extra_rdoc_files = [
@@ -39,7 +39,7 @@ Gem::Specification.new do |s|
   s.homepage = "http://github.com/tadman/asynchro"
   s.licenses = ["MIT"]
   s.require_paths = ["lib"]
-  s.rubygems_version = "1.8.10"
+  s.rubygems_version = "1.8.24"
   s.summary = "Ruby EventMachine Async Programming Toolkit"
 
   if s.respond_to? :specification_version then

data/lib/asynchro.rb

@@ -1,3 +1,5 @@
+require 'fiber'
+
 module Asynchro
   autoload(:Extensions, 'asynchro/extensions')
   autoload(:State, 'asynchro/state')

data/lib/asynchro/extensions.rb

@@ -6,4 +6,14 @@ module Asynchro::Extensions
   def async_state(&block)
     Asynchro::State.new(&block)
   end
+  
+  def yield_to
+    this = Fiber.current
+    
+    fiber = Fiber.new do
+      yield(lambda { fiber.transfer(this) })
+    end
+
+    fiber.transfer(fiber)
+  end
 end

data/lib/asynchro/test_helper.rb

@@ -46,7 +46,7 @@ module Asynchro::TestHelper
   def assert_callback(time = nil, message = nil)
     called_back = false
     
-    Pigeonrocket.execute_in_main_thread do
+    EventMachine.next_tick do
       yield(lambda { called_back = true })
     end
     
@@ -68,7 +68,7 @@ module Asynchro::TestHelper
   def assert_callback_times(count = 1, time = nil, message = nil)
     called_back = 0
     
-    Pigeonrocket.execute_in_main_thread do
+    EventMachine.next_tick do
       yield(lambda { called_back += 1 })
     end
     

data/lib/asynchro/tracker.rb

@@ -6,58 +6,82 @@ class Asynchro::Tracker
     
     if (block_given?)
       yield(self)
-
-      self.run!
+      
+      Fiber.new do
+        self.run!
+      end.resume
     end
   end
   
-  # Runs through the tasks to perform for this tracker. Should only be
-  # called if this object is initialized without a supplied block as in that
-  # case, this would have been called already.
-  def run!
-    if (@procs)
-      @procs.each(&:call)
-    else
-      @finish and @finish.each(&:call)
+  # Performs an action. The supplied block will be called with a callback
+  # tracking Proc that should be triggered with `call` as many times as
+  # are specified in the `count` argument. When the correct number of calls
+  # have been made, this action is considered finished.
+  def perform(count = 1, *args)
+    @operations ||= { }
+
+    _sequence = @sequence += 1
+    @operations[_sequence] = true
+
+    fiber = Fiber.new do
+      called = false
+      should_resume = false
+
+      callback = lambda {
+        called = true
+
+        if (should_resume)
+          fiber.resume
+        end
+      }
+
+      count.times do
+        called = false
+
+        yield(callback, *args)
+
+        unless (called)
+          should_resume = true
+          Fiber.yield
+        end
+      end
+
+      @operations.delete(_sequence)
+
+      if (self.finished?)
+        self.finish!
+      end
     end
+
+    (@fibers ||= [ ]) << fiber
   end
-  
+
   # Executes this block when all the actions to be performed have checked in
   # as finsished.
   def finish(&block)
-    @finish ||= [ ]
-    @finish << block
+    (@finish ||= [ ]) << block
   end
   
   # Returns true if this tracker has completed all supplied blocks, or false
   # otherwise.
   def finished?
-    !@blocks or @blocks.empty?
+    !@operations or @operations.empty?
   end
   
-  # Performs an action. The supplied block will be called with a callback
-  # tracking Proc that should be triggered with `call` as many times as
-  # are specified in the `count` argument. When the correct number of calls
-  # have been made, this action is considered finished.
-  def perform(count = 1, &block)
-    @blocks ||= { }
-
-    _sequence = @sequence += 1
-    @blocks[_sequence] = count
+protected
+  # Runs through the tasks to perform for this tracker. Should only be
+  # called if this object is initialized without a supplied block as in that
+  # case, this would have been called already.
+  def run!
+    if (self.finished?)
+      self.finish!
+    else
+      @fibers.each(&:resume)
+    end
+  end
 
-    callback = lambda {
-      if (@blocks[_sequence])
-        if ((@blocks[_sequence] -=1) <= 0)
-          @blocks.delete(_sequence)
-        end
-      
-        if (self.finished?)
-          @finish and @finish.each(&:call)
-        end
-      end
-    }
-    
-    @procs ||= [ ]
-    @procs << lambda { block.call(callback) }
+  # Executes the defined finish blocks and resumes execution
+  def finish!
+    @finish and @finish.each(&:call)
   end
 end

data/test/helper.rb

@@ -18,4 +18,14 @@ require 'asynchro'
 
 class Test::Unit::TestCase
   include Asynchro::TestHelper
+  
+  def assert_exception(type)
+    begin
+      yield
+    rescue => e
+      assert_equal type, e.class
+    else
+      assert_equal type, nil
+    end
+  end
 end

data/test/test_asynchro_extensions.rb

@@ -43,4 +43,20 @@ class TestAsynchroExtensions < Test::Unit::TestCase
     
     assert_equal Asynchro::State, state.class
   end
+  
+  def test_yield_to
+    ran = false
+    subfiber = nil
+    
+    yield_to do |f|
+      ran = true
+      sleep(10)
+    end
+    
+    assert_equal ran, true
+    
+    assert_exception LocalJumpError do
+      yield_to
+    end
+  end
 end

data/test/test_asynchro_tracker.rb

@@ -16,32 +16,65 @@ class TestAsynchroTracker < Test::Unit::TestCase
   
   def test_simple_tracker
     count = 0
+    success = 0
     
     Asynchro::Tracker.new do |tracker|
-      tracker.perform do |done|
-        tracker.perform do |done|
-          count += 2
-          done.call
+      tracker.perform(3) do |done1|
+        tracker.perform(2) do |done2|
+          count += 10
+          done2.call
         end
         
         count += 1
-        done.call
+        done1.call
+      end
+      
+      trigger = nil
+      
+      tracker.perform(8) do |done|
+        count += 100
+        trigger = done
       end
       
       tracker.perform(4) do |done|
-        4.times do
-          count += 1
-          done.call
-        end
+        count += 1000
+        trigger.call
+        trigger.call
+        done.call
       end
       
       tracker.finish do
-        success = true
+        success += 1
+      end
+
+      tracker.finish do
+        success += 100
       end
     end
     
-    assert_eventually(5) do
-      count == 7
+    assert_equal 4863, count
+    assert_equal 101, success
+  end
+  
+  def test_repetition
+    test_cycle = 1000
+    count = 0
+
+    Asynchro::Tracker.new do |tracker1|
+      tracker1.perform(test_cycle) do |done1|
+        Asynchro::Tracker.new do |tracker2|
+          tracker2.perform(test_cycle) do |done2|
+            count += 1
+            done2.call
+          end
+          
+          tracker2.finish do
+            done1.call
+          end
+        end
+      end
     end
+    
+    assert_equal test_cycle * test_cycle, count
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asynchro
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-27 00:00:00.000000000Z
+date: 2012-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: eventmachine
-  requirement: &2154668920 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,15 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2154668920
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &2154668040 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +37,15 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2154668040
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &2154657980 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +53,12 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2154657980
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Provides a number of tools to help make developing and testing asynchronous
   applications more manageable.
 email: github@tadman.ca
@@ -92,7 +107,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.10
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Ruby EventMachine Async Programming Toolkit