asynchro 0.1.0 → 0.1.1

data/README.rdoc

@@ -10,6 +10,16 @@ The two primary components are:
 * A simple state machine defining tool that can be used to map out the steps
   required to complete an operation. This is especially useful if the process
   will vary depending on certain conditions.
+  
+== Installation
+
+The gem should be a good place to start:
+
+    gem install asynchro
+    
+The best approach is to put this in your Gemfile:
+
+    gem 'asynchro'
 
 == State
 

data/VERSION

@@ -0,0 +1 @@
+0.1.1

data/asynchro.gemspec

@@ -0,0 +1,63 @@
+# 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 = "asynchro"
+  s.version = "0.1.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Scott Tadman"]
+  s.date = "2011-09-26"
+  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 = [
+    "LICENSE.txt",
+    "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "LICENSE.txt",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "asynchro.gemspec",
+    "lib/asynchro.rb",
+    "lib/asynchro/extensions.rb",
+    "lib/asynchro/state.rb",
+    "lib/asynchro/test_helper.rb",
+    "lib/asynchro/tracker.rb",
+    "test/helper.rb",
+    "test/test_asynchro.rb",
+    "test/test_asynchro_extensions.rb",
+    "test/test_asynchro_state.rb",
+    "test/test_asynchro_test_helper.rb",
+    "test/test_asynchro_tracker.rb"
+  ]
+  s.homepage = "http://github.com/tadman/asynchro"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.10"
+  s.summary = "Ruby EventMachine Async Programming Toolkit"
+
+  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/asynchro/extensions.rb

@@ -0,0 +1,9 @@
+module Asynchro::Extensions
+  def async_chain(&block)
+    Asynchro::Tracker.new(&block)
+  end
+
+  def async_state(&block)
+    Asynchro::State.new(&block)
+  end
+end

data/lib/asynchro/state.rb

@@ -0,0 +1,62 @@
+class Asynchro::State
+  # Create a state map object. If a block is given, it is called with the
+  # instance created, then that instance is run.
+  def initialize(&block)
+    @states = {
+      :finish => [ ]
+    }
+    
+    if (block_given?)
+      case (block.arity)
+      when 0
+        instance_exec(&block)
+      else
+        block.call(self)
+      end
+    
+      self.run!
+    end
+  end
+  
+  # Declares the action to be taken when a particular state is entered. The
+  # argument is the state name and should be a Symbol. A block must be
+  # provided. If this state is already declared, the given block will be
+  # executed after the previous declarations.
+  def declare(state)
+    (@states[state.to_sym] ||= [ ]) << Proc.new
+  end
+
+  # Returns true if a particular state has been declared, false otherwise.
+  def declared?(state)
+    !!@states[state]
+  end
+  
+  # Runs a particular state, or if the state is not specified, then :start
+  # by default.
+  def run!(state = :start)
+    procs = @states[state.to_sym]
+    
+    case (state)
+    when :start
+      procs = [ lambda { finish! } ] unless (procs)
+    end
+    
+    procs and procs.each(&:call) or STDERR.puts "WARNING: No state #{state} defined."
+  end
+
+protected
+  # This lets the object instance function as a simple DSL by allowing
+  # arbitrary method names to map to various functions.
+  def method_missing(name, &block)
+    name_s = name.to_s
+    
+    case (name)
+    when /\?$/
+      self.declared?(name_s.sub(/\?$/, ''))
+    when /\!$/
+      self.run!(name_s.sub(/\!$/, ''))
+    else
+      self.declare(name, &block)
+    end
+  end
+end

data/lib/asynchro/test_helper.rb

