concurrent-ruby 0.1.0 → 0.1.1.pre.1

data/md/thread_pool.md

@@ -1,197 +1,197 @@
-# We're Going to Need a Bigger Boat
-
-Thread pools are neither a new idea nor an implementation of the actor pattern. Nevertheless, thread
-pools are still an extremely relevant concurrency tool. Every time a thread is created then
-subsequently destroyed there is overhead. Creating a pool of reusable worker threads then repeatedly'
-dipping into the pool can have huge performace benefits for a long-running application like a service.
-Ruby's blocks provide an excellent mechanism for passing a generic work request to a thread, making
-Ruby an excellent candidate language for thread pools.
-
-The inspiration for thread pools in this library is Java's `java.util.concurrent` implementation of
-[thread pools](java.util.concurrent). The `java.util.concurrent` library is a well-designed, stable,
-scalable, and battle-tested concurrency library. It provides three different implementations of thread
-pools. One of those implementations is simply a special case of the first and doesn't offer much
-advantage in Ruby, so only the first two (`FixedThreadPool` and `CachedThreadPool`) are implemented here.
-
-Thread pools share common `behavior` defined by `:thread_pool`. The most imortant method is `post`
-(aliased with the left-shift operator `<<`). The `post` method sends a block to the pool for future
-processing.
-
-A running thread pool can be shutdown in an orderly or disruptive manner. Once a thread pool has been
-shutdown in cannot be started again. The `shutdown` method can be used to initiate an orderly shutdown
-of the thread pool. All new `post` calls will reject the given block and immediately return `false`.
-Threads in the pool will continue to process all in-progress work and will process all tasks still in
-the queue. The `kill` method can be used to immediately shutdown the pool. All new `post` calls will
-reject the given block and immediately return `false`. Ruby's `Thread.kill` will be called on all threads
-in the pool, aborting all in-progress work. Tasks in the queue will be discarded.
-
-A client thread can choose to block and wait for pool shutdown to complete. This is useful when shutting
-down an application and ensuring the app doesn't exit before pool processing is complete. The method
-`wait_for_termination` will block for a maximum of the given number of seconds then return `true` if
-shutdown completed successfully or `false`. When the timeout value is `nil` the call will block
-indefinitely. Calling `wait_for_termination` on a stopped thread pool will immediately return `true`.
-
-Predicate methods are provided to describe the current state of the thread pool. Provided methods are
-`running?`, `shutdown?`, and `killed?`. The `shutdown` method will return true regardless of whether
-the pool was shutdown wil `shutdown` or `kill`.
-
-## FixedThreadPool
-
-From the docs:
-
-> Creates a thread pool that reuses a fixed number of threads operating off a shared unbounded queue.
-> At any point, at most `nThreads` threads will be active processing tasks. If additional tasks are submitted
-> when all threads are active, they will wait in the queue until a thread is available. If any thread terminates
-> due to a failure during execution prior to shutdown, a new one will take its place if needed to execute
-> subsequent tasks. The threads in the pool will exist until it is explicitly `shutdown`.
-
-### Examples
-
-```ruby
-require 'concurrent'
-
-pool = Concurrent::FixedThreadPool.new(5)
-
-pool.size     #=> 5
-pool.running? #=> true
-pool.status   #=> ["sleep", "sleep", "sleep", "sleep", "sleep"]
-
-pool.post(1,2,3){|*args| sleep(10) }
-pool << proc{ sleep(10) }
-pool.size     #=> 5
-
-sleep(11)
-pool.status   #=> ["sleep", "sleep", "sleep", "sleep", "sleep"]
-
-pool.shutdown #=> :shuttingdown
-pool.status   #=> []
-pool.wait_for_termination
-
-pool.size      #=> 0
-pool.status    #=> []
-pool.shutdown? #=> true
-```
-
-## CachedThreadPool
-
-From the docs:
-
-> Creates a thread pool that creates new threads as needed, but will reuse previously constructed threads when
-> they are available. These pools will typically improve the performance of programs that execute many short-lived
-> asynchronous tasks. Calls to [`post`] will reuse previously constructed threads if available. If no existing
-> thread is available, a new thread will be created and added to the pool. Threads that have not been used for
-> sixty seconds are terminated and removed from the cache. Thus, a pool that remains idle for long enough will
-> not consume any resources. Note that pools with similar properties but different details (for example,
-> timeout parameters) may be created using [`CachedThreadPool`] constructors.
-
-### Examples
-
-```ruby
-require 'functional/cached_thread_pool'
-# or
-require 'functional/concurrency'
-
-pool = Concurrent::CachedThreadPool.new
-
-pool.size     #=> 0
-pool.running? #=> true
-pool.status   #=> []
-
-pool.post(1,2,3){|*args| sleep(10) }
-pool << proc{ sleep(10) }
-pool.size     #=> 2
-pool.status   #=> [[:working, nil, "sleep"], [:working, nil, "sleep"]]
-
-sleep(11)
-pool.status   #=> [[:idle, 23, "sleep"], [:idle, 23, "sleep"]]
-
-sleep(60)
-pool.size     #=> 0
-pool.status   #=> []
-
-pool.shutdown #=> :shuttingdown
-pool.status   #=> []
-pool.wait_for_termination
-
-pool.size      #=> 0
-pool.status    #=> []
-pool.shutdown? #=> true
-```
-
-## Global Thread Pool
-
-For efficiency, of the aforementioned concurrency methods (agents, futures, promises, and
-goroutines) run against a global thread pool. This pool can be directly accessed through the
-`$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.
-
-### Changing the Global Thread Pool
-
-It is possible to change the global thread pool. Simply assign a new pool to the `$GLOBAL_THREAD_POOL`
-variable:
-
-```ruby
-$GLOBAL_THREAD_POOL = Concurrent::FixedThreadPool.new(10)
-```
-
-Ideally this should be done at application startup, before any concurrency functions are called.
-If the circumstances warrant the global thread pool can be changed at runtime. Just make sure to
-shutdown the old global thread pool so that no tasks are lost:
-
-```ruby
-$GLOBAL_THREAD_POOL = Concurrent::FixedThreadPool.new(10)
-
-# do stuff...
-
-old_global_pool = $GLOBAL_THREAD_POOL
-$GLOBAL_THREAD_POOL = Concurrent::FixedThreadPool.new(10)
-old_global_pool.shutdown
-```
-
-### EventMachine
-
-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
-of `EventMachineDeferProxy`:
-
-```ruby
-require 'eventmachine' # do this FIRST
-require 'functional/concurrency'
-
-$GLOBAL_THREAD_POOL = EventMachineDeferProxy.new
-```
-
-## Copyright
-
-*Concurrent Ruby* is Copyright &copy; 2013 [Jerry D'Antonio](https://twitter.com/jerrydantonio).
-It is free software and may be redistributed under the terms specified in the LICENSE file.
-
-## License
-
-Released under the MIT license.
-
-http://www.opensource.org/licenses/mit-license.php  
-
-> 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.  
+# We're Going to Need a Bigger Boat
+
+Thread pools are neither a new idea nor an implementation of the actor pattern. Nevertheless, thread
+pools are still an extremely relevant concurrency tool. Every time a thread is created then
+subsequently destroyed there is overhead. Creating a pool of reusable worker threads then repeatedly'
+dipping into the pool can have huge performace benefits for a long-running application like a service.
+Ruby's blocks provide an excellent mechanism for passing a generic work request to a thread, making
+Ruby an excellent candidate language for thread pools.
+
+The inspiration for thread pools in this library is Java's `java.util.concurrent` implementation of
+[thread pools](java.util.concurrent). The `java.util.concurrent` library is a well-designed, stable,
+scalable, and battle-tested concurrency library. It provides three different implementations of thread
+pools. One of those implementations is simply a special case of the first and doesn't offer much
+advantage in Ruby, so only the first two (`FixedThreadPool` and `CachedThreadPool`) are implemented here.
+
+Thread pools share common `behavior` defined by `:thread_pool`. The most imortant method is `post`
+(aliased with the left-shift operator `<<`). The `post` method sends a block to the pool for future
+processing.
+
+A running thread pool can be shutdown in an orderly or disruptive manner. Once a thread pool has been
+shutdown in cannot be started again. The `shutdown` method can be used to initiate an orderly shutdown
+of the thread pool. All new `post` calls will reject the given block and immediately return `false`.
+Threads in the pool will continue to process all in-progress work and will process all tasks still in
+the queue. The `kill` method can be used to immediately shutdown the pool. All new `post` calls will
+reject the given block and immediately return `false`. Ruby's `Thread.kill` will be called on all threads
+in the pool, aborting all in-progress work. Tasks in the queue will be discarded.
+
+A client thread can choose to block and wait for pool shutdown to complete. This is useful when shutting
+down an application and ensuring the app doesn't exit before pool processing is complete. The method
+`wait_for_termination` will block for a maximum of the given number of seconds then return `true` if
+shutdown completed successfully or `false`. When the timeout value is `nil` the call will block
+indefinitely. Calling `wait_for_termination` on a stopped thread pool will immediately return `true`.
+
+Predicate methods are provided to describe the current state of the thread pool. Provided methods are
+`running?`, `shutdown?`, and `killed?`. The `shutdown` method will return true regardless of whether
+the pool was shutdown wil `shutdown` or `kill`.
+
+## FixedThreadPool
+
+From the docs:
+
+> Creates a thread pool that reuses a fixed number of threads operating off a shared unbounded queue.
+> At any point, at most `nThreads` threads will be active processing tasks. If additional tasks are submitted
+> when all threads are active, they will wait in the queue until a thread is available. If any thread terminates
+> due to a failure during execution prior to shutdown, a new one will take its place if needed to execute
+> subsequent tasks. The threads in the pool will exist until it is explicitly `shutdown`.
+
+### Examples
+
+```ruby
+require 'concurrent'
+
+pool = Concurrent::FixedThreadPool.new(5)
+
+pool.size     #=> 5
+pool.running? #=> true
+pool.status   #=> ["sleep", "sleep", "sleep", "sleep", "sleep"]
+
+pool.post(1,2,3){|*args| sleep(10) }
+pool << proc{ sleep(10) }
+pool.size     #=> 5
+
+sleep(11)
+pool.status   #=> ["sleep", "sleep", "sleep", "sleep", "sleep"]
+
+pool.shutdown #=> :shuttingdown
+pool.status   #=> []
+pool.wait_for_termination
+
+pool.size      #=> 0
+pool.status    #=> []
+pool.shutdown? #=> true
+```
+
+## CachedThreadPool
+
+From the docs:
+
+> Creates a thread pool that creates new threads as needed, but will reuse previously constructed threads when
+> they are available. These pools will typically improve the performance of programs that execute many short-lived
+> asynchronous tasks. Calls to [`post`] will reuse previously constructed threads if available. If no existing
+> thread is available, a new thread will be created and added to the pool. Threads that have not been used for
+> sixty seconds are terminated and removed from the cache. Thus, a pool that remains idle for long enough will
+> not consume any resources. Note that pools with similar properties but different details (for example,
+> timeout parameters) may be created using [`CachedThreadPool`] constructors.
+
+### Examples
+
+```ruby
+require 'functional/cached_thread_pool'
+# or
+require 'functional/concurrency'
+
+pool = Concurrent::CachedThreadPool.new
+
+pool.size     #=> 0
+pool.running? #=> true
+pool.status   #=> []
+
+pool.post(1,2,3){|*args| sleep(10) }
+pool << proc{ sleep(10) }
+pool.size     #=> 2
+pool.status   #=> [[:working, nil, "sleep"], [:working, nil, "sleep"]]
+
+sleep(11)
+pool.status   #=> [[:idle, 23, "sleep"], [:idle, 23, "sleep"]]
+
+sleep(60)
+pool.size     #=> 0
+pool.status   #=> []
+
+pool.shutdown #=> :shuttingdown
+pool.status   #=> []
+pool.wait_for_termination
+
+pool.size      #=> 0
+pool.status    #=> []
+pool.shutdown? #=> true
+```
+
+## Global Thread Pool
+
+For efficiency, of the aforementioned concurrency methods (agents, futures, promises, and
+goroutines) run against a global thread pool. This pool can be directly accessed through the
+`$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.
+
+### Changing the Global Thread Pool
+
+It is possible to change the global thread pool. Simply assign a new pool to the `$GLOBAL_THREAD_POOL`
+variable:
+
+```ruby
+$GLOBAL_THREAD_POOL = Concurrent::FixedThreadPool.new(10)
+```
+
+Ideally this should be done at application startup, before any concurrency functions are called.
+If the circumstances warrant the global thread pool can be changed at runtime. Just make sure to
+shutdown the old global thread pool so that no tasks are lost:
+
+```ruby
+$GLOBAL_THREAD_POOL = Concurrent::FixedThreadPool.new(10)
+
+# do stuff...
+
+old_global_pool = $GLOBAL_THREAD_POOL
+$GLOBAL_THREAD_POOL = Concurrent::FixedThreadPool.new(10)
+old_global_pool.shutdown
+```
+
+### EventMachine
+
+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
+of `EventMachineDeferProxy`:
+
+```ruby
+require 'eventmachine' # do this FIRST
+require 'functional/concurrency'
+
+$GLOBAL_THREAD_POOL = EventMachineDeferProxy.new
+```
+
+## Copyright
+
+*Concurrent Ruby* is Copyright &copy; 2013 [Jerry D'Antonio](https://twitter.com/jerrydantonio).
+It is free software and may be redistributed under the terms specified in the LICENSE file.
+
+## License
+
+Released under the MIT license.
+
+http://www.opensource.org/licenses/mit-license.php  
+
+> 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/spec/concurrent/agent_spec.rb

@@ -1,405 +1,376 @@
-require 'spec_helper'
-
-module Concurrent
-
-  describe Agent do
-
-    subject { Agent.new(0) }
-
-    let(:observer) do
-      Class.new do
-        attr_reader :value
-        define_method(:update) do |time, value|
-          @value = value
-        end
-      end.new
-    end
-
-    before(:each) do
-      $GLOBAL_THREAD_POOL = CachedThreadPool.new
-    end
-
-    context '#initialize' do
-
-      it 'sets the value to the given initial state' do
-        Agent.new(10).value.should eq 10
-      end
-
-      it 'sets the timeout to the given value' do
-        Agent.new(0, 5).timeout.should eq 5
-      end
-
-      it 'sets the timeout to the default when nil' do
-        Agent.new(0).timeout.should eq Agent::TIMEOUT
-      end
-
-      it 'sets the length to zero' do
-        Agent.new(10).length.should eq 0
-      end
-
-      it 'spawns the worker thread' do
-        $GLOBAL_THREAD_POOL.should_receive(:post).once.with(any_args())
-        Agent.new(0)
-      end
-    end
-
-    context '#rescue' do
-
-      it 'returns self when a block is given' do
-        a1 = subject
-        a2 = a1.rescue{}
-        a1.object_id.should eq a2.object_id
-      end
-
-      it 'returns self when no block is given' do
-        a1 = subject
-        a2 = a1.rescue
-        a1.object_id.should eq a2.object_id
-      end
-
-      it 'accepts an exception class as the first parameter' do
-        lambda {
-          subject.rescue(StandardError){}
-        }.should_not raise_error
-      end
-
-      it 'ignores rescuers without a block' do
-        subject.rescue
-        subject.instance_variable_get(:@rescuers).should be_empty
-      end
-    end
-
-    context '#validate' do
-
-      it 'returns self when a block is given' do
-        a1 = subject
-        a2 = a1.validate{}
-        a1.object_id.should eq a2.object_id
-      end
-
-      it 'returns self when no block is given' do
-        a1 = subject
-        a2 = a1.validate
-        a1.object_id.should eq a2.object_id
-      end
-
-      it 'ignores validators without a block' do
-        subject.validate
-        subject.instance_variable_get(:@validator).should be_nil
-      end
-    end
-
-    context '#post' do
-      
-      it 'adds the given block to the queue' do
-        before = subject.length
-        subject.post{ nil }
-        subject.post{ nil }
-        subject.length.should eq before+2
-      end
-
-      it 'does not add to the queue when no block is given' do
-        before = subject.length
-        subject.post
-        subject.post{ nil }
-        subject.length.should eq before+1
-      end
-    end
-
-    context '#length' do
-
-      it 'should be zero for a new agent' do
-        subject.length.should eq 0
-      end
-
-      it 'should increase by one for each #post' do
-        subject.post{ sleep }
-        subject.post{ sleep }
-        subject.post{ sleep }
-        subject.length.should eq 3
-      end
-
-      it 'should decrease by one each time a handler is run' do
-        subject.post{ nil }
-        subject.post{ sleep }
-        subject.post{ sleep }
-        sleep(0.1)
-        subject.length.should eq 1
-      end
-    end
-
-    context 'fulfillment' do
-
-      it 'process each block in the queue' do
-        @expected = []
-        subject.post{ @expected << 1 }
-        subject.post{ @expected << 2 }
-        subject.post{ @expected << 3 }
-        sleep(0.1)
-        @expected.should eq [1,2,3]
-      end
-
-      it 'passes the current value to the handler' do
-        @expected = nil
-        Agent.new(10).post{|i| @expected = i }
-        sleep(0.1)
-        @expected.should eq 10
-      end
-
-      it 'sets the value to the handler return value on success' do
-        subject.post{ 100 }
-        sleep(0.1)
-        subject.value.should eq 100
-      end
-
-      it 'rejects the handler after timeout reached' do
-        agent = Agent.new(0, 0.1)
-        agent.post{ sleep(1); 10 }
-        agent.value.should eq 0
-      end
-    end
-
-    context 'validation' do
-
-      it 'processes the validator when present' do
-        @expected = nil
-        subject.validate{ @expected = 10; true }
-        subject.post{ nil }
-        sleep(0.1)
-        @expected.should eq 10
-      end
-
-      it 'passes the new value to the validator' do
-        @expected = nil
-        subject.validate{|v| @expected = v; true }
-        subject.post{ 10 }
-        sleep(0.1)
-        @expected.should eq 10
-      end
-
-      it 'sets the new value when the validator returns true' do
-        agent = Agent.new(0).validate{ true }
-        agent.post{ 10 }
-        sleep(0.1)
-        agent.value.should eq 10
-      end
-
-      it 'does not change the value when the validator returns false' do
-        agent = Agent.new(0).validate{ false }
-        agent.post{ 10 }
-        sleep(0.1)
-        agent.value.should eq 0
-      end
-
-      it 'does not change the value when the validator raises an exception' do
-        agent = Agent.new(0).validate{ raise StandardError }
-        agent.post{ 10 }
-        sleep(0.1)
-        agent.value.should eq 0
-      end
-    end
-
-    context 'rejection' do
-
-      it 'calls the first exception block with a matching class' do
-        @expected = nil
-        subject.
-          rescue(StandardError){|ex| @expected = 1 }.
-          rescue(StandardError){|ex| @expected = 2 }.
-          rescue(StandardError){|ex| @expected = 3 }
-        subject.post{ raise StandardError }
-          sleep(0.1)
-        @expected.should eq 1
-      end
-
-      it 'matches all with a rescue with no class given' do
-        @expected = nil
-        subject.
-          rescue(LoadError){|ex| @expected = 1 }.
-          rescue{|ex| @expected = 2 }.
-          rescue(StandardError){|ex| @expected = 3 }
-        subject.post{ raise NoMethodError }
-        sleep(0.1)
-        @expected.should eq 2
-      end
-
-      it 'searches associated rescue handlers in order' do
-        @expected = nil
-        subject.
-          rescue(ArgumentError){|ex| @expected = 1 }.
-          rescue(LoadError){|ex| @expected = 2 }.
-          rescue(Exception){|ex| @expected = 3 }
-        subject.post{ raise ArgumentError }
-        sleep(0.1)
-        @expected.should eq 1
-
-        @expected = nil
-        subject.
-          rescue(ArgumentError){|ex| @expected = 1 }.
-          rescue(LoadError){|ex| @expected = 2 }.
-          rescue(Exception){|ex| @expected = 3 }
-        subject.post{ raise LoadError }
-        sleep(0.1)
-        @expected.should eq 2
-
-        @expected = nil
-        subject.
-          rescue(ArgumentError){|ex| @expected = 1 }.
-          rescue(LoadError){|ex| @expected = 2 }.
-          rescue(Exception){|ex| @expected = 3 }
-        subject.post{ raise StandardError }
-        sleep(0.1)
-        @expected.should eq 3
-      end
-
-      it 'passes the exception object to the matched block' do
-        @expected = nil
-        subject.
-          rescue(ArgumentError){|ex| @expected = ex }.
-          rescue(LoadError){|ex| @expected = ex }.
-          rescue(Exception){|ex| @expected = ex }
-        subject.post{ raise StandardError }
-        sleep(0.1)
-        @expected.should be_a(StandardError)
-      end
-
-      it 'ignores rescuers without a block' do
-        @expected = nil
-        subject.
-          rescue(StandardError).
-          rescue(StandardError){|ex| @expected = ex }.
-          rescue(Exception){|ex| @expected = ex }
-        subject.post{ raise StandardError }
-        sleep(0.1)
-        @expected.should be_a(StandardError)
-      end
-
-      it 'supresses the exception if no rescue matches' do
-        lambda {
-          subject.
-            rescue(ArgumentError){|ex| @expected = ex }.
-            rescue(StandardError){|ex| @expected = ex }.
-            rescue(Exception){|ex| @expected = ex }
-          subject.post{ raise StandardError }
-          sleep(0.1)
-        }.should_not raise_error
-      end
-
-      it 'supresses exceptions thrown from rescue handlers' do
-        lambda {
-          subject.rescue(Exception){ raise StandardError }
-          subject.post{ raise ArgumentError }
-          sleep(0.1)
-        }.should_not raise_error
-      end
-    end
-
-    context 'observation' do
-
-      it 'notifies all observers when the value changes' do
-        agent = Agent.new(0)
-        agent.add_observer(observer)
-        agent.post{ 10 }
-        sleep(0.1)
-        observer.value.should eq 10
-      end
-
-      it 'does not notify observers when validation fails' do
-        agent = Agent.new(0)
-        agent.validate{ false }
-        agent.add_observer(observer)
-        agent.post{ 10 }
-        sleep(0.1)
-        observer.value.should be_nil
-      end
-
-      it 'does not notify observers when the handler raises an exception' do
-        agent = Agent.new(0)
-        agent.add_observer(observer)
-        agent.post{ raise StandardError }
-        sleep(0.1)
-        observer.value.should be_nil
-      end
-    end
-
-    context 'aliases' do
-
-      it 'aliases #deref for #value' do
-        Agent.new(10).deref.should eq 10
-      end
-
-      it 'aliases #validates for :validate' do
-        @expected = nil
-        subject.validates{|v| @expected = v }
-        subject.post{ 10 }
-        sleep(0.1)
-        @expected.should eq 10
-      end
-        
-      it 'aliases #validate_with for :validate' do
-        @expected = nil
-        subject.validate_with{|v| @expected = v }
-        subject.post{ 10 }
-        sleep(0.1)
-        @expected.should eq 10
-      end
-
-      it 'aliases #validates_with for :validate' do
-        @expected = nil
-        subject.validates_with{|v| @expected = v }
-        subject.post{ 10 }
-        sleep(0.1)
-        @expected.should eq 10
-      end
-
-      it 'aliases #catch for #rescue' do
-        @expected = nil
-        subject.catch{ @expected = true }
-        subject.post{ raise StandardError }
-        sleep(0.1)
-        @expected.should be_true
-      end
-
-      it 'aliases #on_error for #rescue' do
-        @expected = nil
-        subject.on_error{ @expected = true }
-        subject.post{ raise StandardError }
-        sleep(0.1)
-        @expected.should be_true
-      end
-
-      it 'aliases #add_watch for #add_observer' do
-        agent = Agent.new(0)
-        agent.add_watch(observer)
-        agent.post{ 10 }
-        sleep(0.1)
-        observer.value.should eq 10
-      end
-
-      it 'aliases #<< for Agent#post' do
-        subject << proc{ 100 }
-        sleep(0.1)
-        subject.value.should eq 100
-
-        subject << lambda{ 100 }
-        sleep(0.1)
-        subject.value.should eq 100
-      end
-
-      it 'aliases Kernel#agent for Agent.new' do
-        agent(10).should be_a(Agent)
-      end
-
-      it 'aliases Kernel#deref for #deref' do
-        deref(Agent.new(10)).should eq 10
-        deref(Agent.new(10), 10).should eq 10
-      end
-
-      it 'aliases Kernel:post for Agent#post' do
-        post(subject){ 100 }
-        sleep(0.1)
-        subject.value.should eq 100
-      end
-    end
-  end
-end
+require 'spec_helper'
+
+module Concurrent
+
+  describe Agent do
+
+    subject { Agent.new(0) }
+
+    let(:observer) do
+      Class.new do
+        attr_reader :value
+        define_method(:update) do |time, value|
+          @value = value
+        end
+      end.new
+    end
+
+    context '#initialize' do
+
+      it 'sets the value to the given initial state' do
+        Agent.new(10).value.should eq 10
+      end
+
+      it 'sets the timeout to the given value' do
+        Agent.new(0, 5).timeout.should eq 5
+      end
+
+      it 'sets the timeout to the default when nil' do
+        Agent.new(0).timeout.should eq Agent::TIMEOUT
+      end
+
+      it 'sets the length to zero' do
+        Agent.new(10).length.should eq 0
+      end
+
+      it 'spawns the worker thread' do
+        Thread.should_receive(:new).once.with(any_args())
+        Agent.new(0)
+      end
+    end
+
+    context '#rescue' do
+
+      it 'returns self when a block is given' do
+        a1 = subject
+        a2 = a1.rescue{}
+        a1.object_id.should eq a2.object_id
+      end
+
+      it 'returns self when no block is given' do
+        a1 = subject
+        a2 = a1.rescue
+        a1.object_id.should eq a2.object_id
+      end
+
+      it 'accepts an exception class as the first parameter' do
+        lambda {
+          subject.rescue(StandardError){}
+        }.should_not raise_error
+      end
+
+      it 'ignores rescuers without a block' do
+        subject.rescue
+        subject.instance_variable_get(:@rescuers).should be_empty
+      end
+    end
+
+    context '#validate' do
+
+      it 'returns self when a block is given' do
+        a1 = subject
+        a2 = a1.validate{}
+        a1.object_id.should eq a2.object_id
+      end
+
+      it 'returns self when no block is given' do
+        a1 = subject
+        a2 = a1.validate
+        a1.object_id.should eq a2.object_id
+      end
+
+      it 'ignores validators without a block' do
+        subject.validate
+        subject.instance_variable_get(:@validator).should be_nil
+      end
+    end
+
+    context '#post' do
+      
+      it 'adds the given block to the queue' do
+        before = subject.length
+        subject.post{ nil }
+        subject.post{ nil }
+        subject.length.should eq before+2
+      end
+
+      it 'does not add to the queue when no block is given' do
+        before = subject.length
+        subject.post
+        subject.post{ nil }
+        subject.length.should eq before+1
+      end
+    end
+
+    context '#length' do
+
+      it 'should be zero for a new agent' do
+        subject.length.should eq 0
+      end
+
+      it 'should increase by one for each #post' do
+        subject.post{ sleep }
+        subject.post{ sleep }
+        subject.post{ sleep }
+        subject.length.should eq 3
+      end
+
+      it 'should decrease by one each time a handler is run' do
+        subject.post{ nil }
+        subject.post{ sleep }
+        subject.post{ sleep }
+        sleep(0.1)
+        subject.length.should eq 1
+      end
+    end
+
+    context 'fulfillment' do
+
+      it 'process each block in the queue' do
+        @expected = []
+        subject.post{ @expected << 1 }
+        subject.post{ @expected << 2 }
+        subject.post{ @expected << 3 }
+        sleep(0.1)
+        @expected.should eq [1,2,3]
+      end
+
+      it 'passes the current value to the handler' do
+        @expected = nil
+        Agent.new(10).post{|i| @expected = i }
+        sleep(0.1)
+        @expected.should eq 10
+      end
+
+      it 'sets the value to the handler return value on success' do
+        subject.post{ 100 }
+        sleep(0.1)
+        subject.value.should eq 100
+      end
+
+      it 'rejects the handler after timeout reached' do
+        agent = Agent.new(0, 0.1)
+        agent.post{ sleep(1); 10 }
+        agent.value.should eq 0
+      end
+    end
+
+    context 'validation' do
+
+      it 'processes the validator when present' do
+        @expected = nil
+        subject.validate{ @expected = 10; true }
+        subject.post{ nil }
+        sleep(0.1)
+        @expected.should eq 10
+      end
+
+      it 'passes the new value to the validator' do
+        @expected = nil
+        subject.validate{|v| @expected = v; true }
+        subject.post{ 10 }
+        sleep(0.1)
+        @expected.should eq 10
+      end
+
+      it 'sets the new value when the validator returns true' do
+        agent = Agent.new(0).validate{ true }
+        agent.post{ 10 }
+        sleep(0.1)
+        agent.value.should eq 10
+      end
+
+      it 'does not change the value when the validator returns false' do
+        agent = Agent.new(0).validate{ false }
+        agent.post{ 10 }
+        sleep(0.1)
+        agent.value.should eq 0
+      end
+
+      it 'does not change the value when the validator raises an exception' do
+        agent = Agent.new(0).validate{ raise StandardError }
+        agent.post{ 10 }
+        sleep(0.1)
+        agent.value.should eq 0
+      end
+    end
+
+    context 'rejection' do
+
+      it 'calls the first exception block with a matching class' do
+        @expected = nil
+        subject.
+          rescue(StandardError){|ex| @expected = 1 }.
+          rescue(StandardError){|ex| @expected = 2 }.
+          rescue(StandardError){|ex| @expected = 3 }
+        subject.post{ raise StandardError }
+          sleep(0.1)
+        @expected.should eq 1
+      end
+
+      it 'matches all with a rescue with no class given' do
+        @expected = nil
+        subject.
+          rescue(LoadError){|ex| @expected = 1 }.
+          rescue{|ex| @expected = 2 }.
+          rescue(StandardError){|ex| @expected = 3 }
+        subject.post{ raise NoMethodError }
+        sleep(0.1)
+        @expected.should eq 2
+      end
+
+      it 'searches associated rescue handlers in order' do
+        @expected = nil
+        subject.
+          rescue(ArgumentError){|ex| @expected = 1 }.
+          rescue(LoadError){|ex| @expected = 2 }.
+          rescue(Exception){|ex| @expected = 3 }
+        subject.post{ raise ArgumentError }
+        sleep(0.1)
+        @expected.should eq 1
+
+        @expected = nil
+        subject.
+          rescue(ArgumentError){|ex| @expected = 1 }.
+          rescue(LoadError){|ex| @expected = 2 }.
+          rescue(Exception){|ex| @expected = 3 }
+        subject.post{ raise LoadError }
+        sleep(0.1)
+        @expected.should eq 2
+
+        @expected = nil
+        subject.
+          rescue(ArgumentError){|ex| @expected = 1 }.
+          rescue(LoadError){|ex| @expected = 2 }.
+          rescue(Exception){|ex| @expected = 3 }
+        subject.post{ raise StandardError }
+        sleep(0.1)
+        @expected.should eq 3
+      end
+
+      it 'passes the exception object to the matched block' do
+        @expected = nil
+        subject.
+          rescue(ArgumentError){|ex| @expected = ex }.
+          rescue(LoadError){|ex| @expected = ex }.
+          rescue(Exception){|ex| @expected = ex }
+        subject.post{ raise StandardError }
+        sleep(0.1)
+        @expected.should be_a(StandardError)
+      end
+
+      it 'ignores rescuers without a block' do
+        @expected = nil
+        subject.
+          rescue(StandardError).
+          rescue(StandardError){|ex| @expected = ex }.
+          rescue(Exception){|ex| @expected = ex }
+        subject.post{ raise StandardError }
+        sleep(0.1)
+        @expected.should be_a(StandardError)
+      end
+
+      it 'supresses the exception if no rescue matches' do
+        lambda {
+          subject.
+            rescue(ArgumentError){|ex| @expected = ex }.
+            rescue(StandardError){|ex| @expected = ex }.
+            rescue(Exception){|ex| @expected = ex }
+          subject.post{ raise StandardError }
+          sleep(0.1)
+        }.should_not raise_error
+      end
+
+      it 'supresses exceptions thrown from rescue handlers' do
+        lambda {
+          subject.rescue(Exception){ raise StandardError }
+          subject.post{ raise ArgumentError }
+          sleep(0.1)
+        }.should_not raise_error
+      end
+    end
+
+    context 'observation' do
+
+      it 'notifies all observers when the value changes' do
+        agent = Agent.new(0)
+        agent.add_observer(observer)
+        agent.post{ 10 }
+        sleep(0.1)
+        observer.value.should eq 10
+      end
+
+      it 'does not notify observers when validation fails' do
+        agent = Agent.new(0)
+        agent.validate{ false }
+        agent.add_observer(observer)
+        agent.post{ 10 }
+        sleep(0.1)
+        observer.value.should be_nil
+      end
+
+      it 'does not notify observers when the handler raises an exception' do
+        agent = Agent.new(0)
+        agent.add_observer(observer)
+        agent.post{ raise StandardError }
+        sleep(0.1)
+        observer.value.should be_nil
+      end
+    end
+
+    context 'aliases' do
+
+      it 'aliases #deref for #value' do
+        Agent.new(10).deref.should eq 10
+      end
+
+      it 'aliases #validates for :validate' do
+        @expected = nil
+        subject.validates{|v| @expected = v }
+        subject.post{ 10 }
+        sleep(0.1)
+        @expected.should eq 10
+      end
+        
+      it 'aliases #validate_with for :validate' do
+        @expected = nil
+        subject.validate_with{|v| @expected = v }
+        subject.post{ 10 }
+        sleep(0.1)
+        @expected.should eq 10
+      end
+
+      it 'aliases #validates_with for :validate' do
+        @expected = nil
+        subject.validates_with{|v| @expected = v }
+        subject.post{ 10 }
+        sleep(0.1)
+        @expected.should eq 10
+      end
+
+      it 'aliases #catch for #rescue' do
+        @expected = nil
+        subject.catch{ @expected = true }
+        subject.post{ raise StandardError }
+        sleep(0.1)
+        @expected.should be_true
+      end
+
+      it 'aliases #on_error for #rescue' do
+        @expected = nil
+        subject.on_error{ @expected = true }
+        subject.post{ raise StandardError }
+        sleep(0.1)
+        @expected.should be_true
+      end
+
+      it 'aliases #add_watch for #add_observer' do
+        agent = Agent.new(0)
+        agent.add_watch(observer)
+        agent.post{ 10 }
+        sleep(0.1)
+        observer.value.should eq 10
+      end
+    end
+  end
+end