concurrent-ruby 0.3.0.pre.1 → 0.3.0.pre.2

data/lib/concurrent/utilities.rb

@@ -0,0 +1,24 @@
+require 'thread'
+
+module Concurrent
+
+  TimeoutError = Class.new(StandardError)
+
+  def timeout(seconds)
+
+    thread = Thread.new do
+      Thread.current[:result] = yield
+    end
+    success = thread.join(seconds)
+
+    if success
+      return thread[:result]
+    else
+      raise TimeoutError
+    end
+  ensure
+    Thread.kill(thread) unless thread.nil?
+  end
+  module_function :timeout
+
+end

data/lib/concurrent/version.rb

@@ -1,3 +1,3 @@
 module Concurrent
-  VERSION = '0.3.0.pre.1'
+  VERSION = '0.3.0.pre.2'
 end

data/md/agent.md

@@ -42,7 +42,7 @@ score.value #=> 110
 
 score << proc{|current| current * 2 }
 sleep(0.1)
-deref score #=> 220
+score.value #=> 220
 
 score << proc{|current| current - 50 }
 sleep(0.1)
@@ -52,7 +52,7 @@ score.value #=> 170
 With validation and error handling:
 
 ```ruby
-score = agent(0).validate{|value| value <= 1024 }.
+score = Concurrent::Agent.new(0).validate{|value| value <= 1024 }.
           rescue(NoMethodError){|ex| puts "Bam!" }.
           rescue(ArgumentError){|ex| puts "Pow!" }.
           rescue{|ex| puts "Boom!" }
@@ -81,7 +81,7 @@ bingo = Class.new{
   end
 }.new
 
-score = agent(0)
+score = Concurrent::Agent.new(0)
 score.add_observer(bingo)
 
 score << proc{|current| sleep(0.1); current += 30 }

data/md/future.md

@@ -38,18 +38,18 @@ count.value(0) #=> nil (does not block)
 count.value #=> 10 (after blocking)
 count.state #=> :fulfilled
 count.fulfilled? #=> true
-deref count #=> 10
+count.value #=> 10
 ```
 
 A rejected example:
 
 ```ruby
-count = future{ sleep(10); raise StandardError.new("Boom!") }
+count = Concurrent::Future.new{ sleep(10); raise StandardError.new("Boom!") }
 count.state #=> :pending
-pending?(count) #=> true
+count.pending? #=> true
 
 deref(count) #=> nil (after blocking)
-rejected?(count) #=> true
+count.rejected? #=> true
 count.reason #=> #<StandardError: Boom!> 
 ```
 

data/md/promise.md

@@ -44,10 +44,6 @@ Then create one
 p = Promise.new("Jerry", "D'Antonio") do |first, last|
       "#{last}, #{first}"
     end
-
-# -or-
-
-p = promise(10){|x| x * x * x }
 ```
 
 Promises can be chained using the `then` method. The `then` method
@@ -55,13 +51,13 @@ accepts a block but no arguments. The result of the each promise is
 passed as the block argument to chained promises
 
 ```ruby
-p = promise(10){|x| x * 2}.then{|result| result - 10 }
+p = Concurrent::Promise.new(10){|x| x * 2}.then{|result| result - 10 }
 ```
 
 And so on, and so on, and so on...
 
 ```ruby
-p = promise(10){|x| x * 2}.
+p = Concurrent::Promise.new(10){|x| x * 2}.
     then{|result| result - 10 }.
     then{|result| result * 3 }.
     then{|result| result % 5 }
@@ -69,9 +65,8 @@ p = promise(10){|x| x * 2}.
 
 Promises are executed asynchronously so a newly-created promise *should* always be in the pending state
 
-
 ```ruby
-p = promise{ "Hello, world!" }
+p = Concurrent::Promise.new{ "Hello, world!" }
 p.state   #=> :pending
 p.pending? #=> true
 ```