@@ -0,0 +1,115 @@
+require 'eventmachine'
+
+module Asynchro::TestHelper
+  # Wraps a given block in an EventMachine run loop. Because this loop will
+  # monopolize the thread, a new thread is created to execute the supplied
+  # block. Exceptions are trapped from both the supplied block and the
+  # engine and raised accordingly.
+  def eventmachine
+    exception = nil
+
+    Thread.new do
+      Thread.abort_on_exception = true
+
+      # Create a thread for the engine to run on
+      begin
+        EventMachine.run do
+          Thread.new do
+            # Execute the test code in a separate thread to avoid blocking
+            # the EventMachine loop.
+            begin
+              yield
+            rescue Object => exception
+            ensure
+              begin
+                EventMachine.stop_event_loop
+              rescue Object
+                # Shutting down may trigger an exception from time to time
+                # if the engine itself has failed.
+              end
+            end
+          end
+        end
+      rescue Object => exception
+      end
+    end.join
+    
+    if (exception)
+      raise exception
+    end
+  end
+
+  # Asserts that a callback is made within a specified time, or will wait
+  # forever for the callback to occur if no time is specified. The supplied
+  # block will be called with the callback Proc which should be executed
+  # using `call` exactly once.
+  def assert_callback(time = nil, message = nil)
+    called_back = false
+    
+    Pigeonrocket.execute_in_main_thread do
+      yield(lambda { called_back = true })
+    end
+    
+    start_time = Time.now.to_i
+
+    while (!called_back)
+      select(nil, nil, nil, 0.1)
+      
+      if (time and (Time.now.to_i - start_time > time))
+        flunk(message || 'assert_callback timed out')
+      end
+    end
+  end
+
+  # Asserts that a callback is made within a specified time, or will wait
+  # forever for the callback to occur if no time is specified. The supplied
+  # block will be called with the callback Proc which should be executed
+  # using `call` as many times as specified, or 1 by default.
+  def assert_callback_times(count = 1, time = nil, message = nil)
+    called_back = 0
+    
+    Pigeonrocket.execute_in_main_thread do
+      yield(lambda { called_back += 1 })
+    end
+    
+    start_time = Time.now.to_i
+
+    while (called_back < count)
+      select(nil, nil, nil, 0.1)
+      
+      if (time and (Time.now.to_i - start_time > time))
+        flunk(message || "assert_callback_times timed out at only #{count} times")
+      end
+    end
+  end
+  
+  # Tests and re-tests assertions until all of them will pass. An optional
+  # limit on time can be specified in seconds. A short delay is introduced
+  # between tests to avoid monopolizing the CPU during testing. When the
+  # supplied block fails to produce an exception it is presumed to have been
+  # a successful test and execution will continue as normal.
+  def assert_eventually(time = nil, message = nil)
+    end_time = (time and Time.now + time)
+    exception = nil
+
+    while (true)
+      begin
+        yield
+      rescue Object => e
+        exception = e
+      else
+        break
+      end
+      
+      select(nil, nil, nil, 0.1)
+      
+      if (end_time and Time.now > end_time)
+        if (exception)
+          raise exception
+        else
+          flunk(message || 'assert_eventually timed out')
+        end
+      end
+    end
+  end
+end

data/lib/asynchro/tracker.rb

@@ -0,0 +1,52 @@
+class Asynchro::Tracker
+  # Creates a new tracker. If a block is given, this block is called with
+  # the new instance as an argument, and the tracker is automatically run.
+  def initialize
+    @sequence = 0
+    
+    if (block_given?)
+      instance_eval(&Proc.new)
+      self.run!
+    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!
+    @procs and @procs.each(&:call)
+  end
+  
+  # Executes this block when all the actions to be performed have checked in
+  # as finsished.
+  def finish
+    @finish ||= [ ]
+    @finish << Proc.new
+  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
+
+    callback = lambda {
+      if (@blocks[_sequence])
+        if ((@blocks[_sequence] -=1) <= 0)
+          @blocks.delete(_sequence)
+        end
+      
+        if (@blocks.empty?)
+          @finish and @finish.each(&:call)
+        end
+      end
+    }
+    
+    @procs ||= [ ]
+    @procs << lambda { block.call(callback) }
+  end
+end

data/test/test_asynchro_extensions.rb

@@ -0,0 +1,35 @@
+require 'helper'
+
+class TestAsynchroExtensions < Test::Unit::TestCase
+  include Asynchro::Extensions
+
+  def test_async_chain
+    chain = nil
+    
+    async_chain do |_chain|
+      chain = _chain
+    end
+    
+    assert_equal Asynchro::Tracker, chain.class
+  end
+
+  def test_async_state_explicit
+    state = nil
+    
+    async_state do |_state|
+      state = _state
+    end
+    
+    assert_equal Asynchro::State, state.class
+  end
+  
+  def test_async_state_implicit
+    state = nil
+    
+    async_state do
+      state = self
+    end
+    
+    assert_equal Asynchro::State, state.class
+  end
+end

data/test/test_asynchro_state.rb

