agent 0.1.0 → 0.9.0

data/.gitignore

@@ -1,3 +1,5 @@
 pkg/*
 *.gem
 .bundle
+tmp/*
+.rbx

data/Gemfile

@@ -1,4 +1,3 @@
 source "http://rubygems.org"
 
-# Specify your gem's dependencies in go.gemspec
 gemspec

data/Gemfile.lock

@@ -1,22 +1,21 @@
 PATH
   remote: .
   specs:
-    agent (0.0.1)
+    agent (1.0.0)
 
 GEM
   remote: http://rubygems.org/
   specs:
-    diff-lcs (1.1.2)
-    rspec (2.0.1)
-      rspec-core (~> 2.0.1)
-      rspec-expectations (~> 2.0.1)
-      rspec-mocks (~> 2.0.1)
-    rspec-core (2.0.1)
-    rspec-expectations (2.0.1)
-      diff-lcs (>= 1.1.2)
-    rspec-mocks (2.0.1)
-      rspec-core (~> 2.0.1)
-      rspec-expectations (~> 2.0.1)
+    diff-lcs (1.1.3)
+    rake (0.9.2.2)
+    rspec (2.9.0)
+      rspec-core (~> 2.9.0)
+      rspec-expectations (~> 2.9.0)
+      rspec-mocks (~> 2.9.0)
+    rspec-core (2.9.0)
+    rspec-expectations (2.9.0)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.9.0)
 
 PLATFORMS
   java
@@ -24,4 +23,5 @@ PLATFORMS
 
 DEPENDENCIES
   agent!
+  rake
   rspec

data/README.md

@@ -1,11 +1,12 @@
 # Agent
 
-Agent is a diverse family of related approaches for modelling concurrent systems, in Ruby. In other words, it is a collection of different [process calculi](http://en.wikipedia.org/wiki/Process_calculus) primitives and patterns, with no specific, idiomatic affiliation to any specific implementation. A few available patterns so far:
+Agent is an attempt at [Go-like (CSP / pi-calculus) concurrency in Ruby](http://www.igvita.com/2010/12/02/concurrency-with-actors-goroutines-ruby/), but with an additional twist. It is a collection of different [process calculi](http://en.wikipedia.org/wiki/Process_calculus) primitives and patterns, with no specific, idiomatic affiliation to any specific implementation. A few available patterns so far:
 
  - Goroutines on top of green Ruby threads
- - Named, in-memory channels
+ - Named, Typed, Bufferd and Unbufferred in-memory "channels"
+ - Selectable "channels"
 
-This gem is a work in progress & an experiment, so treat it as such. At the moment, it is heavily influenced by Google's Go and π-calculus primitives.
+This gem is a work in progress, so treat it as such.
 
 # Working Code Examples
 
@@ -14,29 +15,63 @@ This gem is a work in progress & an experiment, so treat it as such. At the mome
  * [Sieve of Eratosthenes](https://github.com/igrigorik/agent/blob/master/spec/examples/sieve_spec.rb)
 
 # Example: Goroutine Generator
+A simple multi-threaded consumer-producer, except without a thread or a mutex in sight! Note that by default Agent channels are unbuffered, meaning that the size is implicitly set to 0. Hence, in example below, the producer will generate a single value, and block until we call receive - rinse, repeat.
 
-    producer = Proc.new do |c|
-      puts "Starting generator: #{c.name}"
+```ruby
+c = channel!(Integer)
 
-      i = 0
-      loop { c.pipe << i+= 1 }
-    end
+go! do
+  i = 0
+  loop { c << (i += 1) }
+end
 
-    c = Agent::Channel.new(name: :incr, type: Integer)
+p c.receive.first # => 1
+p c.receive.first # => 2
+```
 
-    Generator = Struct.new(:name, :pipe)
-    g = Generator.new(:incr, c)
+# Example: Multi-channel selector
+A "select" statement chooses which of a set of possible communications will proceed. It looks similar to a "switch" statement but with the cases all referring to communication operations. Select will block until one of the channels becomes available:
 
-    go(g, &producer)
+```ruby
+cw = channel!(Integer, 1)
+cr = channel!(Integer, 1)
 
-    c.receive
-    c.receive
+select do |s|
+  s.case(cr, :receive) { |value| do_something(value) }
+  s.case(cw, :send, 3)
+end
+```
 
+In example above, cr is currently unavailable to read from (since its empty), but cw is ready for writing since the channel is buffered and empty. Hence, select will immediately choose the cw case and execute that code block.
+
+```ruby
+cr = channel!(Integer, 1)
+
+select do |s|
+  s.case(cr, :receive) { |value| do_something(value) }
+  s.default            { puts :default }
+end
+```
+
+In this example, cr is unavailable for read (since its empty), but we also provide "default" case which is executed immediately if no other cases are matched. In other words, no blocking.
+
+```ruby
+cr = channel!(Integer, 1)
+
+select do |s|
+  s.case(cr, :receive) { |value| do_something(value) }
+  s.timeout(1.0)       { puts :timeout }
+end
+```
+
+Once again, cr is empty, hence cannot be read from and there is no default block. Select will block until cr is readable or until the timeout condition is met - which in the case above is set to 1 second.
 
 # Go & π-calculus: Background & Motivation
 
 *Do not communicate by sharing memory; instead, share memory by communicating.*
 
+See [Concurrency with Actors, Goroutines & Ruby](http://www.igvita.com/2010/12/02/concurrency-with-actors-goroutines-ruby/) for motivation and comparison to other concurrency models.
+
 Concurrent programming in many environments is made difficult by the subtleties required to implement correct access to shared variables. Google's Go encourages a different approach in which shared values are passed around on channels and, in fact, never actively shared by separate threads of execution. Only one goroutine has access to the value at any given time. Data races cannot occur, by design.
 
 One way to think about this model is to consider a typical single-threaded program running on one CPU. It has no need for synchronization primitives. Now run another such instance; it too needs no synchronization. Now let those two communicate; if the communication is the synchronizer, there's still no need for other synchronization. Unix pipelines, for example, fit this model perfectly. Although Go's approach to concurrency originates in Hoare's Communicating Sequential Processes (CSP), it can also be seen as a type-safe generalization of Unix pipes.
@@ -46,28 +81,8 @@ To learn more about Go see following resources:
  * [golang.org](http://golang.org/)
  * [Go's concurrency](http://golang.org/doc/effective_go.html#concurrency)
  * [Go's channels](http://golang.org/doc/effective_go.html#channels)
+ * [Go's select statement](http://golang.org/doc/go_spec.html#Select_statements)
 
 # License
 
-(The MIT License)
-
-Copyright (c) 2010 Ilya Grigorik
-
-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.
+The MIT License - Copyright (c) 2011 Ilya Grigorik

data/Rakefile

@@ -1,2 +1,7 @@
 require 'bundler'
 Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+task :default => :spec

data/agent.gemspec

@@ -13,6 +13,7 @@ Gem::Specification.new do |s|
   s.description = s.summary
 
   s.rubyforge_project = "agent"
+  s.add_development_dependency "rake"
   s.add_development_dependency "rspec"
 
   s.files         = `git ls-files`.split("\n")

data/autotest/discover.rb

@@ -1 +1,9 @@
-Autotest.add_discovery { 'rspec2' }
+Autotest.add_discovery { 'rspec2' }
+
+if RUBY_PLATFORM =~ /java/
+  Autotest.add_hook :initialize do |at|
+    def at.ruby
+      "#{super} --1.9"
+    end
+  end
+end

data/benchmark/multi_ruby_bench.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+
+if [[ -s "$HOME/.rvm/scripts/rvm" ]] ; then
+
+  # First try to load from a user install
+  source "$HOME/.rvm/scripts/rvm"
+
+elif [[ -s "/usr/local/rvm/scripts/rvm" ]] ; then
+
+  # Then try to load from a root install
+  source "/usr/local/rvm/scripts/rvm"
+
+else
+
+  printf "ERROR: An RVM installation was not found.\n"
+
+fi
+
+echo
+echo `ruby -v`
+echo
+ruby benchmark/sieve.rb 0
+ruby benchmark/sieve.rb 1
+ruby benchmark/sieve.rb 2
+ruby benchmark/sieve.rb 3
+echo
+rvm use 1.8.7
+echo
+echo `ruby -v`
+echo
+ruby benchmark/sieve.rb 0
+ruby benchmark/sieve.rb 1
+ruby benchmark/sieve.rb 2
+ruby benchmark/sieve.rb 3
+echo
+rvm use 1.9.2
+echo
+echo `ruby -v`
+echo
+ruby benchmark/sieve.rb 0
+ruby benchmark/sieve.rb 1
+ruby benchmark/sieve.rb 2
+ruby benchmark/sieve.rb 3
+echo
+rvm use 1.9.3
+echo
+echo `ruby -v`
+echo
+ruby benchmark/sieve.rb 0
+ruby benchmark/sieve.rb 1
+ruby benchmark/sieve.rb 2
+ruby benchmark/sieve.rb 3
+echo
+rvm use jruby
+echo
+echo `ruby -v`
+echo
+ruby benchmark/sieve.rb 0
+ruby benchmark/sieve.rb 1
+ruby benchmark/sieve.rb 2
+ruby benchmark/sieve.rb 3
+echo
+JRUBY_OPTS="--1.9"
+echo `ruby -v`
+echo
+ruby benchmark/sieve.rb 0
+ruby benchmark/sieve.rb 1
+ruby benchmark/sieve.rb 2
+ruby benchmark/sieve.rb 3
+echo
+rvm use rbx-1.2.4
+echo
+echo `ruby -v`
+echo
+ruby benchmark/sieve.rb 0
+ruby benchmark/sieve.rb 1
+ruby benchmark/sieve.rb 2
+ruby benchmark/sieve.rb 3
+echo
+rvm use rbx-2.0.testing
+echo
+echo `ruby -v`
+echo
+ruby benchmark/sieve.rb 0
+ruby benchmark/sieve.rb 1
+ruby benchmark/sieve.rb 2
+ruby benchmark/sieve.rb 3

data/benchmark/sieve.rb

@@ -0,0 +1,238 @@
+require 'benchmark'
+project_lib_path = File.expand_path(File.join(File.dirname(__FILE__), "..", "lib"))
+$LOAD_PATH.unshift(project_lib_path)
+require 'agent'
+
+$size = (ARGV.pop || 0).to_i
+
+def generate(channels)
+  ch = channel!(Integer, $size)
+  channels << ch
+  go!{ i = 1; loop { ch << i+= 1} }
+
+  return ch
+end
+
+def filter(in_channel, prime, channels)
+  out = channel!(Integer, $size)
+  channels << out
+
+  go! do
+    loop do
+      i, _ = in_channel.receive
+      out << i if (i % prime) != 0
+    end
+  end
+
+  return out
+end
+
+def sieve(channels)
+  out = channel!(Integer, $size)
+  channels << out
+
+  go! do
+    ch = generate(channels)
+    loop do
+      prime, _ = ch.receive
+      out << prime
+      ch = filter(ch, prime, channels)
+    end
+  end
+
+  return out
+end
+
+################
+################
+
+nth_prime = 150
+concurrency = 5
+channels = []
+
+puts "#{nth_prime}'s prime, #{concurrency} goroutines, channel buffer size is #{$size}"
+
+Benchmark.bm(7) do |x|
+  x.report("receive") do
+    runners = []
+
+    concurrency.times do |n|
+      runners << go! do
+        primes = sieve(channels)
+        nth_prime.times { primes.receive }
+      end
+    end
+
+    runners.map {|t| t.join}
+  end
+end
+
+puts
+
+channels.each(&:close)
+
+__END__
+
+The setup:
+  13" Macbook Air
+  OSX Lion 10.7.3
+  1.8 GHz Intel Core i7
+  4 GB 1333 MHz DDR3
+  SSD
+  Terminal w/ OSX Lion's system ruby by default
+
+The command:
+  benchmark/multi_ruby_bench.sh
+
+The results:
+
+ruby 1.8.7 (2010-01-10 patchlevel 249) [universal-darwin11.0]
+
+150's prime, 5 goroutines, channel buffer size is 0
+             user     system      total        real
+receive 27.100000   0.290000  27.390000 ( 27.324909)
+
+150's prime, 5 goroutines, channel buffer size is 1
+             user     system      total        real
+receive 24.690000   0.280000  24.970000 ( 24.910035)
+
+150's prime, 5 goroutines, channel buffer size is 2
+             user     system      total        real
+receive 24.730000   0.280000  25.010000 ( 24.946830)
+
+150's prime, 5 goroutines, channel buffer size is 3
+             user     system      total        real
+receive 25.010000   0.290000  25.300000 ( 25.238002)
+
+
+ruby 1.8.7 (2012-02-08 patchlevel 358) [i686-darwin11.3.0]
+
+150's prime, 5 goroutines, channel buffer size is 0
+             user     system      total        real
+receive 17.890000   0.090000  17.980000 ( 17.984755)
+
+150's prime, 5 goroutines, channel buffer size is 1
+             user     system      total        real
+receive 17.030000   0.090000  17.120000 ( 17.131916)
+
+150's prime, 5 goroutines, channel buffer size is 2
+             user     system      total        real
+receive 17.060000   0.090000  17.150000 ( 17.168336)
+
+150's prime, 5 goroutines, channel buffer size is 3
+             user     system      total        real
+receive 17.090000   0.100000  17.190000 ( 17.187443)
+
+
+ruby 1.9.2p318 (2012-02-14 revision 34678) [x86_64-darwin11.3.0]
+
+150's prime, 5 goroutines, channel buffer size is 0
+             user     system      total        real
+receive  5.410000   2.360000   7.770000 (  7.241433)
+
+150's prime, 5 goroutines, channel buffer size is 1
+             user     system      total        real
+receive  5.270000   1.980000   7.250000 (  6.817536)
+
+150's prime, 5 goroutines, channel buffer size is 2
+             user     system      total        real
+receive  5.330000   2.030000   7.360000 (  6.918912)
+
+150's prime, 5 goroutines, channel buffer size is 3
+             user     system      total        real
+receive  5.340000   1.950000   7.290000 (  6.864300)
+
+
+ruby 1.9.3p125 (2012-02-16 revision 34643) [x86_64-darwin11.3.0]
+
+150's prime, 5 goroutines, channel buffer size is 0
+              user     system      total        real
+receive   6.470000   5.220000  11.690000 (  8.803085)
+
+150's prime, 5 goroutines, channel buffer size is 1
+              user     system      total        real
+receive   6.390000   4.190000  10.580000 (  8.248593)
+
+150's prime, 5 goroutines, channel buffer size is 2
+              user     system      total        real
+receive   6.240000   3.760000  10.000000 (  7.936199)
+
+150's prime, 5 goroutines, channel buffer size is 3
+              user     system      total        real
+receive   6.000000   3.200000   9.200000 (  7.461371)
+
+
+jruby 1.6.7 (ruby-1.8.7-p357) (2012-02-22 3e82bc8) (Java HotSpot(TM) 64-Bit Server VM 1.6.0_29) [darwin-x86_64-java]
+
+150's prime, 5 goroutines, channel buffer size is 0
+             user     system      total        real
+receive  9.672000   0.000000   9.672000 (  9.637000)
+
+150's prime, 5 goroutines, channel buffer size is 1
+             user     system      total        real
+receive 12.528000   0.000000  12.528000 ( 12.494000)
+
+150's prime, 5 goroutines, channel buffer size is 2
+             user     system      total        real
+receive 13.191000   0.000000  13.191000 ( 13.150000)
+
+150's prime, 5 goroutines, channel buffer size is 3
+             user     system      total        real
+receive 14.702000   0.000000  14.702000 ( 14.668000)
+
+
+jruby 1.6.7 (ruby-1.8.7-p357) (2012-02-22 3e82bc8) (Java HotSpot(TM) 64-Bit Server VM 1.6.0_29) [darwin-x86_64-java]
+
+150's prime, 5 goroutines, channel buffer size is 0
+             user     system      total        real
+receive  9.869000   0.000000   9.869000 (  9.836000)
+
+150's prime, 5 goroutines, channel buffer size is 1
+             user     system      total        real
+receive 12.399000   0.000000  12.399000 ( 12.362000)
+
+150's prime, 5 goroutines, channel buffer size is 2
+             user     system      total        real
+receive 13.146000   0.000000  13.146000 ( 13.154000)
+
+150's prime, 5 goroutines, channel buffer size is 3
+             user     system      total        real
+receive 13.888000   0.000000  13.888000 ( 13.847000)
+
+
+rubinius 1.2.4 (1.8.7 release 2011-07-05 JI) [x86_64-apple-darwin11.3.0]
+
+150's prime, 5 goroutines, channel buffer size is 0
+             user     system      total        real
+receive 20.890472   3.099183  23.989655 ( 19.765032)
+
+150's prime, 5 goroutines, channel buffer size is 1
+             user     system      total        real
+receive 21.727269   3.028753  24.756022 ( 20.554911)
+
+150's prime, 5 goroutines, channel buffer size is 2
+             user     system      total        real
+receive 45.912357   5.814811  51.727168 ( 44.636344)
+
+150's prime, 5 goroutines, channel buffer size is 3
+             user     system      total        real
+receive 46.211119   7.487593  53.698712 ( 44.716384)
+
+
+rubinius 2.0.0dev (1.8.7 65c6146e yyyy-mm-dd JI) [x86_64-apple-darwin11.3.0]
+
+150's prime, 5 goroutines, channel buffer size is 0
+             user     system      total        real
+receive 62.980970   4.578037  67.559007 ( 18.560938)
+
+150's prime, 5 goroutines, channel buffer size is 1
+             user     system      total        real
+receive 52.822284   4.667321  57.489605 ( 15.986046)
+
+150's prime, 5 goroutines, channel buffer size is 2
+             user     system      total        real
+receive 54.217875   4.579821  58.797696 ( 16.267339)
+
+150's prime, 5 goroutines, channel buffer size is 3
+             user     system      total        real
+receive 59.092219   4.881411  63.973630 ( 17.664269)