@@ -79,27 +74,24 @@ p.pending? #=> true
 Wait a little bit, and the promise will resolve and provide a value
 
 ```ruby
-p = promise{ "Hello, world!" }
+p = Concurrent::Promise.new{ "Hello, world!" }
 sleep(0.1)
 
 p.state      #=> :fulfilled
 p.fulfilled? #=> true
-
 p.value      #=> "Hello, world!"
-
 ```
 
 If an exception occurs, the promise will be rejected and will provide
 a reason for the rejection
 
 ```ruby
-p = promise{ raise StandardError.new("Here comes the Boom!") }
+p = Concurrent::Promise.new{ raise StandardError.new("Here comes the Boom!") }
 sleep(0.1)
 
 p.state     #=> :rejected
 p.rejected? #=> true
-
-p.reason=>  #=> "#<StandardError: Here comes the Boom!>"
+p.reason    #=> "#<StandardError: Here comes the Boom!>"
 ```
 
 ### Rejection
@@ -108,7 +100,7 @@ Much like the economy, rejection exhibits a trickle-down effect. When
 a promise is rejected all its children will be rejected
 
 ```ruby
-p = [ promise{ Thread.pass; raise StandardError } ]
+p = [ Concurrent::Promise.new{ Thread.pass; raise StandardError } ]
 
 10.times{|i| p << p.first.then{ i } }
 sleep(0.1)
@@ -122,7 +114,7 @@ Once a promise is rejected it will not accept any children. Calls
 to `then` will continually return `self`
 
 ```ruby
-p = promise{ raise StandardError }
+p = Concurrent::Promise.new{ raise StandardError }
 sleep(0.1)
 
 p.object_id        #=> 32960556
@@ -135,30 +127,28 @@ p.then{}.object_id #=> 32960556
 Promises support error handling callbacks is a style mimicing Ruby's
 own exception handling mechanism, namely `rescue`
 
-
 ```ruby
-promise{ "dangerous operation..." }.rescue{|ex| puts "Bam!" }
+Concurrent::Promise.new{ "dangerous operation..." }.rescue{|ex| puts "Bam!" }
 
 # -or- (for the Java/C# crowd)
-promise{ "dangerous operation..." }.catch{|ex| puts "Boom!" }
+Concurrent::Promise.new{ "dangerous operation..." }.catch{|ex| puts "Boom!" }
 
 # -or- (for the hipsters)
-promise{ "dangerous operation..." }.on_error{|ex| puts "Pow!" }
+Concurrent::Promise.new{ "dangerous operation..." }.on_error{|ex| puts "Pow!" }
 ```
 
 As with Ruby's `rescue` mechanism, a promise's `rescue` method can
 accept an optional Exception class argument (defaults to `Exception`
 when not specified)
 
-
 ```ruby
-promise{ "dangerous operation..." }.rescue(ArgumentError){|ex| puts "Bam!" }
+Concurrent::Promise.new{ "dangerous operation..." }.rescue(ArgumentError){|ex| puts "Bam!" }
 ```
 
 Calls to `rescue` can also be chained
 
 ```ruby
-promise{ "dangerous operation..." }.
+Concurrent::Promise.new{ "dangerous operation..." }.
   rescue(ArgumentError){|ex| puts "Bam!" }.
   rescue(NoMethodError){|ex| puts "Boom!" }.
   rescue(StandardError){|ex| puts "Pow!" }
@@ -168,7 +158,7 @@ When there are multiple `rescue` handlers the first one to match the thrown
 exception will be triggered
 
 ```ruby
-promise{ raise NoMethodError }.
+Concurrent::Promise.new{ raise NoMethodError }.
   rescue(ArgumentError){|ex| puts "Bam!" }.
   rescue(NoMethodError){|ex| puts "Boom!" }.
   rescue(StandardError){|ex| puts "Pow!" }
@@ -182,7 +172,7 @@ Trickle-down rejection also applies to rescue handlers. When a promise is reject
 for any reason, its rescue handlers will be triggered. Rejection of the parent counts.
 
 ```ruby
-promise{ Thread.pass; raise StandardError }.
+Concurrent::Promise.new{ Thread.pass; raise StandardError }.
   then{ true }.rescue{ puts 'Boom!' }.
   then{ true }.rescue{ puts 'Boom!' }.
   then{ true }.rescue{ puts 'Boom!' }.

data/md/thread_pool.md

@@ -87,9 +87,7 @@ From the docs:
 ### Examples
 
 ```ruby
