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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2e3a37abe10cd8c068be7f5f34ec87ea665c4d8c
-  data.tar.gz: bbb6cf6902175de9995656c9ded8e611940edfb7
+  metadata.gz: 0823ac7a2cf530803f04b071254f156c32a840a7
+  data.tar.gz: 74a9edb10d10210746b53cb87dec1bdff8c1a971
 SHA512:
-  metadata.gz: 69f7670740cfb70d858462864993d38209050a435435cbd4a9202dda5146f3ab32629bc6e2206b016c2ec0d9a95b5ff1c7751a2ee8278ba6e6400fafb478d23f
-  data.tar.gz: 84ce8fdad2b1ccc72f93e6a5b08889937b9c27d2d4aea0560d191ac4e9338e5909fedbd1a9a128c228a36eb7f6fbcc6f3206130308658122d23d98e89a2a4239
+  metadata.gz: f681fd88bf4a4aa2d0a1f186f48fe839ef370c39f08fe3fa9527c539668b02a3d50581e4b8e7bac11212e726231eb7f59c7671447b3b78c87ce6d67037cc6ecd
+  data.tar.gz: 856d32dac93217664581bfd4958d5daee48b5c0525bf4ca6307a83aeef912e7f0b2a441c3fd2c410e00041191af98ec163ac2a5ee9965aa8fb362fec1298f051

data/README.md

