concurrent-ruby 0.1.1 → 0.2.0

data/lib/concurrent/thread_pool.rb

@@ -35,7 +35,7 @@ module Concurrent
     end
 
     def shutdown?
-      return ! running?
+      return @status == :shutdown
     end
 
     def killed?
@@ -43,10 +43,14 @@ module Concurrent
     end
 
     def shutdown
-      atomic {
-        @pool.size.times{ @queue << :stop }
-        @status = :shuttingdown
-      }
+      mutex.synchronize do
+        if @pool.empty?
+          @status = :shutdown
+        else
+          @status = :shuttingdown
+          @pool.size.times{ @queue << :stop }
+        end
+      end
     end
 
     def wait_for_termination(timeout = nil)
@@ -61,5 +65,12 @@ module Concurrent
       self.post(&block)
       return self
     end
+
+    protected
+
+    # @private
+    def mutex # :nodoc:
+      @mutex || Mutex.new
+    end
   end
 end

data/lib/concurrent/utilities.rb

@@ -20,5 +20,13 @@ module Kernel
     }.resume
   end
   module_function :atomic
+end
+
+class Mutex
 
+  def sync_with_timeout(timeout, &block)
+    Timeout::timeout(timeout) {
+      synchronize(&block)
+    }
+  end
 end

data/lib/concurrent/version.rb

@@ -1,3 +1,3 @@
 module Concurrent
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

data/md/defer.md

