concurrent-ruby 0.3.2 → 0.4.0

data/lib/concurrent/utilities.rb

@@ -2,8 +2,20 @@ require 'thread'
 
 module Concurrent
 
+  # Error raised when an operations times out.
   TimeoutError = Class.new(StandardError)
 
+  # Wait the given number of seconds for the block operation to complete.
+  #
+  # @param [Integer] seconds The number of seconds to wait
+  #
+  # @return The result of the block operation
+  #
+  # @raise Concurrent::TimeoutError when the block operation does not complete
+  #   in the allotted number of seconds.
+  #
+  # @note This method is intended to be a simpler and more reliable replacement
+  # to the Ruby standard library `Timeout::timeout` method.
   def timeout(seconds)
 
     thread = Thread.new do
@@ -20,5 +32,4 @@ module Concurrent
     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.2'
+  VERSION = '0.4.0'
 end

data/md/actor.md

@@ -29,7 +29,7 @@ Actors are defined by subclassing the `Concurrent::Actor` class and overriding t
 `#act` method. The `#act` method can have any signature/arity but
 
 ```ruby
-def act(*args, &block)
+def act(*args)
 ```
 
 is the most flexible and least error-prone signature. The `#act` method is called in
@@ -146,7 +146,7 @@ to confusion and difficult debugging.
 ### Observation
 
 The `Actor` superclass mixes in the Ruby standard library