@@ -59,8 +59,8 @@ Several features from Erlang, Go, Clojure, Java, and JavaScript have been implem
 * Go inspired [Goroutine](https://github.com/jdantonio/concurrent-ruby/blob/master/md/goroutine.md)
 * JavaScript inspired [Promise](https://github.com/jdantonio/concurrent-ruby/blob/master/md/promise.md)
 * Java inspired [Thread Pools](https://github.com/jdantonio/concurrent-ruby/blob/master/md/thread_pool.md)
-* Old school [events](http://msdn.microsoft.com/en-us/library/windows/desktop/ms682655(v=vs.85).aspx) from back in my Visual C++ days
-* Scheduled task execution with the [Executor](https://github.com/jdantonio/concurrent-ruby/blob/master/md/executor.md) service
+* Old school [events](http://msdn.microsoft.com/en-us/library/windows/desktop/ms682655.aspx) from back in my Visual C++ days
+* Repeated task execution with Java inspired [TimerTask](https://github.com/jdantonio/concurrent-ruby/blob/master/md/timer_task.md) service
 * Erlang inspired [Supervisor](https://github.com/jdantonio/concurrent-ruby/blob/master/md/supervisor.md) for managing long-running threads
 
 ### Is it any good?
@@ -199,25 +199,32 @@ sleep(1)
 #=> Zap!
 ```
 
-#### Executor
+#### TimerTask
 
 ```ruby
 require 'concurrent'
 
-ec = Concurrent::Executor.run('Foo'){ puts 'Boom!' }
+ec = Concurrent::TimerTask.run{ puts 'Boom!' }
 
-ec.name               #=> "Foo"
-ec.execution_interval #=> 60 == Concurrent::Executor::EXECUTION_INTERVAL
-ec.timeout_interval   #=> 30 == Concurrent::Executor::TIMEOUT_INTERVAL
+ec.execution_interval #=> 60 == Concurrent::TimerTask::EXECUTION_INTERVAL
+ec.timeout_interval   #=> 30 == Concurrent::TimerTask::TIMEOUT_INTERVAL
 ec.status             #=> "sleep"
 
 # wait 60 seconds...
 #=> 'Boom!'
-#=> ' INFO (2013-08-02 23:20:15) Foo: execution completed successfully'
 
 ec.kill #=> true
 ```
 
+## Todo
+
+* DelayedTask
+* More methods from Scala's Actor
+* More Erlang goodness
+  * gen_server
+  * gen_event
+  * gen_fsm
+
 ## Contributing
 
 1. Fork it

data/lib/concurrent.rb

@@ -4,13 +4,13 @@ require 'concurrent/version'
 require 'concurrent/actor'
 require 'concurrent/agent'
 require 'concurrent/event'
-require 'concurrent/executor'
 require 'concurrent/future'
 require 'concurrent/goroutine'
 require 'concurrent/obligation'
 require 'concurrent/promise'
 require 'concurrent/runnable'
 require 'concurrent/supervisor'
+require 'concurrent/timer_task'
 require 'concurrent/utilities'
 
 require 'concurrent/global_thread_pool'

data/lib/concurrent/runnable.rb

@@ -2,7 +2,9 @@ require 'thread'
 
 module Concurrent
 
-  module Running
+  module Runnable
+
+    LifecycleError = Class.new(StandardError)
 
     class Context
       attr_reader :runner, :thread
@@ -12,28 +14,11 @@ module Concurrent
           Thread.abort_on_exception = false
           runner.run
         end
-        #HACK: more consistent on JRuby and Rbx
-        sleep(0.1)
       end
     end
 
     def self.included(base)
 
-      def run!
-        return mutex.synchronize do
-          raise LifecycleError.new('already running') if @running
-          Context.new(self)
-        end
-      end
-
-      protected
-
-      def mutex
-        @mutex ||= Mutex.new
-      end
-
-      public
-
       class << base
 
         def run!(*args, &block)
@@ -44,14 +29,15 @@ module Concurrent
         end
       end
     end
-  end
-
-  module Runnable
-
-    LifecycleError = Class.new(StandardError)
 
-    def self.included(base)
-      base.send(:include, Running)
+    def run!(abort_on_exception = false)
+      raise LifecycleError.new('already running') if @running
+      thread = Thread.new{
+        Thread.current.abort_on_exception = abort_on_exception
+        self.run
+      }
+      Thread.pass
+      return thread
     end
 
     def run
@@ -93,5 +79,11 @@ module Concurrent
     def running?
       return @running == true
     end
+
+    protected
+
+    def mutex
+      @mutex ||= Mutex.new
+    end
   end
 end

data/lib/concurrent/supervisor.rb

@@ -280,7 +280,7 @@ module Concurrent
 
     def exceeded_max_restart_frequency?
       @restart_times.unshift(Time.now.to_i)
-      diff = delta(@restart_times.first, @restart_times.last)
+      diff = (@restart_times.first - @restart_times.last).abs
       if @restart_times.length >= @max_restart && diff <= @max_time
         return true
       elsif diff >= @max_time

data/lib/concurrent/{executor.rb → timer_task.rb}

@@ -1,30 +1,27 @@
 require 'thread'
+require 'observer'
+
 require 'concurrent/runnable'
+require 'concurrent/utilities'
 
 module Concurrent
 
-  class Executor
+  class TimerTask
     include Runnable
+    include Observable
 
     EXECUTION_INTERVAL = 60
     TIMEOUT_INTERVAL = 30
 
-    STDOUT_LOGGER = proc do |name, level, msg|
-      print "%5s (%s) %s: %s\n" % [level.upcase, Time.now.strftime("%F %T"), name, msg]
-    end
-
-    attr_reader :name
     attr_reader :execution_interval
     attr_reader :timeout_interval
 
-    def initialize(name, opts = {}, &block)
+    def initialize(opts = {}, &block)
       raise ArgumentError.new('no block given') unless block_given?
 
-      @name = name
       @execution_interval = opts[:execution] || opts[:execution_interval] || EXECUTION_INTERVAL
       @timeout_interval = opts[:timeout] || opts[:timeout_interval] || TIMEOUT_INTERVAL
       @run_now = opts[:now] || opts[:run_now] || false
-      @logger = opts[:logger] || STDOUT_LOGGER
       @block_args = opts[:args] || opts [:arguments] || []
 
       @task = block
@@ -45,9 +42,7 @@ module Concurrent
     end
     alias_method :terminate, :kill
 
-    def status
-      return @monitor.status unless @monitor.nil?
-    end
+    alias_method :cancel, :stop
 
     protected
 
@@ -72,15 +67,14 @@ module Concurrent
     def execute_task
       @worker = Thread.new do
         Thread.current.abort_on_exception = false
-        @task.call(*@block_args)
-      end
-      if @worker.join(@timeout_interval).nil?
-        @logger.call(@name, :warn, "execution timed out after #{@timeout_interval} seconds")
-      else
-        @logger.call(@name, :info, 'execution completed successfully')
+        Thread.current[:result] = @task.call(*@block_args)
       end
+      raise TimeoutError if @worker.join(@timeout_interval).nil?
+      changed
+      notify_observers(Time.now, @worker[:result], nil)
     rescue Exception => ex
-      @logger.call(@name, :error, "execution failed with error '#{ex}'")
+      changed
+      notify_observers(Time.now, nil, ex)
     ensure
       unless @worker.nil?
         Thread.kill(@worker)

data/lib/concurrent/version.rb

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

data/md/timer_task.md

@@ -0,0 +1,151 @@
+# 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 `TimerTask` class alleviates both problems.
+
+When a TimerTask is launched it starts a thread for monitoring the execution interval.
+The TimerTask thread does not perform the task, however. Instead, the TimerTask
+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 TimerTask thread. The
+TimerTask thread can then log the success or failure of the task. The TimerTask
+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 `TimerTask` 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 a TimerTask for scheduling and running.
+
+The `TimerTask` is the yin to to the
+[Supervisor's](https://github.com/jdantonio/concurrent-ruby/blob/master/md/supervisor.md)
+yang. Where the `Supervisor` is intended to manage long-running threads that operate
+continuously, the `TimerTask` is intended to manage fairly short operations that
+occur repeatedly at regular intervals.
+
+Unlike some of the others concurrency objects in the library, TimerTasks do not
+run on the global thread pool. In my experience the types of tasks that will benefit
+from the `TimerTask` class tend to also be long running. For this reason they get
+their own thread every time the task is executed.
+
+## Observation
+
+`TimerTask` supports notification through the Ruby standard library
+[Observable](http://ruby-doc.org/stdlib-1.9.3/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
+will receive a `Concurrent::TimeoutError` object as the third argument.
+
+## Examples
+
+A basic example:
+
+```ruby
+require 'concurrent'
+
+ec = Concurrent::TimerTask.run{ puts 'Boom!' }
+
+ec.execution_interval #=> 60 == Concurrent::TimerTask::EXECUTION_INTERVAL
+ec.timeout_interval   #=> 30 == Concurrent::TimerTask::TIMEOUT_INTERVAL
+ec.status             #=> "sleep"
+
+# wait 60 seconds...
+#=> 'Boom!'
+
+ec.kill #=> true
+```
+
+Both the execution_interval and the timeout_interval can be configured:
+
+```ruby
+ec = Concurrent::TimerTask.run(execution_interval: 5, timeout_interval: 5) do
+       puts 'Boom!'
+     end
+
+ec.runner.execution_interval #=> 5
+ec.runner.timeout_interval   #=> 5
+```
+
+By default an `TimerTask` 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::TimerTask.run(run_now: true){ puts 'Boom!' }
+#=> 'Boom!''
+ec.thread.status #=> "sleep"
+>> 
+```
+
+A simple example with observation:
+
+```ruby
+class TaskObserver
+  def update(time, result, ex)
+    if result
+      print "(#{time}) Execution successfully returned #{result}\n"
+    elsif ex.is_a?(Concurrent::TimeoutError)
+      print "(#{time}) Execution timed out\n"
+    else
+      print "(#{time}) Execution failed with error #{ex}\n"
+    end
+  end
+end
+
+task = Concurrent::TimerTask.run!(execution_interval: 1, timeout_interval: 1){ 42 }
+task.runner.add_observer(TaskObserver.new)
+
+#=> (2013-10-13 19:08:58 -0400) Execution successfully returned 42
+#=> (2013-10-13 19:08:59 -0400) Execution successfully returned 42
+#=> (2013-10-13 19:09:00 -0400) Execution successfully returned 42
+task.runner.stop
+
+task = Concurrent::TimerTask.run!(execution_interval: 1, timeout_interval: 1){ sleep }
+task.runner.add_observer(TaskObserver.new)
+
+#=> (2013-10-13 19:07:25 -0400) Execution timed out
+#=> (2013-10-13 19:07:27 -0400) Execution timed out
+#=> (2013-10-13 19:07:29 -0400) Execution timed out
+task.runner.stop
+
+task = Concurrent::TimerTask.run!(execution_interval: 1){ raise StandardError }
+task.runner.add_observer(TaskObserver.new)
+
+#=> (2013-10-13 19:09:37 -0400) Execution failed with error StandardError
+#=> (2013-10-13 19:09:38 -0400) Execution failed with error StandardError
+#=> (2013-10-13 19:09:39 -0400) Execution failed with error StandardError
+task.runner.stop
+```
+
+## Copyright
+
+*Concurrent Ruby* is Copyright © 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/fixed_thread_pool_spec.rb

@@ -64,7 +64,7 @@ module Concurrent
       it 'creates new workers when there are none available' do
         pool = FixedThreadPool.new(5)
         pool.length.should eq 0
-        5.times{ sleep(0.1); pool << proc{ sleep } }
+        5.times{ pool << proc{ sleep } }
         sleep(0.1)
         pool.length.should eq 5
         pool.kill
@@ -72,22 +72,11 @@ module Concurrent
 
       it 'never creates more than :max_threads threads' do
         pool = FixedThreadPool.new(5)
-        100.times{ sleep(0.01); pool << proc{ sleep } }
+        100.times{ pool << proc{ sleep } }
         sleep(0.1)
         pool.length.should eq 5
         pool.kill
       end
-
-      it 'creates new threads when garbage collecting' do
-        pool = FixedThreadPool.new(5)
-        pool.length.should == 0
-        pool << proc { sleep }
-        sleep(0.1)
-        pool.length.should == 5
-        pool.instance_variable_set(:@max_threads, 25)
-        pool << proc { sleep }
-        pool.length.should == 25
-      end
     end
 
     context 'exception handling' do

data/spec/concurrent/runnable_spec.rb

@@ -141,33 +141,34 @@ module Concurrent
 
     context 'instance #run!' do
 
-      let(:clazz) do
-        Class.new { include Runnable }
+      after(:each) do
+        @thread.kill if @thread
       end
 
-      subject { clazz.new }
-
-      after(:each) do
-        @context.runner.stop if @context && @context.runner
-        @context.thread.kill if @context && @context.thread
+      it 'raises an exception when already running' do
+        @thread = Thread.new{ subject.run }
+        @thread.join(0.1)
+        expect {
+          @thread = subject.run!
+        }.to raise_exception(Concurrent::Runnable::LifecycleError)
+        sleep(0.1)
       end
 
       it 'creates a new thread' do
-        Thread.should_receive(:new).with(any_args()).and_return(nil)
-        @context = subject.run!
-        sleep(0.1)
+        Thread.should_receive(:new).with(no_args())
+        @thread = subject.run!
       end
 
-      it 'runs the runner on the new thread' do
-        @context = subject.run!
+      it 'calls the #run method on the new thread' do
+        subject.should_receive(:run)
+        @thread = subject.run!
         sleep(0.1)
-        @context.thread.should_not eq Thread.current
       end
 
-      it 'returns a context object on success' do
-        @context = subject.run!
+      it 'returns the new thread' do
+        @thread = subject.run!
         sleep(0.1)
-        @context.should be_a(Running::Context)
+        @thread.should be_a(Thread)
       end
     end
 
@@ -219,7 +220,7 @@ module Concurrent
       it 'returns a context object on success' do
         @context = runnable.run!
         sleep(0.1)
-        @context.should be_a(Running::Context)
+        @context.should be_a(Runnable::Context)
       end
 
       it 'returns nil on failure' do

data/spec/concurrent/thread_pool_shared.rb

@@ -34,6 +34,7 @@ share_examples_for :thread_pool do
 
     it 'stops accepting new tasks' do
       subject.post{ sleep(1) }
+      sleep(0.1)
       subject.shutdown
       @expected = false
       subject.post{ @expected = true }.should be_false

data/spec/concurrent/timer_task_spec.rb

@@ -0,0 +1,195 @@
+require 'spec_helper'
+require_relative 'runnable_shared'
+
+module Concurrent
+
+  describe TimerTask do
+
+    after(:each) do
+      @subject = @subject.runner if @subject.respond_to?(:runner)
+      @subject.kill unless @subject.nil?
+      @thread.kill unless @thread.nil?
+      sleep(0.1)
+    end
+
+    context ':runnable' do
+
+      subject { TimerTask.new{ nil } }
+
+      it_should_behave_like :runnable
+    end
+
+    context 'created with #new' do
+
+      context '#initialize' do
+
+        it 'raises an exception if no block given' do
+          lambda {
+            @subject = Concurrent::TimerTask.new
+          }.should raise_error
+        end
+
+        it 'uses the default execution interval when no interval is given' do
+          @subject = TimerTask.new{ nil }
+          @subject.execution_interval.should eq TimerTask::EXECUTION_INTERVAL
+        end
+
+        it 'uses the default timeout interval when no interval is given' do
+          @subject = TimerTask.new{ nil }
+          @subject.timeout_interval.should eq TimerTask::TIMEOUT_INTERVAL
+        end
+
+        it 'uses the given execution interval' do
+          @subject = TimerTask.new(execution_interval: 5){ nil }
+          @subject.execution_interval.should eq 5
+        end
+
+        it 'uses the given timeout interval' do
+          @subject = TimerTask.new(timeout_interval: 5){ nil }
+          @subject.timeout_interval.should eq 5
+        end
+      end
+
+      context '#kill' do
+        pending
+      end
+    end
+
+    context 'created with TimerTask.run!' do
+
+      context 'arguments' do
+
+        it 'raises an exception if no block given' do
+          lambda {
+            @subject = Concurrent::TimerTask.run
+          }.should raise_error
+        end
+
+        it 'passes the options to the new TimerTask' do
+          opts = {
+            execution_interval: 100,
+            timeout_interval: 100,
+            run_now: false,
+            logger: proc{ nil },
+            block_args: %w[one two three]
+          }
+          @subject = TimerTask.new(opts){ nil }
+          TimerTask.should_receive(:new).with(opts).and_return(@subject)
+          Concurrent::TimerTask.run!(opts)
+        end
+
+        it 'passes the block to the new TimerTask' do
+          @expected = false
+          block = proc{ @expected = true }
+          @subject = TimerTask.run!(run_now: true, &block)
+          sleep(0.1)
+          @expected.should be_true
+        end
+
+        it 'creates a new thread' do
+          thread = Thread.new{ sleep(1) }
+          Thread.should_receive(:new).with(any_args()).and_return(thread)
+          @subject = TimerTask.run!{ nil }
+        end
+      end
+    end
+
+    context 'execution' do
+
+      it 'runs the block immediately when the :run_now option is true' do
+        @expected = false
+        @subject = TimerTask.run!(execution: 500, now: true){ @expected = true }
+        sleep(0.1)
+        @expected.should be_true
+      end
+
+      it 'waits for :execution_interval seconds when the :run_now option is false' do
+        @expected = false
+        @subject = TimerTask.run!(execution: 0.5, now: false){ @expected = true }
+        @expected.should be_false
+        sleep(1)
+        @expected.should be_true
+      end
+
+      it 'waits for :execution_interval seconds when the :run_now option is not given' do
+        @expected = false
+        @subject = TimerTask.run!(execution: 0.5){ @expected = true }
+        @expected.should be_false
+        sleep(1)
+        @expected.should be_true
+      end
+
+      it 'yields to the execution block' do
+        @expected = false
+        @subject = TimerTask.run!(execution: 1){ @expected = true }
+        sleep(2)
+        @expected.should be_true
+      end
+
+      it 'passes any given arguments to the execution block' do
+        args = [1,2,3,4]
+        @expected = nil
+        @subject = TimerTask.new(execution_interval: 0.5, args: args) do |*args|
+          @expected = args
+        end
+        @thread = Thread.new { @subject.run }
+        sleep(1)
+        @expected.should eq args
+      end
+
+      it 'kills the worker thread if the timeout is reached' do
+        # the after(:each) block will trigger this expectation
+        Thread.should_receive(:kill).at_least(1).with(any_args())
+        @subject = TimerTask.new(execution_interval: 0.5, timeout_interval: 0.5){ Thread.stop }
+        @thread = Thread.new { @subject.run }
+        sleep(1.5)
+      end
+    end
+
+    context 'observation' do
+
+      let(:observer) do
+        Class.new do
+          attr_reader :time
+          attr_reader :value
+          attr_reader :ex
+          define_method(:update) do |time, value, ex|
+            @time = time
+            @value = value
+            @ex = ex
+          end
+        end.new
+      end
+
+      it 'notifies all observers on success' do
+        task = TimerTask.new(run_now: true){ sleep(0.1); 42 }
+        task.add_observer(observer)
+        Thread.new{ task.run }
+        sleep(1)
+        observer.value.should == 42
+        observer.ex.should be_nil
+        task.kill
+      end
+
+      it 'notifies all observers on timeout' do
+        task = TimerTask.new(run_now: true, timeout: 1){ sleep }
+        task.add_observer(observer)
+        Thread.new{ task.run }
+        sleep(2)
+        observer.value.should be_nil
+        observer.ex.should be_a(Concurrent::TimeoutError)
+        task.kill
+      end
+
+      it 'notifies all observers on error' do
+        task = TimerTask.new(run_now: true){ sleep(0.1); raise ArgumentError }
+        task.add_observer(observer)
+        Thread.new{ task.run }
+        sleep(1)
+        observer.value.should be_nil
+        observer.ex.should be_a(ArgumentError)
+        task.kill
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: concurrent-ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.0.pre.2
+  version: 0.3.0.pre.3
 platform: ruby
 authors:
 - Jerry D'Antonio
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-13 00:00:00.000000000 Z
+date: 2013-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -42,7 +42,6 @@ files:
 - lib/concurrent/cached_thread_pool.rb
 - lib/concurrent/event.rb
 - lib/concurrent/event_machine_defer_proxy.rb
-- lib/concurrent/executor.rb
 - lib/concurrent/fixed_thread_pool/worker.rb
 - lib/concurrent/fixed_thread_pool.rb
 - lib/concurrent/future.rb
@@ -52,25 +51,25 @@ files:
 - lib/concurrent/promise.rb
 - lib/concurrent/runnable.rb
 - lib/concurrent/supervisor.rb
+- lib/concurrent/timer_task.rb
 - lib/concurrent/utilities.rb
 - lib/concurrent/version.rb
 - lib/concurrent.rb
 - lib/concurrent_ruby.rb
 - md/agent.md
 - md/event.md
-- md/executor.md
 - md/future.md
 - md/goroutine.md
 - md/obligation.md
 - md/promise.md
 - md/supervisor.md
 - md/thread_pool.md
+- md/timer_task.md
 - spec/concurrent/actor_spec.rb
 - spec/concurrent/agent_spec.rb
 - spec/concurrent/cached_thread_pool_spec.rb
 - spec/concurrent/event_machine_defer_proxy_spec.rb
 - spec/concurrent/event_spec.rb
-- spec/concurrent/executor_spec.rb
 - spec/concurrent/fixed_thread_pool_spec.rb
 - spec/concurrent/future_spec.rb
 - spec/concurrent/global_thread_pool_spec.rb
@@ -81,6 +80,7 @@ files:
 - spec/concurrent/runnable_spec.rb
 - spec/concurrent/supervisor_spec.rb
 - spec/concurrent/thread_pool_shared.rb
+- spec/concurrent/timer_task_spec.rb
 - spec/concurrent/uses_global_thread_pool_shared.rb
 - spec/concurrent/utilities_spec.rb
 - spec/spec_helper.rb
@@ -119,7 +119,6 @@ test_files:
 - spec/concurrent/cached_thread_pool_spec.rb
 - spec/concurrent/event_machine_defer_proxy_spec.rb
 - spec/concurrent/event_spec.rb
-- spec/concurrent/executor_spec.rb
 - spec/concurrent/fixed_thread_pool_spec.rb
 - spec/concurrent/future_spec.rb
 - spec/concurrent/global_thread_pool_spec.rb
@@ -130,6 +129,7 @@ test_files:
 - spec/concurrent/runnable_spec.rb
 - spec/concurrent/supervisor_spec.rb
 - spec/concurrent/thread_pool_shared.rb
+- spec/concurrent/timer_task_spec.rb
 - spec/concurrent/uses_global_thread_pool_shared.rb
 - spec/concurrent/utilities_spec.rb
 - spec/spec_helper.rb

data/md/executor.md

@@ -1,193 +0,0 @@
-# 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.
-
-The `Executor` is the yin to to the
-[Supervisor's](https://github.com/jdantonio/concurrent-ruby/blob/master/md/supervisor.md)
-yang. Where the `Supervisor` is intended to manage long-running threads that operate
-continuously, the `Executor` is intended to manage fairly short operations that
-occur repeatedly at regular intervals.
-
-Unlike some of the others concurrency objects in the library, executors do not
-run on the global thread pool. 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/spec/concurrent/executor_spec.rb

@@ -1,240 +0,0 @@
-require 'spec_helper'
-require_relative 'runnable_shared'
-
-module Concurrent
-
-  describe Executor do
-
-    before(:each) do
-      @orig_stdout = $stdout
-      $stdout = StringIO.new 
-    end
-
-    after(:each) do
-      $stdout = @orig_stdout
-    end
-
-    after(:each) do
-      @subject = @subject.runner if @subject.respond_to?(:runner)
-      @subject.kill unless @subject.nil?
-      @thread.kill unless @thread.nil?
-      sleep(0.1)
-    end
-
-    context ':runnable' do
-
-      subject { Executor.new(':runnable'){ nil } }
-
-      it_should_behave_like :runnable
-    end
-
-    context 'created with #new' do
-
-      context '#initialize' do
-
-        it 'raises an exception if no block given' do
-          lambda {
-            @subject = Concurrent::Executor.new('Foo')
-          }.should raise_error
-        end
-
-        it 'uses the default execution interval when no interval is given' do
-          @subject = Executor.new('Foo'){ nil }
-          @subject.execution_interval.should eq Executor::EXECUTION_INTERVAL
-        end
-
-        it 'uses the default timeout interval when no interval is given' do
-          @subject = Executor.new('Foo'){ nil }
-          @subject.timeout_interval.should eq Executor::TIMEOUT_INTERVAL
-        end
-
-        it 'uses the given execution interval' do
-          @subject = Executor.new('Foo', execution_interval: 5){ nil }
-          @subject.execution_interval.should eq 5
-        end
-
-        it 'uses the given timeout interval' do
-          @subject = Executor.new('Foo', timeout_interval: 5){ nil }
-          @subject.timeout_interval.should eq 5
-        end
-
-        it 'sets the #name context variable' do
-          @subject = Executor.new('Foo'){ nil }
-          @subject.name.should eq 'Foo'
-        end
-      end
-
-      context '#kill' do
-        pending
-      end
-
-      context '#status' do
-
-        subject { Executor.new('Foo'){ nil } }
-
-        it 'returns the status of the executor thread when running' do
-          @thread = Thread.new { subject.run }
-          sleep(0.1)
-          subject.status.should eq 'sleep'
-        end
-
-        it 'returns nil when not running' do
-          subject.status.should be_nil
-        end
-      end
-    end
-
-    context 'created with Executor.run!' do
-
-      context 'arguments' do
-
-        it 'raises an exception if no block given' do
-          lambda {
-            @subject = Concurrent::Executor.run('Foo')
-          }.should raise_error
-        end
-
-        it 'passes the name to the new Executor' do
-          @subject = Executor.new('Foo'){ nil }
-          Executor.should_receive(:new).with('Foo').and_return(@subject)
-          Concurrent::Executor.run!('Foo')
-        end
-
-        it 'passes the options to the new Executor' do
-          opts = {
-            execution_interval: 100,
-            timeout_interval: 100,
-            run_now: false,
-            logger: proc{ nil },
-            block_args: %w[one two three]
-          }
-          @subject = Executor.new('Foo', opts){ nil }
-          Executor.should_receive(:new).with(anything(), opts).and_return(@subject)
-          Concurrent::Executor.run!('Foo', opts)
-        end
-
-        it 'passes the block to the new Executor' do
-          @expected = false
-          block = proc{ @expected = true }
-          @subject = Executor.run!('Foo', run_now: true, &block)
-          sleep(0.1)
-          @expected.should be_true
-        end
-
-        it 'creates a new thread' do
-          thread = Thread.new{ sleep(1) }
-          Thread.should_receive(:new).with(any_args()).and_return(thread)
-          @subject = Executor.run!('Foo'){ nil }
-        end
-      end
-
-      context 'execution' do
-
-        it 'runs the block immediately when the :run_now option is true' do
-          @expected = false
-          @subject = Executor.run!('Foo', execution: 500, now: true){ @expected = true }
-          sleep(0.1)
-          @expected.should be_true
-        end
-
-        it 'waits for :execution_interval seconds when the :run_now option is false' do
-          @expected = false
-          @subject = Executor.run!('Foo', execution: 0.5, now: false){ @expected = true }
-          @expected.should be_false
-          sleep(1)
-          @expected.should be_true
-        end
-
-        it 'waits for :execution_interval seconds when the :run_now option is not given' do
-          @expected = false
-          @subject = Executor.run!('Foo', execution: 0.5){ @expected = true }
-          @expected.should be_false
-          sleep(1)
-          @expected.should be_true
-        end
-
-        it 'yields to the execution block' do
-          @expected = false
-          @subject = Executor.run!('Foo', execution: 1){ @expected = true }
-          sleep(2)
-          @expected.should be_true
-        end
-
-        it 'passes any given arguments to the execution block' do
-          args = [1,2,3,4]
-          @expected = nil
-          @subject = Executor.new('Foo', execution_interval: 0.5, args: args) do |*args|
-            @expected = args
-          end
-          @thread = Thread.new { @subject.run }
-          sleep(1)
-          @expected.should eq args
-        end
-
-        it 'kills the worker thread if the timeout is reached' do
-          # the after(:each) block will trigger this expectation
-          Thread.should_receive(:kill).at_least(1).with(any_args())
-          @subject = Executor.new('Foo', execution_interval: 0.5, timeout_interval: 0.5){ Thread.stop }
-          @thread = Thread.new { @subject.run }
-          sleep(1.5)
-        end
-      end
-
-      context '#status' do
-
-        it 'returns the status of the executor thread when running' do
-          @subject = Executor.run!('Foo'){ nil }
-          sleep(0.1)
-          @subject.runner.status.should eq 'sleep'
-        end
-
-        it 'returns nil when not running' do
-          @subject = Executor.new('Foo'){ nil }
-          sleep(0.1)
-          @subject.kill
-          sleep(0.1)
-          @subject.status.should be_nil
-        end
-      end
-    end
-
-    context 'logging' do
-
-      before(:each) do
-        @name = nil
-        @level = nil
-        @msg = nil
-
-        @logger = proc do |name, level, msg|
-          @name = name
-          @level = level
-          @msg = msg
-        end
-      end
-
-      it 'uses a custom logger when given' do
-        @subject = Executor.run!('Foo', execution_interval: 0.1, logger: @logger){ nil }
-        sleep(0.5)
-        @name.should eq 'Foo'
-      end
-
-      it 'logs :info when execution is successful' do
-        @subject = Executor.run!('Foo', execution_interval: 0.1, logger: @logger){ nil }
-        sleep(0.5)
-        @level.should eq :info
-      end
-
-      it 'logs :warn when execution times out' do
-        @subject = Executor.run!('Foo', execution_interval: 0.1, timeout_interval: 0.1, logger: @logger){ Thread.stop }
-        sleep(0.5)
-        @level.should eq :warn
-      end
-
-      it 'logs :error when execution is fails' do
-        @subject = Executor.run!('Foo', execution_interval: 0.1, logger: @logger){ raise StandardError }
-        sleep(0.5)
-        @level.should eq :error
-      end
-    end
-  end
-end