-require 'functional/cached_thread_pool'
-# or
-require 'functional/concurrency'
+require 'concurrent'
 
 pool = Concurrent::CachedThreadPool.new
 
@@ -125,8 +123,11 @@ goroutines) run against a global thread pool. This pool can be directly accessed
 `$GLOBAL_THREAD_POOL` global variable. Generally, this pool should not be directly accessed.
 Use the other concurrency features instead.
 
-By default the global thread pool is a `CachedThreadPool`. This means it consumes no resources
-unless concurrency functions are called. Most of the time this pool can simply be left alone.
+By default the global thread pool is a `NullThreadPool`. This isn't a real thread pool at all.
+It's simply a proxy for creating new threads on every post to the pool. I couldn't decide which
+of the other threads pools and what configuration would be the most universally appropriate so
+I punted. If you understand thread pools then you know enough to make your own choice. That's
+why the global thread pool can be changed.
 
 ### Changing the Global Thread Pool
 
@@ -162,13 +163,13 @@ it is not an actual thread pool. Instead it spawns a new thread on every call to
 The [EventMachine](http://rubyeventmachine.com/) library (source [online](https://github.com/eventmachine/eventmachine))
 is an awesome library for creating evented applications. EventMachine provides its own thread pool
 and the authors recommend using their pool rather than using Ruby's `Thread`. No sweat,
-`functional-ruby` is fully compatible with EventMachine. Simple require `eventmachine`
-*before* requiring `functional-ruby` then replace the global thread pool with an instance
+`concurrent-ruby` is fully compatible with EventMachine. Simple require `eventmachine`
+*before* requiring `concurrent-ruby` then replace the global thread pool with an instance
 of `EventMachineDeferProxy`:
 
 ```ruby
 require 'eventmachine' # do this FIRST
-require 'functional/concurrency'
+require 'concurrent'
 
 $GLOBAL_THREAD_POOL = EventMachineDeferProxy.new
 ```

data/spec/concurrent/actor_spec.rb

@@ -0,0 +1,377 @@
+require 'spec_helper'
+require_relative 'runnable_shared'
+
+module Concurrent
+
+  describe Actor do
+
+    let(:actor_class) do
+      Class.new(Actor) do
+        attr_reader :last_message
+        def initialize(&block)
+          @task = block
+          super()
+        end
+        def act(*message)
+          @last_message = message
+          @task.call(*message) unless @task.nil?
+        end
+      end
+    end
+
+    subject { Class.new(actor_class).new }
+
+    it_should_behave_like :runnable
+
+    after(:each) do
+      subject.stop
+      @thread.kill unless @thread.nil?
+      sleep(0.1)
+    end
+
+    context '#post' do
+
+      it 'returns false when not running' do
+        subject.post.should be_false
+      end
+
+      it 'pushes a message onto the queue' do
+        @expected = false
+        actor = actor_class.new{|msg| @expected = msg }
+        @thread = Thread.new{ actor.run }
+        @thread.join(0.1)
+        actor.post(true)
+        @thread.join(0.1)
+        @expected.should be_true
+        actor.stop
+      end
+
+      it 'returns the current size of the queue' do
+        actor = actor_class.new{|msg| sleep }
+        @thread = Thread.new{ actor.run }
+        @thread.join(0.1)
+        actor.post(true).should == 1
+        @thread.join(0.1)
+        actor.post(true).should == 1
+        @thread.join(0.1)
+        actor.post(true).should == 2
+        actor.stop
+      end
+
+      it 'is aliased a <<' do
+        @expected = false
+        actor = actor_class.new{|msg| @expected = msg }
+        @thread = Thread.new{ actor.run }
+        @thread.join(0.1)
+        actor << true
+        @thread.join(0.1)
+        @expected.should be_true
+        actor.stop
+      end
+    end
+
+    context '#run' do
+
+      it 'empties the queue' do
+        @thread = Thread.new{ subject.run }
+        @thread.join(0.1)
+        q = subject.instance_variable_get(:@queue)
+        q.size.should == 0
+      end
+    end
+
+    context '#stop' do
+
+      it 'empties the queue' do
+        actor = actor_class.new{|msg| sleep }
+        @thread = Thread.new{ actor.run }
+        10.times { actor.post(true) }
+        @thread.join(0.1)
+        actor.stop
+        @thread.join(0.1)
+        q = actor.instance_variable_get(:@queue)
+        if q.size >= 1
+          q.pop.should == :stop
+        else
+          q.size.should == 0
+        end
+      end
+
+      it 'pushes a :stop message onto the queue' do
+        @thread = Thread.new{ subject.run }
+        @thread.join(0.1)
+        q = subject.instance_variable_get(:@queue)
+        q.should_receive(:push).once.with(:stop)
+        subject.stop
+        @thread.join(0.1)
+      end
+    end
+
+    context 'message handling' do
+
+      it 'runs the constructor block once for every message' do
+        @expected = 0
+        actor = actor_class.new{|msg| @expected += 1 }
+        @thread = Thread.new{ actor.run }
+        @thread.join(0.1)
+        10.times { actor.post(true) }
+        @thread.join(0.1)
+        @expected.should eq 10
+        actor.stop
+      end
+
+      it 'passes the message to the block' do
+        @expected = []
+        actor = actor_class.new{|msg| @expected << msg }
+        @thread = Thread.new{ actor.run }
+        @thread.join(0.1)
+        10.times {|i| actor.post(i) }
+        @thread.join(0.1)
+        actor.stop
+        @expected.should eq (0..9).to_a
+      end
+    end
+
+    context 'exception handling' do
+
+      it 'supresses exceptions thrown when handling messages' do
+        actor = actor_class.new{|msg| raise StandardError }
+        @thread = Thread.new{ actor.run }
+        expect {
+          @thread.join(0.1)
+          10.times { actor.post(true) }
+        }.not_to raise_error
+        actor.stop
+      end
+    end
+
+    context 'observer notification' do
+
+      let(:observer) do
+        Class.new {
+          attr_reader :notice
+          def update(*args) @notice = args; end
+        }.new
+      end
+
+      it 'notifies observers when a message is successfully handled' do
+        observer.should_receive(:update).exactly(10).times.with(any_args())
+        subject.add_observer(observer)
+        @thread = Thread.new{ subject.run }
+        @thread.join(0.1)
+        10.times { subject.post(true) }
+        @thread.join(0.1)
+      end
+
+      it 'does not notify observers when a message raises an exception' do
+        observer.should_not_receive(:update).with(any_args())
+        actor = actor_class.new{|msg| raise StandardError }
+        actor.add_observer(observer)
+        @thread = Thread.new{ actor.run }
+        @thread.join(0.1)
+        10.times { actor.post(true) }
+        @thread.join(0.1)
+        actor.stop
+      end
+
+      it 'passes the time, message, and result to the observer' do
+        actor = actor_class.new{|*msg| msg }
+        actor.add_observer(observer)
+        @thread = Thread.new{ actor.run }
+        @thread.join(0.1)
+        actor.post(42)
+        @thread.join(0.1)
+        observer.notice[0].should be_a(Time)
+        observer.notice[1].should == [42]
+        observer.notice[2].should == [42]
+        actor.stop
+      end
+    end
+
+    context '#pool' do
+
+      let(:clazz){ Class.new(actor_class) }
+
+      it 'raises an exception if the count is zero or less' do
+        expect {
+          clazz.pool(0)
+        }.to raise_error(ArgumentError)
+      end
+  
+      it 'creates the requested number of actors' do
+        mailbox, actors = clazz.pool(5)
+        actors.size.should == 5
+      end
+
+      it 'passes the block to each actor' do
+        block = proc{ nil }
+        clazz.should_receive(:new).with(&block)
+        clazz.pool(1, &block)
+      end
+
+      it 'gives all actors the same mailbox' do
+        mailbox, actors = clazz.pool(2)
+        mbox1 = actors.first.instance_variable_get(:@queue)
+        mbox2 = actors.last.instance_variable_get(:@queue)
+        mbox1.should eq mbox2
+      end
+
+      it 'returns a Poolbox as the first retval' do
+        mailbox, actors = clazz.pool(2)
+        mailbox.should be_a(Actor::Poolbox)
+      end
+
+      it 'gives the Poolbox the same mailbox as the actors' do
+        mailbox, actors = clazz.pool(1)
+        mbox1 = mailbox.instance_variable_get(:@queue)
+        mbox2 = actors.first.instance_variable_get(:@queue)
+        mbox1.should eq mbox2
+      end
+
+      it 'returns an array of actors as the second retval' do
+        mailbox, actors = clazz.pool(2)
+        actors.each do |actor|
+          actor.should be_a(clazz)
+        end
+      end
+
+      it 'posts to the mailbox with Poolbox#post' do
+        @expected = false
+        mailbox, actors = clazz.pool(1){|msg| @expected = true }
+        @thread = Thread.new{ actors.first.run }
+        sleep(0.1)
+        mailbox.post(42)
+        sleep(0.1)
+        actors.each{|actor| actor.stop }
+        @thread.kill
+        @expected.should be_true
+      end
+
+      it 'posts to the mailbox with Poolbox#<<' do
+        @expected = false
+        mailbox, actors = clazz.pool(1){|msg| @expected = true }
+        @thread = Thread.new{ actors.first.run }
+        sleep(0.1)
+        mailbox << 42
+        sleep(0.1)
+        actors.each{|actor| actor.stop }
+        @thread.kill
+        @expected.should be_true
+      end
+    end
+
+    context 'subclassing' do
+
+      after(:each) do
+        @thread.kill unless @thread.nil?
+      end
+
+      context '#pool' do
+
+        it 'creates actors of the appropriate subclass' do
+          actor = Class.new(actor_class)
+          mailbox, actors = actor.pool(1)
+          actors.first.should be_a(actor)
+        end
+      end
+
+      context '#act overloading' do
+
+        it 'raises an exception if #act is not implemented in the subclass' do
+          actor = Class.new(Actor).new
+          @thread = Thread.new{ actor.run }
+          @thread.join(0.1)
+          expect {
+            actor.post(:foo)
+            @thread.join(0.1)
+          }.to raise_error(NotImplementedError)
+          actor.stop
+        end
+
+        it 'uses the subclass #act implementation' do
+          actor = actor_class.new{|*args| @expected = true }
+          @thread = Thread.new{ actor.run }
+          @thread.join(0.1)
+          actor.post(:foo)
+          @thread.join(0.1)
+          actor.last_message.should eq [:foo]
+          actor.stop
+        end
+      end
+
+      context '#on_error overloading' do
+
+        let(:bad_actor) do
+          Class.new(actor_class) {
+            attr_reader :last_error
+            def act(*message)
+              raise StandardError
+            end
+            def on_error(*args)
+              @last_error = args
+            end
+          }
+        end
+
+        it 'uses the subclass #on_error implementation' do
+          actor = bad_actor.new
+          @thread = Thread.new{ actor.run }
+          @thread.join(0.1)
+          actor.post(42)
+          @thread.join(0.1)
+          actor.last_error[0].should be_a(Time)
+          actor.last_error[1].should eq [42]
+          actor.last_error[2].should be_a(StandardError)
+          actor.stop
+        end
+      end
+    end
+
+    context 'supervision' do
+
+      it 'can be started by a Supervisor' do
+        actor = actor_class.new
+        supervisor = Supervisor.new
+        supervisor.add_worker(actor)
+        
+        actor.should_receive(:run).with(no_args())
+        supervisor.run!
+        sleep(0.1)
+
+        supervisor.stop
+        sleep(0.1)
+        actor.stop
+      end
+
+      it 'can receive messages while under supervision' do
+        @expected = false
+        actor = actor_class.new{|*args| @expected = true}
+        supervisor = Supervisor.new
+        supervisor.add_worker(actor)
+        supervisor.run!
+        sleep(0.1)
+
+        actor.post(42)
+        sleep(0.1)
+        @expected.should be_true
+
+        supervisor.stop
+        sleep(0.1)
+        actor.stop
+      end
+
+      it 'can be stopped by a supervisor' do
+        actor = actor_class.new
+        supervisor = Supervisor.new
+        supervisor.add_worker(actor)
+        
+        supervisor.run!
+        sleep(0.1)
+
+        actor.should_receive(:stop).with(no_args())
+        supervisor.stop
+        sleep(0.1)
+      end
+    end
+  end
+end