-[Observable](http://ruby-doc.org/stdlib-1.9.3/libdoc/observer/rdoc/Observable.html)
+[Observable](http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html)
 module to provide consistent callbacks upon message processing completion. The normal
 `Observable` methods, including `#add_observer` behave normally. Once an observer
 is added to an `Actor` it will be notified of all messages processed *after*

data/md/agent.md

@@ -22,7 +22,7 @@ seacrhed in order until one matching the current exception is found. That `rescu
 then be called an passed the exception object. If no matching `rescue` block is found, or none
 were configured, then the exception will be suppressed.
 
-`Agent`s also implement Ruby's [Observable](http://ruby-doc.org/stdlib-1.9.3/libdoc/observer/rdoc/Observable.html).
+`Agent`s also implement Ruby's [Observable](http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html).
 Code that observes an `Agent` will receive a callback with the new value any time the value
 is changed.
 

data/md/channel.md

@@ -0,0 +1,40 @@
+# Change the dang channel!
+
+`Channel` is a functional programming variation of `Actor`, based very loosely on the
+[MailboxProcessor](http://blogs.msdn.com/b/dsyme/archive/2010/02/15/async-and-parallel-design-patterns-in-f-part-3-agents.aspx)
+agent in [F#](http://msdn.microsoft.com/en-us/library/ee370357.aspx).
+The `Actor` is used to create objects that receive messages from other
+threads then processes those messages based on the behavior of the class. `Channel`
+creates objects that receive messages and processe them using the block given
+at construction. `Channel` is implemented as a subclass of
+[Actor](https://github.com/jdantonio/concurrent-ruby/blob/master/md/actor.md)
+and supports all message-passing methods of that class. `Channel` also supports pools 
+with a shared mailbox.
+
+See the [Actor](https://github.com/jdantonio/concurrent-ruby/blob/master/md/actor.md)
+documentation for more detail.
+
+## Usage
+
+```ruby
+require 'concurrent'
+
+channel = Concurrent::Channel.new do |msg|
+  sleep(1)
+  puts "#{msg}\n"
+end
+
+channel.run! => #<Thread:0x007fa123d95fc8 sleep>
+
+channel.post("Hello, World!") => 1
+# wait...
+=> Hello, World!
+
+future = channel.post? "Don't Panic." => #<Concurrent::Contract:0x007fa123d6d9d8 @state=:pending...
+future.pending? => true
+# wait...
+=> "Don't Panic."
+future.fulfilled? => true
+
+channel.stop => true
+```

data/md/dereferenceable.md

@@ -2,18 +2,16 @@
 
 Object references in Ruby are mutable. This can lead to serious problems when
 the `#value` of a concurrent object is a mutable reference. Which is always the
-case unless the value is a `Fixnum`, `Symbol`, or similar "primative" data type.
+case unless the value is a `Fixnum`, `Symbol`, or similar "primitive" data type.
 Most classes in this library that expose a `#value` getter method do so using
-the Dereferenceable mixin module.
+the `Dereferenceable` mixin module.
 
+Objects with this mixin can be configured with a few options that can help protect
+the program from potentially dangerous operations.
 
-Each `Agent` instance can be configured with a few options that can help protect the
-program from potentially dangerous operations. Each of these options can be
-optionally set when the `Agent` is created:
-
-* `:dup_on_deref` when true the `Agent` will call the `#dup` method on the
-  `value` object every time the `#value` methid is called (default: false)
-* `:freeze_on_deref` when true the `Agent` will call the `#freeze` method on the
+* `:dup_on_deref` when true  will call the `#dup` method on the
+  `value` object every time the `#value` method is called (default: false)
+* `:freeze_on_deref` when true  will call the `#freeze` method on the
   `value` object every time the `#value` method is called (default: false)
 * `:copy_on_deref` when given a `Proc` object the `Proc` will be run every time
   the `#value` method is called. The `Proc` will be given the current `value` as

data/md/future.md

@@ -22,7 +22,7 @@ block indefinitely. If `0` the call will not block. Any other integer or float v
 maximum number of seconds to block.
 
 The `Future` class also includes the Ruby standard library
-[Observable](http://ruby-doc.org/stdlib-1.9.3/libdoc/observer/rdoc/Observable.html) module. On fulfillment
+[Observable](http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html) module. On fulfillment
 or rejection all observers will be notified according to the normal `Observable` behavior. The observer
 callback function will be called with three parameters: the `Time` of fulfillment/rejection, the
 final `value`, and the final `reason`. Observers added after fulfillment/rejection will still be
@@ -35,7 +35,7 @@ A fulfilled example:
 ```ruby
 require 'concurrent'
 
-count = Concurrent::Future{ sleep(10); 10 }
+count = Concurrent::Future.new{ sleep(10); 10 }
 count.state #=> :pending
 count.pending? #=> true
 

data/md/promise.md

@@ -15,7 +15,7 @@ upon resolution. When a promise is rejected all its children will be summarily r
 
 Promises have three possible states: *pending*, *rejected*, and *fulfilled*. When a promise is created it is set
 to *pending* and will remain in that state until processing is complete. A completed promise is either *rejected*,
-indicating that an exception was thrown during processing, or *fulfilled*, indicating succedd. If a promise is
+indicating that an exception was thrown during processing, or *fulfilled*, indicating it succeeded. If a promise is
 *fulfilled* its `value` will be updated to reflect the result of the operation. If *rejected* the `reason` will
 be updated with a reference to the thrown exception. The predicate methods `pending?`, `rejected`, and `fulfilled?`
 can be called at any time to obtain the state of the promise, as can the `state` method, which returns a symbol.

data/md/scheduled_task.md

@@ -45,7 +45,7 @@ The result of a `ScheduledTask` can be obtained either synchronously or asynchro
 `ScheduledTask` mixes in both the
 [Obligation](https://github.com/jdantonio/concurrent-ruby/blob/master/md/obligation.md)
 module and the
-[Observable](http://ruby-doc.org/stdlib-1.9.3/libdoc/observer/rdoc/Observable.html)
+[Observable](http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html)
 module from the Ruby standard library. With one exception `ScheduledTask` behaves
 identically to
 [Concurrent::Future](https://github.com/jdantonio/concurrent-ruby/blob/master/md/future.md)

data/md/timer_task.md

@@ -31,7 +31,7 @@ This class is based on the Java class
 ## Observation
 
 `TimerTask` supports notification through the Ruby standard library
-[Observable](http://ruby-doc.org/stdlib-1.9.3/libdoc/observer/rdoc/Observable.html)
+[Observable](http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html)
 module. On execution the `TimerTask` will notify the observers with thress arguments:
 time of execution, the result of the block (or nil on failure), and any raised
 exceptions (or nil on success). If the timeout interval is exceeded the observer

data/spec/concurrent/actor_spec.rb

@@ -1,4 +1,5 @@
 require 'spec_helper'
+require_relative 'postable_shared'
 require_relative 'runnable_shared'
 
 module Concurrent
@@ -19,242 +20,30 @@ module Concurrent
       end
     end
 
+    ## :runnable
     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
+    ## :postable
 
-      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
+    let!(:postable_class){ actor_class }
 
-      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 '#post?' do
-
-      it 'returns nil when not running' do
-        subject.post?.should be_false
-      end
-
-      it 'returns an Obligation' do
-        actor = actor_class.new
-        @thread = Thread.new{ actor.run }
-        @thread.join(0.1)
-        obligation = actor.post?(nil)
-        obligation.should be_a(Obligation)
-        actor.stop
-      end
-
-      it 'fulfills the obligation on success' do
-        actor = actor_class.new{|msg| @expected = msg }
-        @thread = Thread.new{ actor.run }
-        @thread.join(0.1)
-        obligation = actor.post?(42)
-        @thread.join(0.1)
-        obligation.should be_fulfilled
-        obligation.value.should == 42
-        actor.stop
-      end
-
-      it 'rejects the obligation on failure' do
-        actor = actor_class.new{|msg| raise StandardError.new('Boom!') }
-        @thread = Thread.new{ actor.run }
-        @thread.join(0.1)
-        obligation = actor.post?(42)
-        @thread.join(0.1)
-        obligation.should be_rejected
-        obligation.reason.should be_a(StandardError)
-        actor.stop
-      end
-    end
-
-    context '#post!' do
-
-      it 'raises Concurrent::Runnable::LifecycleError when not running' do
-        expect {
-          subject.post!(1)
-        }.to raise_error(Concurrent::Runnable::LifecycleError)
-      end
-
-      it 'blocks for up to the given number of seconds' do
-        actor = actor_class.new{|msg| sleep }
-        @thread = Thread.new{ actor.run }
-        @thread.join(0.1)
-        start = Time.now.to_i
-        expect {
-          actor.post!(2, nil)
-        }.to raise_error
-        elapsed = Time.now.to_i - start
-        elapsed.should >= 2
-        actor.stop
-      end
-
-      it 'raises Concurrent::TimeoutError when seconds is zero' do
-        actor = actor_class.new{|msg| 42 }
-        @thread = Thread.new{ actor.run }
-        @thread.join(0.1)
-        expect {
-          actor.post!(0, nil)
-        }.to raise_error(Concurrent::TimeoutError)
-        actor.stop
-      end
-
-      it 'raises Concurrent::TimeoutError on timeout' do
-        actor = actor_class.new{|msg| sleep }
-        @thread = Thread.new{ actor.run }
-        @thread.join(0.1)
-        expect {
-          actor.post!(1, nil)
-        }.to raise_error(Concurrent::TimeoutError)
-        actor.stop
-      end
-
-      it 'bubbles the exception on error' do
-        actor = actor_class.new{|msg| raise StandardError.new('Boom!') }
-        @thread = Thread.new{ actor.run }
-        @thread.join(0.1)
-        expect {
-          actor.post!(1, nil)
-        }.to raise_error(StandardError)
-        actor.stop
-      end
-
-      it 'returns the result on success' do
-        actor = actor_class.new{|msg| 42 }
-        @thread = Thread.new{ actor.run }
-        @thread.join(0.1)
-        expected = actor.post!(1, nil)
-        expected.should == 42
-        actor.stop
-      end
-
-      it 'attempts to cancel the operation on timeout' do
-        @expected = 0
-        actor = actor_class.new{|msg| sleep(0.5); @expected += 1 }
-        @thread = Thread.new{ actor.run }
-        @thread.join(0.1)
-        actor.post(nil) # block the actor
-        expect {
-          actor.post!(0.1, nil)
-        }.to raise_error(Concurrent::TimeoutError)
-        sleep(1.5)
-        @expected.should == 1
-        actor.stop
-      end
-    end
-
-    context '#forward' do
-
-      let(:sender_clazz) do
-        Class.new(Actor) do
-          def act(*message)
-            if message.first.is_a?(Exception)
-              raise message.first
-            else
-              return message.first
-            end
-          end
-        end
-      end
-
-      let(:receiver_clazz) do
-        Class.new(Actor) do
-          attr_reader :result
-          def act(*message)
-            @result = message.first
+    let(:sender_class) do
+      Class.new(Actor) do
+        def act(*message)
+          if message.first.is_a?(Exception)
+            raise message.first
+          else
+            return message.first
           end
         end
       end
+    end
 
-      let(:sender) { sender_clazz.new }
-      let(:receiver) { receiver_clazz.new }
-
-      let(:observer) { double('observer') }
-
-      before(:each) do
-        @sender = Thread.new{ sender.run }
-        @receiver = Thread.new{ receiver.run }
-        sleep(0.1)
-      end
-
-      after(:each) do
-        sender.stop
-        receiver.stop
-        sleep(0.1)
-        @sender.kill unless @sender.nil?
-        @receiver.kill unless @receiver.nil?
-      end
-
-      it 'returns false when sender not running' do
-        sender_clazz.new.forward(receiver).should be_false
-      end
-
-      it 'forwards the result to the receiver on success' do
-        sender.forward(receiver, 42)
-        sleep(0.1)
-        receiver.result.should eq 42
-      end
+    let(:sender) { sender_class.new }
+    let(:receiver) { postable_class.new }
 
-      it 'does not forward on exception' do
-        sender.forward(receiver, StandardError.new)
-        sleep(0.1)
-        receiver.result.should be_nil
-      end
-
-      it 'notifies observers on success' do
-        observer.should_receive(:update).with(any_args())
-        sender.add_observer(observer)
-        sender.forward(receiver, 42)
-        sleep(0.1)
-      end
-
-      it 'notifies observers on exception' do
-        observer.should_not_receive(:update).with(any_args())
-        sender.add_observer(observer)
-        sender.forward(receiver, StandardError.new)
-        sleep(0.1)
-      end
-    end
+    it_should_behave_like :postable
 
     context '#run' do
 
@@ -394,65 +183,69 @@ module Concurrent
         }.to raise_error(ArgumentError)
       end
 
-      it 'creates the requested number of actors' do
-        mailbox, actors = clazz.pool(5)
-        actors.size.should == 5
+      it 'creates the requested number of pool' do
+        mailbox, pool = clazz.pool(5)
+        pool.size.should == 5
+      end
+
+      it 'passes all optional arguments to the individual constructors' do
+        clazz.should_receive(:new).with(1, 2, 3).exactly(5).times
+        clazz.pool(5, 1, 2, 3)
       end
 
-      it 'passes the block to each actor' do
+      it 'passes a duplicate of the given block to each actor in the pool' do
         block = proc{ nil }
-        clazz.should_receive(:new).with(&block)
-        clazz.pool(1, &block)
+        block.should_receive(:dup).exactly(5).times.and_return(proc{ nil })
+        mailbox, pool = Channel.pool(5, &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)
+      it 'gives all pool the same mailbox' do
+        mailbox, pool = clazz.pool(2)
+        mbox1 = pool.first.instance_variable_get(:@queue)
+        mbox2 = pool.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, pool = 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)
+      it 'gives the Poolbox the same mailbox as the pool' do
+        mailbox, pool = clazz.pool(1)
         mbox1 = mailbox.instance_variable_get(:@queue)
-        mbox2 = actors.first.instance_variable_get(:@queue)
+        mbox2 = pool.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|
+      it 'returns an array of pool as the second retval' do
+        mailbox, pool = clazz.pool(2)
+        pool.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 }
+        mailbox, pool = clazz.pool(1)
+        @thread = Thread.new{ pool.first.run }
         sleep(0.1)
         mailbox.post(42)
         sleep(0.1)
-        actors.each{|actor| actor.stop }
+        pool.first.last_message.should eq [42]
+        pool.first.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 }
+        mailbox, pool = clazz.pool(1)
+        @thread = Thread.new{ pool.first.run }
         sleep(0.1)
         mailbox << 42
         sleep(0.1)
-        actors.each{|actor| actor.stop }
+        pool.first.last_message.should eq [42]
+        pool.first.stop
         @thread.kill
-        @expected.should be_true
       end
     end
 
@@ -464,10 +257,10 @@ module Concurrent
 
       context '#pool' do
 
-        it 'creates actors of the appropriate subclass' do
+        it 'creates pool of the appropriate subclass' do
           actor = Class.new(actor_class)
-          mailbox, actors = actor.pool(1)
-          actors.first.should be_a(actor)
+          mailbox, pool = actor.pool(1)
+          pool.first.should be_a(actor)
         end
       end