minx 0.1.0

data/.gitignore

@@ -0,0 +1,24 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+.yardoc
+doc
+minx.gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Daniel Schierbeck
+
+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,50 @@
+Minx
+====
+
+Massive and pervasive concurrency with Minx!
+
+Minx uses the powerful concurrency primitives outlined by Tony Hoare in his
+famous book "Communicating Sequential Processes".
+
+
+Usage
+-----
+
+Minx lets you easily create concurrent programs using the notion of *processes*
+and *channels*.
+
+    # Very contrived example...
+    chan = Minx.channel
+
+    Minx.spawn { chan.send("Hello, World!") }
+    Minx.spawn { puts chan.receive("Hello, World!") }
+
+These primitives, although simple, are incredibly powerful. When reading from
+or writing to a channel, a process yields execution -- and thus blocks until
+another process also participates in the communication. An example of when
+this would be useful is a simple network server:
+
+    # Create a channel for the incoming requests.
+    requests = Minx.channel
+
+    # Spawn 10 workers.
+    10.times do
+      Minx.spawn do
+        requests.each {|request| handle_request(request) }
+      end
+    end
+
+In the near future, evented IO will be implemented, allowing for highly
+performant network and file applications.
+
+
+Documentation
+-------------
+
+See [the full documentation](http://yardoc.org/docs/dasch-minx/file:README.md).
+
+
+Copyright
+---------
+
+Copyright (c) 2010 Daniel Schierbeck. See {file:LICENSE} for details.

data/Rakefile

@@ -0,0 +1,56 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "minx"
+    gem.summary = %Q{Massive and pervasive concurrency}
+    gem.description = %Q{An implementation of the CSP concurrency primitives}
+    gem.email = "daniel.schierbeck@gmail.com"
+    gem.homepage = "http://github.com/dasch/minx"
+    gem.authors = ["Daniel Schierbeck"]
+    gem.add_development_dependency "shoulda", ">= 0"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+begin
+  require 'yard'
+  require 'yard/rake/yardoc_task'
+  YARD::Rake::YardocTask.new do |t|
+    extra_files = %w(LICENSE)
+    t.files = ['lib/**/*.rb']
+    t.options = ["--files=#{extra_files.join(',')}"]
+  end
+rescue LoadError
+  task :yard do
+    abort "YARD is not available. In order to run yard, you must: sudo gem install yard"
+  end
+end

data/VERSION

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

data/benchmarks/ring.rb

@@ -0,0 +1,31 @@
+
+require 'benchmark'
+
+$:.unshift(File.dirname(__FILE__) + "/../lib/")
+
+require 'minx'
+
+
+# Number of processes.
+N = 10000
+
+# Number of rounds.
+M = 10
+
+channels = (0...N).map { Minx::Channel.new }
+processes = (0...N).each do |i|
+  Minx.spawn do
+    M.times do
+      value = channels[i].receive
+      channels[(i + 1) % N].send(value + 1)
+    end
+  end
+end
+
+Benchmark.bmbm do |bm|
+  bm.report("Sending a value #{M} times around a #{N}-length ring") do
+    Minx.spawn do
+      channels[0].send(0)
+    end
+  end
+end

data/lib/minx.rb

@@ -0,0 +1,73 @@
+
+require 'fiber'
+
+Minx = Module.new
+
+require 'minx/channel'
+require 'minx/process'
+
+module Minx
+  # Spawn a new process.
+  #
+  # @return [Process] a new process
+  def self.spawn(&block)
+    Process.new(&block).spawn
+  end
+
+  # Create a new channel.
+  #
+  # @return [Channel] a new channel
+  def self.channel
+    Channel.new
+  end
+
+  # Yield control to another process.
+  #
+  # The calling process will be resumed at a later point.
+  def self.yield(*args)
+    Fiber.yield(*args)
+  end
+
+  # Wait for the processes to yield execution.
+  #
+  # @return [nil]
+  def self.join(*processes)
+    processes.each do |process|
+      process.resume
+    end
+
+    return nil
+  end
+
+  # Select from a list of channels.
+  #
+  # The channels will be enumerated in order; the first one carrying a message
+  # will be picked, and the message will be returned.
+  #
+  # If none of the channels are readable, the calling process will yield until
+  # a channel is written to, unless <code>:skip => true</code> is passed as
+  # an option, in which case the call will just return +nil+.
+  #
+  # @example Non-blocking select
+  #   Minx.select(chan1, chan2, :skip => true)
+  #
+  # @param choices [Channel] the channels to be selected among
+  # @return the first message received from any of the channels
+  def self.select(*choices)
+    options = choices.last.is_a?(Hash) ? choices.pop : {}
+
+    # If a choice is readable, just receive from that one.
+    choices.each do |choice|
+      return choice.receive if choice.readable?
+    end
+
+    # Return immediately if :skip => true
+    return if options[:skip]
+
+    # ... otherwise, wait for a channel to become readable.
+    choices.each do |choice|
+      choice.receive(:async => true)
+    end
+    Minx.yield
+  end
+end

data/lib/minx/channel.rb

@@ -0,0 +1,74 @@
+
+module Minx
+  # A Channel is used to transmit messages between processes in a synchronized
+  # manner.
+  class Channel
+    def initialize
+      @readers = []
+      @writers = []
+    end
+
+    # Write a message to the channel.
+    #
+    # If no readers are waiting, the calling process will block until one comes
+    # along.
+    #
+    # @param message the message to be transmitted
+    # @return [nil]
+    def send(message)
+      if @readers.empty?
+        @writers << Fiber.current
+
+        # Yield control
+        Minx.yield
+
+        # Yield a message back to a reader.
+        Minx.yield(message)
+      else
+        @readers.shift.resume(message)
+      end
+
+      return nil
+    end
+
+    alias :<< :send
+
+    # Read a message off the channel.
+    #
+    # If no messages have been written to the channel, the calling process will
+    # block, only resuming when a write occurs. This behavior can be suppressed
+    # by calling +receive+ with <code>:async => true</code>, in which case the
+    # call will return immediately; the next time the calling process yields,
+    # it may be resumed with a message from the channel.
+    #
+    # @option options [Boolean] :async (false) whether or not to block
+    # @return a message
+    def receive(options = {})
+      if @writers.empty?
+        @readers << Fiber.current
+        Minx.yield unless options[:async]
+      else
+        @writers.shift.resume
+      end
+    end
+
+    # Enumerate over the messages sent to the channel.
+    #
+    # @example Iterating over channel messages
+    #   chan.each do |message|
+    #     puts "Got #{message}!"
+    #   end
+    #
+    # @yield [message]
+    def each
+      yield receive while true
+    end
+
+    # Returns whether there are any processes waiting to write.
+    #
+    # @return +true+ if you can receive a message from the channel
+    def readable?
+      return !@writers.empty?
+    end
+  end
+end

data/lib/minx/process.rb

@@ -0,0 +1,24 @@
+
+module Minx
+  class Process
+    def initialize(&block)
+      raise ArgumentError unless block_given?
+      @fiber = Fiber.new { block.call }
+    end
+
+    # Spawn the process.
+    #
+    # The process will immediately take over execution, and the current
+    # fiber will yield.
+    def spawn
+      @fiber.resume
+    end
+
+    # Resume the process.
+    #
+    # This yields execution to the process.
+    def resume
+      @fiber.resume
+    end
+  end
+end

data/test/channel_test.rb

@@ -0,0 +1,50 @@
+require 'helper'
+
+class ChannelTest < Test::Unit::TestCase
+  context "A Channel" do
+    setup do
+      @channel = Minx.channel
+      @data = []
+      @p1 = Minx::Process.new { @channel.send(:foo) }
+      @p2 = Minx::Process.new { @data << @channel.receive }
+    end
+
+    context "with first a reader, then a writer" do
+      setup do
+        @p2.spawn
+        @p1.spawn
+      end
+
+      should "be able to transmit a message" do
+        assert_equal :foo, @data.first
+      end
+    end
+
+    context "with first a writer, then a reader" do
+      setup do
+        @p1.spawn
+        @p2.spawn
+      end
+
+      should "be able to transmit a message" do
+        assert_equal :foo, @data.first
+      end
+    end
+
+    should "send a message with #<<" do
+      Minx.spawn { @channel << :bar }
+      assert_equal :bar, @channel.receive
+    end
+
+    should "iterate over messages on #each" do
+      Minx.spawn { [:foo, :bar, :baz].each {|msg| @channel.send(msg) } }
+
+      values = [:foo, :bar, :baz]
+      Minx.spawn do
+        @channel.each do |message|
+          assert_equal values.shift, message
+        end
+      end
+    end
+  end
+end

data/test/choice_test.rb

@@ -0,0 +1,69 @@
+
+require 'helper'
+
+class ChoiceTest < Test::Unit::TestCase
+  context "A simple choice between two channels" do
+    setup do
+      @chan1 = Minx.channel
+      @chan2 = Minx.channel
+    end
+
+    context "with a single writer" do
+      setup do
+        Minx.spawn { @chan2.send(42) }
+      end
+
+      should "receive from the channel with a writer" do
+        Minx.spawn do
+          assert_equal 42, Minx.select(@chan1, @chan2)
+        end
+      end
+    end
+
+    context "with writers on both channels" do
+      setup do
+        Minx.spawn { @chan1.send(666) }
+        Minx.spawn { @chan2.send(42) }
+      end
+
+      should "receive from the first channel specified" do
+        Minx.spawn do
+          assert_equal 666, Minx.select(@chan1, @chan2)
+        end
+      end
+
+      should "not receive from the second channel specified" do
+        Minx.spawn do
+          Minx.select(@chan1, @chan2)
+          assert_equal 42, @chan2.receive
+        end
+      end
+    end
+
+    context "with no writers" do
+      setup do
+        Minx.spawn { @value = Minx.select(@chan1, @chan2) }
+      end
+
+      should "block until a writer comes along" do
+        Minx.spawn { @chan1.send(42) }
+        assert_equal 42, @value
+      end
+
+      should "also block until the second channel gets written to" do
+        Minx.spawn { @chan2.send(666) }
+        assert_equal 666, @value
+      end
+    end
+
+    context "with :skip => true" do
+      setup do
+        Minx.spawn { @value = Minx.select(@chan1, @chan2, :skip => true) }
+      end
+
+      should "not block" do
+        assert_nil @value
+      end
+    end
+  end
+end

data/test/helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'minx'
+
+class Test::Unit::TestCase
+end

data/test/process_test.rb

@@ -0,0 +1,41 @@
+require 'helper'
+
+class ProcessTest < Test::Unit::TestCase
+  should "Raise ArgumentError if no block is given" do
+    assert_raise(ArgumentError) { Minx::Process.new }
+  end
+
+  context "A Minx process" do
+    setup do
+      @data = ""
+      @process = Minx::Process.new {  @data.replace("foo") }
+    end
+
+    should "not execute initially" do
+      assert_equal "", @data
+    end
+
+    should "execute on #spawn" do
+      @process.spawn
+
+      assert_equal "foo", @data
+    end
+  end
+
+  context "A Minx process that yields initially" do
+    setup do
+      @process = Minx::Process.new { Minx.yield; @value = 42 }
+    end
+
+    should "be rescheduled and resumed" do
+      Minx.spawn do
+        @process.spawn
+        Minx.yield
+      end
+
+      Minx.join(@process)
+
+      assert_equal 42, @value
+    end
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification 
+name: minx
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Daniel Schierbeck
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-02-07 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: An implementation of the CSP concurrency primitives
+email: daniel.schierbeck@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.md
+files: 
+- .gitignore
+- LICENSE
+- README.md
+- Rakefile
+- VERSION
+- benchmarks/ring.rb
+- lib/minx.rb
+- lib/minx/channel.rb
+- lib/minx/process.rb
+- test/channel_test.rb
+- test/choice_test.rb
+- test/helper.rb
+- test/process_test.rb
+has_rdoc: true
+homepage: http://github.com/dasch/minx
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Massive and pervasive concurrency
+test_files: 
+- test/choice_test.rb
+- test/channel_test.rb
+- test/helper.rb
+- test/process_test.rb