contrails 0.1.0

data/Gemfile

@@ -0,0 +1,15 @@
+source "http://rubygems.org"
+
+
+gem 'eventmachine'
+gem 'rake'
+
+group 'test' do
+  gem 'rspec'
+  gem 'rantly'
+  gem 'mocha'
+end
+
+group 'development' do
+  gem 'ruby-debug19'
+end

data/Gemfile.lock

@@ -0,0 +1,41 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    archive-tar-minitar (0.5.2)
+    columnize (0.3.4)
+    diff-lcs (1.1.2)
+    eventmachine (0.12.10)
+    linecache19 (0.5.12)
+      ruby_core_source (>= 0.1.4)
+    mocha (0.9.12)
+    rake (0.8.7)
+    rantly (0.3.0)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+    ruby-debug-base19 (0.11.25)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby_core_source (>= 0.1.4)
+    ruby-debug19 (0.11.6)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby-debug-base19 (>= 0.11.19)
+    ruby_core_source (0.1.5)
+      archive-tar-minitar (>= 0.5.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  eventmachine
+  mocha
+  rake
+  rantly
+  rspec
+  ruby-debug19

data/README.markdown

@@ -0,0 +1,29 @@
+Contrails - declarative concurrency for EventMachine
+====================================================
+
+
+![Contrails](http://github.com/likely/contrails/raw/master/contrib/contrails.jpg)
+
+Contrails is a lightweight DSL that allows concurrent processes to be specified using an intuitive, declarative syntax for execution by EventMachine. It consists of a process class that wraps a block, and can then be chained with other processes in series using the `>>` operator, and composed into a single process that executes its constituent processes in parallel using the `*` operator. A trivial example:
+
+    Contrails::Process.new { get_an_integer_from_somewhere } >> Contrails.Process.new {|x| x*2 } * {Contrails::Process.new {|x| x * 3}  >> Contrails::Process.new {|x,y| x+y } 
+
+This takes a number from some input, computes its multiplication by two and three in parallel, then sums both values once both computations have finished.
+
+There's still rather a lot of unsightly syntax there, right? Perhaps even more so than before. However, if you import the Contrails::Utils module, you'll get a few other useful methods:
+
+ * the 'trails' method is an alias for Contrails::Process.new
+
+    `trail { get_integer } >> trail { |x| x * 3} * trail { |x| x * 2 } >> trail {|x, y| x+y }`
+
+ * the 'seq' method sequences all its arguments
+
+    `seq(trail, trail2, trail3) == trail >> trail2 >> trail3`
+
+ * the 'par' method composes all its arguments in parallel
+
+    `par(trail, trail2, trail3) == trail * trail2 * trail3`
+
+Enjoy! Questions, comments, feature requests and patches always welcome.
+
+(Photo by [FrancoisRoche](http://www.flickr.com/photos/francoisroche/2563417399/) on flickr, Licence: CC BY-SA)

data/Rakefile

@@ -0,0 +1,97 @@
+require 'rubygems'
+require 'bundler/setup'
+require 'rspec/core/rake_task'
+
+task :default => :test
+task :test => :spec
+
+if !defined?(RSpec)
+  puts "spec targets require RSpec"
+else
+  desc "Run all examples"
+  RSpec::Core::RakeTask.new(:spec) do |t|
+    t.pattern = 'spec/**/*_spec.rb'
+    t.rspec_opts = ['-cfs']
+  end
+end
+
+
+require "rubygems"
+require "rubygems/package_task"
+require "rdoc/task"
+
+require "rspec"
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = %w(--format documentation --colour)
+end
+
+
+task :default => ["spec"]
+
+# This builds the actual gem. For details of what all these options
+# mean, and other ones you can add, check the documentation here:
+#
+#   http://rubygems.org/read/chapter/20
+#
+spec = Gem::Specification.new do |s|
+
+  # Change these as appropriate
+  s.name              = "contrails"
+  s.version           = "0.1.0"
+  s.summary           = "Declarative concurrency for EventMachine"
+  s.author            = "Tim Cowlishaw"
+  s.email             = "tim@timcowlishaw.co.uk"
+  s.homepage          = "http://github.com/likely/contrails"
+
+  s.has_rdoc          = true
+  s.extra_rdoc_files  = %w(README.markdown)
+  s.rdoc_options      = %w(--main README.markdown)
+
+  # Add any extra files to include in the gem
+  s.files             = %w(Gemfile.lock Rakefile README.markdown Gemfile) + Dir.glob("{spec,lib}/**/*")
+  s.require_paths     = ["lib"]
+
+  # If you want to depend on other gems, add them here, along with any
+  # relevant versions
+  s.add_dependency("eventmachine")
+
+  # If your tests use any gems, include them here
+  s.add_development_dependency("rspec")
+end
+
+# This task actually builds the gem. We also regenerate a static
+# .gemspec file, which is useful if something (i.e. GitHub) will
+# be automatically building a gem for this project. If you're not
+# using GitHub, edit as appropriate.
+#
+# To publish your gem online, install the 'gemcutter' gem; Read more 
+# about that here: http://gemcutter.org/pages/gem_docs
+Gem::PackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc "Build the gemspec file #{spec.name}.gemspec"
+task :gemspec do
+  file = File.dirname(__FILE__) + "/#{spec.name}.gemspec"
+  File.open(file, "w") {|f| f << spec.to_ruby }
+end
+
+# If you don't want to generate the .gemspec file, just remove this line. Reasons
+# why you might want to generate a gemspec:
+#  - using bundler with a git source
+#  - building the gem without rake (i.e. gem build blah.gemspec)
+#  - maybe others?
+task :package => :gemspec
+
+# Generate documentation
+RDoc::Task.new do |rd|
+  rd.main = "README.markdown"
+  rd.rdoc_files.include("README.markdown", "lib/**/*.rb")
+  rd.rdoc_dir = "rdoc"
+end
+
+desc 'Clear out RDoc and generated packages'
+task :clean => [:clobber_rdoc, :clobber_package] do
+  rm "#{spec.name}.gemspec"
+end

data/lib/contrails/chainable.rb

@@ -0,0 +1,30 @@
+module Contrails
+  module Chainable
+
+    def bind(other)
+      raise NotImplementedError
+    end
+
+    def distribute(other)
+      raise NotImplementedError
+    end
+
+    def call(*a)
+      raise NotImplementedError
+    end
+
+    def to_proc
+      lambda {|*a| self.call(*a) }
+    end
+
+    def >>(other)
+      self.bind(other)
+    end
+
+    def *(other)
+      self.distribute(other)
+    end
+
+  end
+end
+

data/lib/contrails/helpers.rb

@@ -0,0 +1,9 @@
+module Contrails
+  module Helpers
+    class << self
+      def unwrap_array(array)
+        array.inject([]) {|m,n| m + n}
+      end
+    end
+  end
+end

data/lib/contrails/parallel.rb

@@ -0,0 +1,44 @@
+require 'em/deferrable'
+require 'contrails/chainable'
+require 'contrails/semaphore'
+module Contrails
+  class Parallel
+    include EventMachine::Deferrable
+    include Contrails::Chainable
+    def initialize(*procs)
+      results = []
+      @procs = procs
+      @semaphore = Semaphore.new(@procs.length, results)
+      ps = @procs.map.with_index do |p, i|
+        p = p.dup
+        p.callback {|*r| results[i] = r; @semaphore.signal}
+        p
+      end
+      internal_callback { |*a|
+        ps.each {|p| EM.next_tick(lambda { p.call(*a) }) }
+      }
+    end
+
+    alias_method :internal_callback, :callback
+    private :internal_callback
+
+    def callback(&b)
+      @semaphore.callback(&b)
+    end
+
+    def bind(other)
+      @semaphore.callback(&other)
+      self
+    end
+
+    def distribute(other)
+      Contrails::Parallel.new(*(@procs + [other]))
+    end
+
+    def call(*a)
+      self.succeed(*a)
+    end
+
+  end
+end
+

data/lib/contrails/process.rb

@@ -0,0 +1,32 @@
+require 'em/deferrable'
+require 'contrails/parallel'
+module Contrails
+  class Process
+    include EventMachine::Deferrable
+    include Contrails::Chainable
+
+    class << self
+      def return(&b)
+        self.new(&b)
+      end
+    end
+
+    def initialize(&l)
+      @lambda = l
+    end
+
+    def bind(other)
+      p = Contrails::Process.new(&self)
+      p.callback(&other)
+      return p
+    end
+
+    def distribute(other)
+      Contrails::Parallel.new(self, other)
+    end
+    
+    def call(*a)
+      self.succeed(*@lambda.call(*a)) 
+    end
+  end
+end

data/lib/contrails/semaphore.rb

@@ -0,0 +1,23 @@
+require 'em/deferrable'
+require 'contrails/helpers'
+module Contrails
+  class Semaphore
+    
+    include EventMachine::Deferrable
+
+    def initialize(n, results)
+      @value = n
+      @results = results
+      @mutex = Mutex.new
+    end
+
+    def signal
+      @mutex.synchronize do
+        if(@value -= 1) == 0
+          self.succeed(*Contrails::Helpers.unwrap_array(@results))  
+        end
+      end
+    end
+  end
+end
+

data/lib/contrails/utils.rb

@@ -0,0 +1,16 @@
+require 'contrails/process'
+module Contrails
+  module Utils
+    def trail(&block)
+      return Contrails::Process.new(&block)
+    end
+
+    def seq(*ps)
+      return ps.inject {|m,n| m.bind(n) }
+    end
+
+    def par(*ps)
+      return ps.inject {|m,n| m.distribute(n)}
+    end
+  end
+end

data/lib/contrails.rb

@@ -0,0 +1,5 @@
+$: << File.join(File.dirname(__FILE__))
+module Contrails
+end
+require "contrails/process"
+require "contrails/utils"

data/spec/process_spec.rb

@@ -0,0 +1,167 @@
+require 'spec_helper'
+
+describe Contrails::Process do
+  describe "class methods:" do
+    
+    describe "new" do
+      it "wraps the passed lambda in a process" do
+        for_all do
+          int = integer
+          async_assertion(Contrails::Process.new { |x| x**2 }, int) { |result|
+            result.should == int**2
+          }
+        end
+      end
+    end
+    
+    describe "return" do
+       it "delegates to the constructor method" do
+         lamb = lambda {|x, y| x + y }
+         Contrails::Process.expects(:new) #sadly we can't test for block arguments with mocha
+         Contrails::Process.return(&lamb)
+       end
+    end
+  end
+
+  describe "instance methods:" do
+    describe "bind" do
+      it "returns a process which sequences the second operation after the first" do
+        for_all do
+          context = mock
+          context.expects(:first).in_sequence
+          context.expects(:second).in_sequence
+          proc1 = Contrails::Process.new { context.first }
+          proc2 = Contrails::Process.new { context.second }
+          async_assertion(proc1.bind(proc2))
+        end
+      end
+      it "successively calls other processes bound onto the argument" do
+        for_all do 
+          context = mock
+          context.expects(:first).in_sequence
+          context.expects(:second).in_sequence
+          context.expects(:third).in_sequence
+          proc1 = Contrails::Process.new { context.first }
+          proc2 = Contrails::Process.new { context.second }
+          proc3 = Contrails::Process.new { context.third }
+          async_assertion(proc1.bind(proc2).bind(proc3))
+        end
+      end
+
+      it "passes the return value of each process to its successors" do
+        for_all do
+          int= integer
+          proc1 = Contrails::Process.new { |x| x.should == int; x+1}
+          proc2 = Contrails::Process.new { |x| x.should == int+1; x+1}
+          proc3 = Contrails::Process.new { |x| x.should == int+2; x+1}
+          async_assertion(proc1.bind(proc2).bind(proc3), int) {|x| x.should == int+3}
+        end
+      end
+    end
+
+    describe "distribute" do
+      
+      it "returns a process that executes both processes, yielding the results of both as a pair" do
+        for_all {
+          int = integer
+          proc1 = Contrails::Process.new {|x| x*2}
+          proc2 = Contrails::Process.new {|x| x*3}
+          async_assertion(proc1.distribute(proc2), int) {|x1, x2|
+            x1.should == int*2
+            x2.should == int*3
+          }
+        }
+             end
+       it "yields the return value of both to subsequently bound processes" do
+          for_all {
+            int = integer
+            proc1 = Contrails::Process.new {|x| x*2 }
+            proc2 = Contrails::Process.new {|x| x*3 }
+            proc3 = Contrails::Process.new {|x,y| x + y }
+            async_assertion(proc1.distribute(proc2).bind(proc3), int) {|r|
+              r.should == int*2 + int*3
+            }
+          }
+        end
+
+      it "executes both processes in parallel" do
+        for_all {
+          time = float
+          guard time > 0.05
+          guard time < 0.25
+          context = mock
+          context.expects(:first).in_sequence
+          context.expects(:second).in_sequence
+          proc1 = Contrails::Process.new { sleep(time); context.second }
+          proc2 = Contrails::Process.new { context.first }
+          async_assertion(proc1.distribute(proc2))
+        }
+      end
+      it "executes any subsequently distributed processes in parallel" do
+        for_all {
+          time = float
+          guard time > 0.05
+          guard time < 0.25
+          context = mock
+          context.expects(:first).in_sequence
+          context.expects(:second).in_sequence
+          context.expects(:third).in_sequence
+          proc1 = Contrails::Process.new { sleep(time); context.third }
+          proc2 = Contrails::Process.new { sleep(time/2); context.second }
+          proc3 = Contrails::Process.new { context.first }
+          async_assertion(proc1.distribute(proc2).distribute(proc3))
+        }
+      end
+
+      it "collects the results of all processes into a single list of arguments to its callback" do
+        for_all {
+          int = integer
+          proc1 = Contrails::Process.new {|x| x+1 }
+          proc2 = Contrails::Process.new {|x| x+2 }
+          proc3 = Contrails::Process.new {|x| x+3 }
+          async_assertion(proc1.distribute(proc2).distribute(proc3), int) {|a|
+            a.should == [int+1, int+2, int+3]
+          }
+        }
+      end
+    end
+
+    describe "call" do
+      it "calls the lambda and sets itself as succeeded, passing the blocks return value" do
+        for_all do
+          int = integer
+          async_assertion(Contrails::Process.new { |x| x + 2}, int) { |result|
+            result.should == int + 2
+          }
+        end
+      end
+    end
+
+    describe "to proc" do
+      it "returns a lambda which wraps the computation" do
+        p = Contrails::Process.new { 1+2 }
+        p.expects(:call)
+        p.to_proc.should be_a(Proc)
+        p.to_proc.call
+      end
+    end
+
+    describe ">>" do
+      it "delegates to the bind method" do
+        proc1 = Contrails::Process.new {|x| x**2}
+        proc2 = Contrails::Process.new {|x| x+1 }
+        proc1.expects(:bind).with(proc2)
+        proc1 >> proc2
+      end
+    end
+
+    describe "*" do
+      it "delegates to the distribute method" do
+        proc1 = Contrails::Process.new {|x| x**2}
+        proc2 = Contrails::Process.new {|x| x+1 }
+        proc1.expects(:distribute).with(proc2)
+        proc1 * proc2
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,38 @@
+$: << File.join(File.dirname(__FILE__),"..")
+require 'rubygems'
+require 'bundler/setup'
+require 'rspec'
+require 'rantly'
+require 'mocha'
+require 'eventmachine'
+require 'em/deferrable'
+require 'lib/contrails'
+RSpec.configure do |config|
+  config.mock_framework = :mocha
+end
+
+Rantly.send(:include, Mocha::API)
+
+def for_all(&block)
+  Rantly.each(ENV['RANTLY_LIMIT'] ? ENV['RANTLY_LIMIT'].to_i : 100, &block) 
+end
+
+class DeferrableTest
+  include EventMachine::Deferrable
+  def initialize(*a, &b)
+    @args = a
+    @lambda = b
+  end
+
+  def to_proc
+    lambda { succeed(*@lambda.call(*@args)) }
+  end
+end
+
+def async_assertion(process, *args, &callback)
+  EM.run_block do
+    deferrable = DeferrableTest.new(*args, &process)
+    deferrable.callback(&callback) if callback
+    EM.defer(&deferrable)
+  end
+end

data/spec/utils_spec.rb

@@ -0,0 +1,40 @@
+require 'spec_helper'
+class TestImplementation
+  include Contrails::Utils
+end
+
+describe Contrails::Utils do
+  before(:all) do
+    @ti = TestImplementation.new
+  end
+  describe "trail" do
+    it "creates a new process with the passed block" do
+      Contrails::Process.expects(:new)
+      @ti.trail {|x| x+1 }
+    end
+  end
+
+  describe "seq" do
+    it "binds together the supplied processes" do
+      p1 = mock
+      p2 = mock
+      p3 = mock
+      intermediate = mock
+      p1.expects(:bind).with(p2).returns(intermediate)
+      intermediate.expects(:bind).with(p3)
+      @ti.seq(p1,p2,p3)
+    end
+  end
+
+  describe "par" do
+    it "distributes between the supplied processes" do
+      p1 = mock
+      p2 = mock
+      p3 = mock
+      intermediate = mock
+      p1.expects(:distribute).with(p2).returns(intermediate)
+      intermediate.expects(:distribute).with(p3)
+      @ti.par(p1,p2,p3)
+    end
+  end
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification 
+name: contrails
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Tim Cowlishaw
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-08-19 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: eventmachine
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  prerelease: false
+  version_requirements: *id002
+description: 
+email: tim@timcowlishaw.co.uk
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.markdown
+files: 
+- Gemfile.lock
+- Rakefile
+- README.markdown
+- Gemfile
+- spec/utils_spec.rb
+- spec/spec_helper.rb
+- spec/process_spec.rb
+- lib/contrails/process.rb
+- lib/contrails/chainable.rb
+- lib/contrails/parallel.rb
+- lib/contrails/utils.rb
+- lib/contrails/semaphore.rb
+- lib/contrails/helpers.rb
+- lib/contrails.rb
+has_rdoc: true
+homepage: http://github.com/likely/contrails
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.markdown
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -1260005474418307725
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.2
+signing_key: 
+specification_version: 3
+summary: Declarative concurrency for EventMachine
+test_files: []
+