concurrent-ruby 0.1.1.pre.5 → 0.1.1

data/md/executor.md

@@ -1,176 +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.
-
-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
-```
-
-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,200 +0,0 @@
-require 'spec_helper'
-
-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
-      @ec.kill unless @ec.nil?
-    end
-
-    context '#run' do
-
-      it 'raises an exception if no block given' do
-        lambda {
-          @ec = Concurrent::Executor.run('Foo')
-        }.should raise_error
-      end
-
-      it 'uses the default execution interval when no interval is given' do
-        @ec = Executor.run('Foo'){ nil }
-        @ec.execution_interval.should eq Executor::EXECUTION_INTERVAL
-      end
-
-      it 'uses the default timeout interval when no interval is given' do
-        @ec = Executor.run('Foo'){ nil }
-        @ec.timeout_interval.should eq Executor::TIMEOUT_INTERVAL
-      end
-
-      it 'uses the given execution interval' do
-        @ec = Executor.run('Foo', execution_interval: 5){ nil }
-        @ec.execution_interval.should eq 5
-      end
-
-      it 'uses the given timeout interval' do
-        @ec = Executor.run('Foo', timeout_interval: 5){ nil }
-        @ec.timeout_interval.should eq 5
-      end
-
-      it 'creates a new thread' do
-        thread = Thread.new{ sleep(1) }
-        Thread.should_receive(:new).with(any_args()).and_return(thread)
-        @ec = Executor.run('Foo'){ nil }
-      end
-
-      it 'returns an ExecutionContext' do
-        @ec = Executor.run('Foo'){ nil }
-        @ec.should be_a(Executor::ExecutionContext)
-      end
-
-      it 'sets the #name context variable' do
-        @ec = Executor.run('Foo'){ nil }
-        @ec.name.should eq 'Foo'
-      end
-    end
-
-    context 'execution' do
-
-      it 'runs the block immediately when the :run_now option is true' do
-        @expected = false
-        @ec = Executor.run('Foo', execution: 500, now: true){ @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 false' do
-        @expected = false
-        @ec = 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
-        @ec = 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
-        @ec = 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
-        @ec = Executor.run('Foo', execution_interval: 0.5, args: args) do |*args|
-          @expected = args
-        end
-        sleep(1)
-        @expected.should eq args
-      end
-
-      it 'supresses exceptions thrown by the execution block' do
-        lambda {
-          @ec = Executor.run('Foo', execution_interval: 0.5) { raise StandardError }
-          sleep(1)
-        }.should_not raise_error
-      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())
-        @ec = Executor.run('Foo', execution_interval: 0.5, timeout_interval: 0.5){ Thread.stop }
-        sleep(1.5)
-      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
-        @ec = 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
-        @ec = 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
-        @ec = 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
-        @ec = Executor.run('Foo', execution_interval: 0.1, logger: @logger){ raise StandardError }
-        sleep(0.5)
-        @level.should eq :error
-      end
-    end
-
-    context '#status' do
-
-      it 'returns the status of the executor thread when running' do
-        @ec = Executor.run('Foo'){ nil }
-        sleep(0.1)
-        @ec.status.should eq 'sleep'
-      end
-
-      it 'returns nil when not running' do
-        @ec = Executor.run('Foo'){ nil }
-        @ec.kill
-        sleep(0.1)
-        @ec.status.should be_nil
-      end
-    end
-
-    context '#join' do
-
-      it 'joins the executor thread when running' do
-        @ec = Executor.run('Foo'){ nil }
-        Thread.new{ sleep(1); @ec.kill }
-        @ec.join.should be_a(Thread)
-      end
-
-      it 'joins the executor thread with timeout when running' do
-        @ec = Executor.run('Foo'){ nil }
-        @ec.join(1).should be_nil
-      end
-
-      it 'immediately returns nil when not running' do
-        @ec = Executor.run('Foo'){ nil }
-        @ec.kill
-        sleep(0.1)
-        @ec.join.should be_nil
-        @ec.join(1).should be_nil
-      end
-    end
-  end
-end

data/spec/concurrent/functions_spec.rb

@@ -1,217 +0,0 @@
-require 'spec_helper'
-
-module Concurrent
-
-  describe 'functions' do
-
-    context '#post' do
-
-      it 'calls #post when supported by the object' do
-        object = Class.new{
-          def post() nil; end
-        }.new
-        object.should_receive(:post).with(no_args())
-        post(object){ nil }
-      end
-
-      it 'raises an exception when not supported by the object' do
-        object = Class.new{ }.new
-        lambda {
-          post(object){ nil }
-        }.should raise_error(ArgumentError)
-      end
-    end
-
-    context '#deref' do
-
-      it 'returns the value of the #deref function' do
-        object = Class.new{
-          def deref() nil; end
-        }.new
-        object.should_receive(:deref).with(nil)
-        deref(object, nil){ nil }
-      end
-
-      it 'returns the value of the #value function' do
-        object = Class.new{
-          def value() nil; end
-        }.new
-        object.should_receive(:value).with(nil)
-        deref(object, nil){ nil }
-      end
-
-      it 'raises an exception when not supported by the object' do
-        object = Class.new{ }.new
-        lambda {
-          deref(object, nil){ nil }
-        }.should raise_error(ArgumentError)
-      end
-    end
-
-    context '#pending?' do
-
-      it 'returns the value of the #pending? function' do
-        object = Class.new{
-          def pending?() nil; end
-        }.new
-        object.should_receive(:pending?).with(no_args())
-        pending?(object){ nil }
-      end
-
-      it 'raises an exception when not supported by the object' do
-        object = Class.new{ }.new
-        lambda {
-          pending?(object){ nil }
-        }.should raise_error(ArgumentError)
-      end
-    end
-
-    context '#fulfilled?' do
-
-      it 'returns the value of the #fulfilled? function' do
-        object = Class.new{
-          def fulfilled?() nil; end
-        }.new
-        object.should_receive(:fulfilled?).with(no_args())
-        fulfilled?(object){ nil }
-      end
-
-      it 'returns the value of the #realized? function' do
-        object = Class.new{
-          def realized?() nil; end
-        }.new
-        object.should_receive(:realized?).with(no_args())
-        fulfilled?(object){ nil }
-      end
-
-      it 'raises an exception when not supported by the object' do
-        object = Class.new{ }.new
-        lambda {
-          fulfilled?(object){ nil }
-        }.should raise_error(ArgumentError)
-      end
-    end
-
-    context '#realized?' do
-
-      it 'returns the value of the #realized? function' do
-        object = Class.new{
-          def realized?() nil; end
-        }.new
-        object.should_receive(:realized?).with(no_args())
-        realized?(object){ nil }
-      end
-
-      it 'returns the value of the #fulfilled? function' do
-        object = Class.new{
-          def fulfilled?() nil; end
-        }.new
-        object.should_receive(:fulfilled?).with(no_args())
-        realized?(object){ nil }
-      end
-
-      it 'raises an exception when not supported by the object' do
-        object = Class.new{ }.new
-        lambda {
-          realized?(object){ nil }
-        }.should raise_error(ArgumentError)
-      end
-    end
-
-    context '#rejected?' do
-
-      it 'returns the value of the #rejected? function' do
-        object = Class.new{
-          def rejected?() nil; end
-        }.new
-        object.should_receive(:rejected?).with(no_args())
-        rejected?(object){ nil }
-      end
-
-      it 'raises an exception when not supported by the object' do
-        object = Class.new{ }.new
-        lambda {
-          rejected?(object){ nil }
-        }.should raise_error(ArgumentError)
-      end
-    end
-  end
-
-  describe Agent do
-
-    before(:each) do
-      Agent.thread_pool = FixedThreadPool.new(1)
-    end
-
-    it 'aliases #<< for Agent#post' do
-      subject = Agent.new(0)
-      subject << proc{ 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
-      subject = Agent.new(0)
-      post(subject){ 100 }
-      sleep(0.1)
-      subject.value.should eq 100
-    end
-  end
-
-  describe Defer do
-
-    before(:each) do
-      Defer.thread_pool = FixedThreadPool.new(1)
-    end
-
-    it 'aliases Kernel#defer' do
-      defer{ nil }.should be_a(Defer)
-    end
-  end
-
-  describe Executor do
-
-    it 'aliases Kernel#executor' do
-      ex = executor('executor'){ nil }
-      ex.should be_a(Executor::ExecutionContext)
-      ex.kill
-    end
-  end
-
-  describe Future do
-
-    before(:each) do
-      Future.thread_pool = FixedThreadPool.new(1)
-    end
-
-    it 'aliases Kernel#future for Future.new' do
-      future().should be_a(Future)
-      future(){ nil }.should be_a(Future)
-      future(1, 2, 3).should be_a(Future)
-      future(1, 2, 3){ nil }.should be_a(Future)
-    end
-  end
-
-  describe Promise do
-
-    before(:each) do
-      Promise.thread_pool = FixedThreadPool.new(1)
-    end
-
-    it 'aliases Kernel#promise for Promise.new' do
-      promise().should be_a(Promise)
-      promise(){ nil }.should be_a(Promise)
-      promise(1, 2, 3).should be_a(Promise)
-      promise(1, 2, 3){ nil }.should be_a(Promise)
-    end
-  end
-end