@@ -0,0 +1,118 @@
+require 'helper'
+
+class TestAsynchroState < Test::Unit::TestCase
+  def test_empty
+    ran = false
+    instance = nil
+    
+    Asynchro::State.new do
+      ran = true
+      instance = self
+    end
+    
+    assert_eventually(5) do
+      assert_equal true, ran
+      assert_equal Asynchro::State, instance.class
+    end
+  end
+  
+  def test_declared_names
+    state = Asynchro::State.new
+    ran = [ ]
+    
+    state.declare(:start) do
+      ran << :start
+      state.run!(:state1)
+    end
+
+    state.declare(:state1) do
+      ran << :state1
+      state.run!(:state2)
+    end
+
+    state.declare(:state2) do
+      ran << :state2
+      state.run!(:state3)
+    end
+    
+    state.declare(:state3) do
+      ran << :state3
+      state.finish!
+    end
+    
+    state.run!
+    
+    assert_eventually(5) do
+      assert_equal [ :start, :state1, :state2, :state3 ], ran
+    end
+  end
+
+  def test_implicit_names
+    ran = [ ]
+
+    Asynchro::State.new do
+      start do
+        ran << :start
+        state1!
+      end
+
+      state1 do
+        ran << :state1
+        state2!
+      end
+
+      state2 do
+        ran << :state2
+        state3!
+      end
+
+      state3 do
+        ran << :state3
+        finish!
+      end
+      
+      finish do
+        ran << :finish
+      end
+    end
+
+    assert_eventually(5) do
+      assert_equal [ :start, :state1, :state2, :state3, :finish ], ran
+    end
+  end
+
+  def test_arbitrary_names
+    state = Asynchro::State.new
+    ran = [ ]
+    
+    state.start do
+      ran << :start
+      state.state1!
+    end
+
+    state.state1 do
+      ran << :state1
+      state.state2!
+    end
+
+    state.state2 do
+      ran << :state2
+      state.state3!
+    end
+    
+    state.state3 do
+      ran << :state3
+      state.finish!
+    end
+    
+    state.finish do
+      ran << :finish
+    end
+    
+    state.run!
+    
+    assert_eventually(5) do
+      assert_equal [ :start, :state1, :state2, :state3, :finish ], ran
+    end
+  end
+end

data/test/test_asynchro_test_helper.rb

@@ -0,0 +1,22 @@
+require 'helper'
+
+class TestAsynchroTestHelper < Test::Unit::TestCase
+  def test_eventmachine
+    ran = false
+    
+    eventmachine do
+      assert EventMachine.reactor_running?
+      assert !EventMachine.reactor_thread?
+      
+      EventMachine.add_timer(1) do
+        ran = true
+      end
+      
+      while (!ran)
+        # Spin-lock here while waiting for flag to be set in reactor thread
+      end
+    end
+    
+    assert_equal true, ran
+  end
+end

data/test/test_asynchro_tracker.rb

@@ -0,0 +1,52 @@
+require 'helper'
+
+class TestAsynchroTracker < Test::Unit::TestCase
+  def test_async_chain_explicit
+    count = 0
+    
+    Asynchro::Tracker.new do |chain|
+      chain.perform do |done|
+        chain.perform do |done|
+          count += 2
+          done.call
+        end
+        
+        count += 1
+        done.call
+      end
+      
+      chain.perform(4) do |done|
+        4.times do
+          count += 1
+          done.call
+        end
+      end
+      
+      chain.finish do
+        success = true
+      end
+    end
+    
+    assert_eventually(5) do
+      count == 7
+    end
+  end
+
+  def test_async_chain_implicit
+    success = false
+    
+    Asynchro::Tracker.new do
+      perform do |done|
+        done.call
+      end
+      
+      finish do
+        success = true
+      end
+    end
+    
+    assert_eventually(5) do
+      success
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asynchro
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2011-09-26 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: eventmachine
-  requirement: &2152536540 !ruby/object:Gem::Requirement
+  requirement: &2152224060 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2152536540
+  version_requirements: *2152224060
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &2152535960 !ruby/object:Gem::Requirement
+  requirement: &2152814240 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152535960
+  version_requirements: *2152814240
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &2152535400 !ruby/object:Gem::Requirement
+  requirement: &2153229120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2152535400
+  version_requirements: *2153229120
 description: Provides a number of tools to help make developing and testing asynchronous
   applications more manageable.
 email: github@tadman.ca
@@ -58,9 +58,19 @@ files:
 - LICENSE.txt
 - README.rdoc
 - Rakefile
+- VERSION
+- asynchro.gemspec
 - lib/asynchro.rb
+- lib/asynchro/extensions.rb
+- lib/asynchro/state.rb
+- lib/asynchro/test_helper.rb
+- lib/asynchro/tracker.rb
 - test/helper.rb
 - test/test_asynchro.rb
+- test/test_asynchro_extensions.rb
+- test/test_asynchro_state.rb
+- test/test_asynchro_test_helper.rb
+- test/test_asynchro_tracker.rb
 homepage: http://github.com/tadman/asynchro
 licenses:
 - MIT