@@ -2,14 +2,14 @@
 
 In the pantheon of concurrency objects a `Defer` sits somewhere between `Future` and `Promise`.
 Inspired by [EventMachine's *defer* method](https://github.com/eventmachine/eventmachine/wiki/EM::Deferrable-and-EM.defer),
-a `Defer` can be considered a non-blocking `Future` or a simplified, non-blocking `Promise`.
+a `Defer` can be considered a non-blocking `Future` or a simplified, non-blocking `Promise`. Defers run on the global thread pool.
 
 Unlike `Future` and `Promise` a defer is non-blocking. The deferred *operation* is performed on another
 thread. If the *operation* is successful an optional *callback* is called on the same thread as the *operation*.
 The result of the *operation* is passed to the *callbacl*. If the *operation* fails (by raising an exception)
-then an optional *errorback* (error callback) is called on
-the same thread as the *operation*. The raised exception is passed to the *errorback*. The calling thread is
-never aware of the result of the *operation*. This approach fits much more cleanly within an
+then an optional *errorback* (error callback) is called on the same thread as the *operation*. The raised
+exception is passed to the *errorback*. The calling thread is never aware of the result of the *operation*.
+This approach fits much more cleanly within an
 [event-driven](http://en.wikipedia.org/wiki/Event-driven_programming) application.
 
 The operation of a `Defer` can easily be simulated using either `Future` or `Promise` and traditional branching

data/md/executor.md

@@ -0,0 +1,187 @@
+# Being of Sound Mind
+
+A very common currency pattern is to run a thread that performs a task at regular
+intervals. The thread that peforms the task sleeps for the given interval then
+waked up and performs the task. Later, rinse, repeat... This pattern causes two
+problems. First, it is difficult to test the business logic of the task becuse the
+task itself is tightly couple with the threading. Second, an exception in the task
+can cause the entire thread to abend. In a long-running application where the task
+thread is intended to run for days/weeks/years a crashed task thread can pose a real
+problem. The `Executor` class alleviates both problems.
+
+When an executor is launched it starts a thread for monitoring the execution interval.
+The executor thread does not perform the task, however. Instead, the executor
+launches the task on a separat thread. The advantage of this approach is that if
+the task crashes it will only kill the task thread, not the executor thread. The
+executor thread can then log the success or failure of the task. The executor
+can even be configured with a timeout value allowing it to kill a task that runs
+to long and then log the error.
+
+One other advantage of the `Executor` class is that it forces the bsiness logic to
+be completely decoupled from the threading logic. The business logic can be tested
+separately then passed to the an executor for scheduling and running.
+
+Unlike some of the others concurrency objects in the library, executors do not
+run on the global. In my experience the types of tasks that will benefit from
+the `Executor` class tend to also be long running. For this reason they get their
+own thread every time the task is executed.
+
+## ExecutionContext
+
+When an executor is run the return value is an `ExecutionContext` object. An
+`ExecutionContext` object has several attribute readers (`#name`, `#execution_interval`,
+and `#timeout_interval`). It also provides several `Thread` operations which can
+be performed against the internal thread. These include `#status`, `#join`, and
+`kill`.
+
+## Custom Logging
+
+An executor will write a log message to standard out at the completion of every
+task run. When the task is successful the log message is tagged at the `:info`
+level. When the task times out the log message is tagged at the `warn` level.
+When the task fails tocomplete (most likely because of exception) the log
+message is tagged at the `error` level.
+
+The default logging behavior can be overridden by passing a `proc` to the executor
+on creation. The block will be passes three (3) arguments every time it is run:
+executor `name`, log `level`, and the log `msg` (message). The `proc` can do
+whatever it wanst with these arguments.
+
+## Examples
+
+A basic example:
+
+```ruby
+require 'concurrent'
+
+ec = Concurrent::Executor.run('Foo'){ puts 'Boom!' }
+
+ec.name               #=> "Foo"
+ec.execution_interval #=> 60 == Concurrent::Executor::EXECUTION_INTERVAL
+ec.timeout_interval   #=> 30 == Concurrent::Executor::TIMEOUT_INTERVAL
+ec.status             #=> "sleep"
+
+# wait 60 seconds...
+#=> 'Boom!'
+#=> ' INFO (2013-08-02 23:20:15) Foo: execution completed successfully'
+
+ec.kill #=> true
+```
+
+Both the execution_interval and the timeout_interval can be configured:
+
+```ruby
+ec = Concurrent::Executor.run('Foo', execution_interval: 5, timeout_interval: 5) do
+       puts 'Boom!'
+     end
+
+ec.execution_interval #=> 5
+ec.timeout_interval   #=> 5
+```
+
+By default an `Executor` will wait for `:execution_interval` seconds before running the block.
+To run the block immediately set the `:run_now` option to `true`:
+
+```ruby
+ec = Concurrent::Executor.run('Foo', run_now: true){ puts 'Boom!' }
+#=> 'Boom!''
+#=> ' INFO (2013-08-15 21:35:14) Foo: execution completed successfully'
+ec.status #=> "sleep"
+>> 
+```
+
+A simple example with timeout and task exception:
+
+```ruby
+ec = Concurrent::Executor.run('Foo', execution_interval: 1, timeout_interval: 1){ sleep(10) }
+
+#=> WARN (2013-08-02 23:45:26) Foo: execution timed out after 1 seconds
+#=> WARN (2013-08-02 23:45:28) Foo: execution timed out after 1 seconds
+#=> WARN (2013-08-02 23:45:30) Foo: execution timed out after 1 seconds
+
+ec = Concurrent::Executor.run('Foo', execution_interval: 1){ raise StandardError }
+
+#=> ERROR (2013-08-02 23:47:31) Foo: execution failed with error 'StandardError'
+#=> ERROR (2013-08-02 23:47:32) Foo: execution failed with error 'StandardError'
+#=> ERROR (2013-08-02 23:47:33) Foo: execution failed with error 'StandardError'
+```
+
+For custom logging, simply provide a `proc` when creating an executor:
+
+```ruby
+file_logger = proc do |name, level, msg|
+  open('executor.log', 'a') do |f|
+    f << ("%5s (%s) %s: %s\n" % [level.upcase, Time.now.strftime("%F %T"), name, msg])
+  end
+end
+
+ec = Concurrent::Executor.run('Foo', execution_interval: 5, logger: file_logger) do
+       puts 'Boom!'
+     end
+
+# the log file contains
+# INFO (2013-08-02 23:30:19) Foo: execution completed successfully
+# INFO (2013-08-02 23:30:24) Foo: execution completed successfully
+# INFO (2013-08-02 23:30:29) Foo: execution completed successfully
+# INFO (2013-08-02 23:30:34) Foo: execution completed successfully
+# INFO (2013-08-02 23:30:39) Foo: execution completed successfully
+# INFO (2013-08-02 23:30:44) Foo: execution completed successfully
+```
+
+It is also possible to access the default stdout logger from within a logger `proc`:
+
+```ruby
+file_logger = proc do |name, level, msg|
+  Concurrent::Executor::STDOUT_LOGGER.call(name, level, msg)
+  open('executor.log', 'a') do |f|
+    f << ("%5s (%s) %s: %s\n" % [level.upcase, Time.now.strftime("%F %T"), name, msg])
+  end
+end
+
+ec = Concurrent::Executor.run('Foo', execution_interval: 5, logger: file_logger) do
+       puts 'Boom!'
+     end
+
+# wait...
+
+#=> Boom!
+#=> INFO (2013-08-02 23:40:49) Foo: execution completed successfully
+#=> Boom!
+#=> INFO (2013-08-02 23:40:54) Foo: execution completed successfully
+#=> Boom!
+#=> INFO (2013-08-02 23:40:59) Foo: execution completed successfully
+
+# and the log file contains
+# INFO (2013-08-02 23:39:52) Foo: execution completed successfully
+# INFO (2013-08-02 23:39:57) Foo: execution completed successfully
+# INFO (2013-08-02 23:40:49) Foo: execution completed successfully
+```
+
+## 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/md/promise.md

@@ -28,6 +28,8 @@ A *timeout* value can be passed to `value` to limit how long the call will block
 block indefinitely. If `0` the call will not block. Any other integer or float value will indicate the
 maximum number of seconds to block.
 
+Promises run on the global thread pool.
+
 ## Examples
 
 Start by requiring promises

data/md/thread_pool.md

@@ -151,6 +151,12 @@ $GLOBAL_THREAD_POOL = Concurrent::FixedThreadPool.new(10)
 old_global_pool.shutdown
 ```
 
+### NullThreadPool
+
+If for some reason an appliction would be better served by *not* having a global thread pool, the
+`NullThreadPool` is provided. The `NullThreadPool` is compatible with the global thread pool but
+it is not an actual thread pool. Instead it spawns a new thread on every call to the `post` method.
+
 ### EventMachine
 
 The [EventMachine](http://rubyeventmachine.com/) library (source [online](https://github.com/eventmachine/eventmachine))
@@ -167,6 +173,27 @@ require 'functional/concurrency'
 $GLOBAL_THREAD_POOL = EventMachineDeferProxy.new
 ```
 
+## Per-class Thread Pools
+
+Many of the classes in this library use the global thread pool rather than creating new threads.
+Classes such as `Agent`, `Defer`, and others follow this pattern. There may be cases where a
+program would be better suited for one or more of these classes used a different thread pool.
+All classes that use the global thread pool support a class-level `thread_pool` attribute accessor.
+This property defaults to the global thread pool but can be changed at any time. Once changed, all
+new instances of that class will use the new thread pool.
+
+```ruby
+Concurrent::Agent.thread_pool == $GLOBAL_THREAD_POOL #=> true
+
+$GLOBAL_THREAD_POOL = Concurrent::FixedThreadPool.new(10) #=> #<Concurrent::FixedThreadPool:0x007fe31130f1f0 ...
+
+Concurrent::Agent.thread_pool == $GLOBAL_THREAD_POOL #=> false
+
+Concurrent::Defer.thread_pool = Concurrent::CachedThreadPool.new #=> #<Concurrent::CachedThreadPool:0x007fef1c6b6b48 ...
+Concurrent::Defer.thread_pool == Concurrent::Agent.thread_pool #=> false
+Concurrent::Defer.thread_pool == $GLOBAL_THREAD_POOL #=> false
+```
+
 ## Copyright
 
 *Concurrent Ruby* is Copyright &copy; 2013 [Jerry D'Antonio](https://twitter.com/jerrydantonio).

data/spec/concurrent/agent_spec.rb

@@ -16,7 +16,7 @@ module Concurrent
     end
 
     before(:each) do
-      $GLOBAL_THREAD_POOL = CachedThreadPool.new
+      Agent.thread_pool = FixedThreadPool.new(1)
     end
 
     context '#initialize' do
@@ -38,7 +38,7 @@ module Concurrent
       end
 
       it 'spawns the worker thread' do
-        $GLOBAL_THREAD_POOL.should_receive(:post).once.with(any_args())
+        Agent.thread_pool.should_receive(:post).once.with(any_args())
         Agent.new(0)
       end
     end
@@ -92,6 +92,8 @@ module Concurrent
     context '#post' do
       
       it 'adds the given block to the queue' do
+        subject.post{ sleep(100) }
+        sleep(0.1)
         before = subject.length
         subject.post{ nil }
         subject.post{ nil }
@@ -99,6 +101,8 @@ module Concurrent
       end
 
       it 'does not add to the queue when no block is given' do
+        subject.post{ sleep(100) }
+        sleep(0.1)
         before = subject.length
         subject.post
         subject.post{ nil }
@@ -113,6 +117,8 @@ module Concurrent
       end
 
       it 'should increase by one for each #post' do
+        subject.post{ sleep(100) }
+        sleep(0.1)
         subject.post{ sleep }
         subject.post{ sleep }
         subject.post{ sleep }
@@ -375,31 +381,6 @@ module Concurrent
         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

data/spec/concurrent/cached_thread_pool_spec.rb

@@ -10,6 +10,7 @@ module Concurrent
     it_should_behave_like 'Thread Pool'
 
     context '#initialize' do
+
       it 'aliases Concurrent#new_cached_thread_pool' do
         pool = Concurrent.new_cached_thread_pool
         pool.should be_a(CachedThreadPool)
@@ -20,7 +21,7 @@ module Concurrent
     context '#kill' do
 
       it 'kills all threads' do
-        Thread.should_receive(:kill).exactly(5).times
+        Thread.should_receive(:kill).at_least(5).times
         pool = CachedThreadPool.new
         5.times{ sleep(0.1); pool << proc{ sleep(1) } }
         sleep(1)
@@ -108,5 +109,17 @@ module Concurrent
         subject.instance_variable_get(:@collector).status.should be_false
       end
     end
+
+    context '#status' do
+
+      it 'returns an empty collection when the pool is empty' do
+        subject.status.should be_empty
+      end
+
+      it 'returns one status object for each thread in the pool' do
+        3.times{ sleep(0.1); subject << proc{ sleep(0.5) } }
+        subject.status.length.should eq 3
+      end
+    end
   end
 end

data/spec/concurrent/defer_spec.rb

@@ -4,11 +4,11 @@ module Concurrent
 
   describe Defer do
 
-    context '#initialize' do
+    before(:each) do
+      Defer.thread_pool = FixedThreadPool.new(1)
+    end
 
-      before(:each) do
-        $GLOBAL_THREAD_POOL = FixedThreadPool.new(1)
-      end
+    context '#initialize' do
 
       it 'raises an exception if no block or operation given' do
         lambda {
@@ -19,23 +19,19 @@ module Concurrent
       it 'raises an exception if both a block and an operation given' do
         lambda {
           operation = proc{ nil }
-          Defer.new(operation, nil, nil){ nil }
+          Defer.new(op: operation){ nil }
         }.should raise_error(ArgumentError)
       end
 
       it 'starts the thread if an operation is given' do
-        $GLOBAL_THREAD_POOL.should_receive(:post).once.with(any_args())
+        Defer.thread_pool.should_receive(:post).once.with(any_args())
         operation = proc{ nil }
-        Defer.new(operation, nil, nil)
+        Defer.new(op: operation)
       end
 
       it 'does not start the thread if neither a callback or errorback is given' do
-        $GLOBAL_THREAD_POOL.should_not_receive(:post)
-        Defer.new(nil, nil, nil){ nil }
-      end
-
-      it 'aliases Kernel#defer' do
-        defer{ nil }.should be_a(Defer)
+        Defer.thread_pool.should_not_receive(:post)
+        Defer.new{ nil }
       end
     end
 
@@ -56,14 +52,14 @@ module Concurrent
       it 'raises an exception if an operation was provided at construction' do
         lambda {
           operation = proc{ nil }
-          Defer.new(operation, nil, nil).then{|result| nil }
+          Defer.new(op: operation).then{|result| nil }
         }.should raise_error(IllegalMethodCallError)
       end
 
       it 'raises an exception if a callback was provided at construction' do
         lambda {
           callback = proc{|result|nil }
-          Defer.new(nil, callback, nil){ nil }.then{|result| nil }
+          Defer.new(callback: callback){ nil }.then{|result| nil }
         }.should raise_error(IllegalMethodCallError)
       end
 
@@ -90,14 +86,14 @@ module Concurrent
       it 'raises an exception if an operation was provided at construction' do
         lambda {
           operation = proc{ nil }
-          Defer.new(operation, nil, nil).rescue{|ex| nil }
+          Defer.new(op: operation).rescue{|ex| nil }
         }.should raise_error(IllegalMethodCallError)
       end
 
       it 'raises an exception if an errorback was provided at construction' do
         lambda {
           errorback = proc{|ex| nil }
-          Defer.new(nil, nil, errorback){ nil }.rescue{|ex| nil }
+          Defer.new(errorback: errorback){ nil }.rescue{|ex| nil }
         }.should raise_error(IllegalMethodCallError)
       end
 
@@ -123,14 +119,14 @@ module Concurrent
 
       it 'starts the thread if not started' do
         deferred = Defer.new{ nil }
-        $GLOBAL_THREAD_POOL.should_receive(:post).once.with(any_args())
+        Defer.thread_pool.should_receive(:post).once.with(any_args())
         deferred.go
       end
 
       it 'does nothing if called more than once' do
         deferred = Defer.new{ nil }
         deferred.go
-        $GLOBAL_THREAD_POOL.should_not_receive(:post)
+        Defer.thread_pool.should_not_receive(:post)
         deferred.go
       end
 
@@ -138,8 +134,8 @@ module Concurrent
         operation = proc{ nil }
         callback = proc{|result| nil }
         errorback = proc{|ex| nil }
-        deferred = Defer.new(operation, callback, errorback)
-        $GLOBAL_THREAD_POOL.should_not_receive(:post)
+        deferred = Defer.new(op: operation, callback: callback, errorback: errorback)
+        Defer.thread_pool.should_not_receive(:post)
         deferred.go
       end
     end