thread_storm 0.5.1 → 0.7.0

data/lib/thread_storm.rb

@@ -1,55 +1,126 @@
 require "thread"
 require "timeout"
 require "thread_storm/active_support"
-require "thread_storm/sentinel"
+require "thread_storm/queue"
 require "thread_storm/execution"
 require "thread_storm/worker"
 
+# Simple but powerful thread pool implementation.
 class ThreadStorm
   
+  class TimeoutError < Exception; end
+  
+  # Version of ThreadStorm that you are using.
+  VERSION = File.read(File.dirname(__FILE__)+"/../VERSION").chomp
+  
+  # Default options found in ThreadStorm.options.
+  DEFAULTS = { :size => 2,
+               :execute_blocks => false,
+               :timeout => nil,
+               :timeout_method => Timeout.method(:timeout),
+               :timeout_exception => Timeout::Error,
+               :default_value => nil,
+               :reraise => true }.freeze
+  
+  @options = DEFAULTS.dup
+  metaclass.class_eval do
+    # Global options.
+    attr_reader :options
+  end
+  
+  # Options specific to a ThreadStorm instance.
+  attr_reader :options
+  
   # Array of executions in order as they are defined by calls to ThreadStorm#execute.
   attr_reader :executions
   
-  # Valid options are
-  #   :size => How many threads to spawn.  Default is 2.
-  #   :timeout => Max time an execution is allowed to run before terminating it.  Default is nil (no timeout).
-  #   :timeout_method => An object that implements something like Timeout.timeout via #call.  Default is Timeout.method(:timeout).
-  #   :default_value => Value of an execution if it times out or errors.  Default is nil.
-  #   :reraise => True if you want exceptions reraised when ThreadStorm#join is called.  Default is true.
-  #   :execute_blocks => True if you want #execute to block until there is an available thread.  Default is false.
+  # call-seq:
+  #   new(options = {}) -> thread_storm
+  #   new(options = {}){ |self| ... } -> thread_storm
+  #
+  # Valid _options_ are...
+  #   :size => How many threads to spawn.
+  #   :timeout => Max time an execution is allowed to run before terminating it.  Nil means no timeout.
+  #   :timeout_method => An object that implements something like Timeout.timeout via #call..
+  #   :default_value => Value of an execution if it times out or errors..
+  #   :reraise => True if you want exceptions to be reraised when ThreadStorm#join is called.
+  #   :execute_blocks => True if you want #execute to block until there is an available thread.
+  #
+  # For defaults, see DEFAULTS.
+  #
+  # When given a block, ThreadStorm#join and ThreadStorm#shutdown are called for you.  In other words...
+  #   ThreadStorm.new do |storm|
+  #     storm.execute{ sleep(1) }
+  #   end
+  # ...is the same as...
+  #   storm = ThreadStorm.new
+  #   storm.execute{ sleep(1) }
+  #   storm.join
+  #   storm.shutdown
   def initialize(options = {})
-    @options = options.option_merge :size => 2,
-                                    :timeout => nil,
-                                    :timeout_method => Timeout.method(:timeout),
-                                    :default_value => nil,
-                                    :reraise => true,
-                                    :execute_blocks => false
-    @sentinel = Sentinel.new
-    @queue = []
+    @options = options.reverse_merge(self.class.options)
+    @queue = Queue.new(@options[:size], @options[:execute_blocks])
     @executions = []
-    @workers = (1..@options[:size]).collect{ Worker.new(@queue, @sentinel, @options) }
+    @workers = (1..@options[:size]).collect{ Worker.new(@queue) }
+    run{ yield(self) } if block_given?
+  end
+  
+  # This is like Execution.new except the default options are specific this ThreadStorm instance.
+  #   ThreadStorm.options[:timeout]
+  #   # => nil
+  #   storm = ThreadStorm.new :timeout => 1
+  #   execution = storm.new_execution
+  #   execution.options[:timeout]
+  #   # => 1
+  #   execution = ThreadStorm::Execution.new
+  #   execution.options[:timeout]
+  #   # => nil
+  def new_execution(*args, &block)
+    
+    # It has to be this way because of how options are merged.
+    
     if block_given?
-      yield(self)
-      join
-      shutdown
+      Execution.new(options.dup).define(*args, &block)
+    elsif args.length == 0
+      Execution.new(options.dup)
+    elsif args.length == 1 and args.first.kind_of?(Hash)
+      Execution.new(options.merge(args.first))
+    else
+      raise ArgumentError, "illegal call-seq"
     end
   end
   
-  def size #:nodoc:
-    @options[:size]
+  def run
+    yield(self)
+    join
+    shutdown
   end
   
-  # Creates an execution and schedules it to be run by the thread pool.
-  # Return value is a ThreadStorm::Execution.
+  # call-seq:
+  #   storm.execute(*args){ |*args| ... } -> execution
+  #   storm.execute(execution) -> execution
+  #
+  # Schedules an execution to be run (i.e. moves it to the :queued state).
+  # When given a block, it is the same as
+  #   execution = ThreadStorm::Execution.new(*args){ |*args| ... }
+  #   storm.execute(execution)
   def execute(*args, &block)
-    Execution.new(args, default_value, &block).tap do |execution|
-      @sentinel.synchronize do |e_cond, p_cond|
-        e_cond.wait_while{ all_workers_busy? } if execute_blocks?
-        @queue << execution
-        @executions << execution
-        p_cond.signal
-      end
+    if block_given?
+      execution = new_execution(*args, &block)
+    elsif args.length == 1 and args.first.instance_of?(Execution)
+      execution = args.first
+    else
+      raise ArgumentError, "execution or arguments and block expected"
+    end
+    
+    @queue.synchronize do |q|
+      q.enqueue(execution)
+      execution.queued! # This needs to be in here or we'll get a race condition to set the execution's state.
     end
+    
+    @executions << execution
+    
+    execution
   end
   
   # Block until all pending executions are finished running.
@@ -57,7 +128,6 @@ class ThreadStorm
   def join
     @executions.each do |execution|
       execution.join
-      raise execution.exception if execution.exception and reraise?
     end
   end
   
@@ -69,19 +139,11 @@ class ThreadStorm
   # Signals the worker threads to terminate immediately (ignoring any pending
   # executions) and blocks until they do.
   def shutdown
-    @sentinel.synchronize do |e_cond, p_cond|
-      @queue.replace([:die] * size)
-      p_cond.broadcast
-    end
-    @workers.each{ |worker| worker.thread.join }
+    @queue.shutdown
+    threads.each{ |thread| thread.join }
     true
   end
   
-  # Returns workers that are currently running executions.
-  def busy_workers
-    @workers.select{ |worker| worker.busy? }
-  end
-  
   # Returns an array of Ruby threads in the pool.
   def threads
     @workers.collect{ |worker| worker.thread }
@@ -108,22 +170,4 @@ class ThreadStorm
     cleared
   end
   
-private
-  
-  def default_value #:nodoc:
-    @options[:default_value]
-  end
-  
-  def reraise? #:nodoc:
-    @options[:reraise]
-  end
-  
-  def execute_blocks? #:nodoc:
-    @options[:execute_blocks]
-  end
-  
-  def all_workers_busy? #:nodoc:
-    @workers.all?{ |worker| worker.busy? }
-  end
-  
 end

data/test/helper.rb

@@ -5,6 +5,7 @@ require "set"
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 $LOAD_PATH.unshift(File.dirname(__FILE__))
 require 'thread_storm'
+require 'timecop'
 
 class Test::Unit::TestCase
   

data/test/test_callbacks.rb

@@ -0,0 +1,49 @@
+require 'helper'
+
+class TestCallbacks < Test::Unit::TestCase
+  
+  # The general premise of this test is that we assign a callback to increment
+  # this counter when we enter each state.
+  def test_state_callbacks
+    counter = 0
+    callback = Proc.new{ counter += 1 }
+    
+    storm = ThreadStorm.new
+    execution = storm.new_execution{ "done" }
+    assert_equal 0, counter
+    execution.options.merge! :queued_callback      => callback,
+                             :started_callback     => callback,
+                             :finished_callback    => callback
+        
+    execution.queued!
+    assert_equal 1, counter
+    
+    execution.execute
+    assert_equal 3, counter
+  end
+  
+  def test_callback_exception
+    storm = ThreadStorm.new :size => 1
+    storm.options[:queued_callback] = Proc.new{ raise RuntimeError, "oops" }
+    e = storm.execute{ "success" }
+    storm.join
+    assert_equal false, e.exception?
+    assert_equal "success", e.value
+    assert_equal true, e.callback_exception?
+    assert_equal false, e.callback_exception?(:started)
+    assert_equal true, e.callback_exception?(:queued)
+    assert_equal RuntimeError, e.callback_exception(:queued).class
+    assert_equal "oops", e.callback_exception(:queued).message
+    assert storm.threads.all?{ |thread| thread.alive? }
+  end
+  
+  def test_initialized_callback
+    counter  = 0
+    callback = Proc.new{ counter += 1 }
+    
+    assert_equal 0, counter
+    execution = ThreadStorm::Execution.new :initialized_callback => callback
+    assert_equal 1, counter
+  end
+  
+end

data/test/test_execution.rb

@@ -0,0 +1,147 @@
+require 'helper'
+
+class TestExecution < Test::Unit::TestCase
+  
+  def setup
+    @sign = nil
+    @lock = Monitor.new
+    @cond = @lock.new_cond
+  end
+  
+  def new_execution(*args, &block)
+    block = Proc.new{ nil } unless block_given?
+    ThreadStorm::Execution.new(*args, &block).tap do |execution|
+      execution.options.replace :timeout => nil,
+                                :timeout_method => Proc.new{ |seconds, &block| Timeout.timeout(seconds, ThreadStorm::TimeoutError, &block) },
+                                :timeout_exception => ThreadStorm::TimeoutError,
+                                :default_value => nil,
+                                :reraise => false
+    end
+  end
+  
+  def wait_until_sign(i)
+    @lock.synchronize do
+      @cond.wait_until{ @sign == i }
+    end
+  end
+  
+  def set_sign(i)
+    @lock.synchronize do
+      @sign = i
+      @cond.signal
+    end
+  end
+  
+  def test_execute
+    execution = new_execution{ 1 }
+    execution.execute
+    assert ! execution.exception?
+    assert ! execution.timeout?
+    assert_equal 1, execution.value
+  end
+  
+  def test_exception
+    execution = new_execution{ raise RuntimeError, "blah"; 1 }
+    execution.options[:default_value] = 2
+    execution.execute
+    assert execution.exception?
+    assert ! execution.timeout?
+    assert_equal 2, execution.value
+  end
+  
+  def test_timeout
+    execution = new_execution{ sleep(1); 1 }
+    execution.options.merge! :default_value => 2,
+                             :timeout => 0.001
+    execution.execute
+    assert ! execution.exception?
+    assert execution.timeout?
+    assert execution.exception.kind_of?(ThreadStorm::TimeoutError)
+    assert_equal 2, execution.value
+  end
+  
+  def test_timeout_exception
+    timeout_exception = Class.new(RuntimeError)
+    execution = new_execution{ sleep(1); 1 }
+    execution.options.merge! :default_value => 2,
+                             :timeout => 0.001,
+                             :timeout_method => Proc.new{ |secs, &block| Timeout.timeout(secs, timeout_exception){ block.call } },
+                             :timeout_exception => timeout_exception
+    execution.execute
+    assert ! execution.exception?
+    assert execution.timeout?
+    assert execution.exception.kind_of?(timeout_exception)
+    assert_equal 2, execution.value
+  end
+  
+  def test_states
+    execution = new_execution do
+      set_sign(1)
+      wait_until_sign(2)
+    end
+    
+    assert_equal :initialized, execution.state(:sym)
+    
+    execution.queued!
+    assert_equal :queued, execution.state(:sym)
+    
+    Thread.new{ execution.execute }
+    wait_until_sign(1)
+    assert_equal :started, execution.state(:sym)
+    
+    set_sign(2)
+    execution.join
+    assert_equal :finished, execution.state(:sym)
+  end
+  
+  def test_duration
+    time, execution = Time.now, nil
+    Timecop.freeze(time){ execution = ThreadStorm::Execution.new{ "done" } }
+    Timecop.freeze(time += 1){ execution.queued! }
+    assert_equal 1, execution.duration(:initialized)
+    
+    # The queued state is still going on, so the duration should change each time we call it.
+    Timecop.freeze(time += 2){ assert_equal 2, execution.duration(:queued) }
+    Timecop.freeze(time += 3){ assert_equal 5, execution.duration(:queued) }
+    
+    # Make sure duration doesn't crash if we call it for a state that hasn't started yet.
+    assert_equal nil, execution.duration(:started)
+    
+    # The execution has been in the queued state for 5 seconds already (see above).
+    Timecop.freeze(time += 4){ execution.execute }
+    assert_equal 9, execution.duration(:queued)
+  end
+  
+  def test_duration_with_skipped_states
+    time, execution = Time.now, nil
+    Timecop.freeze(time){ execution = ThreadStorm::Execution.new{ "done" } }
+    Timecop.freeze(time += 5){ execution.execute } # Skip over the queued state.
+    assert_equal 5, execution.duration(:initialized)
+    assert_equal nil, execution.duration(:queued)
+  end
+  
+  def test_reraise
+    klass = Class.new(RuntimeError)
+    
+    execution = new_execution{ nil }
+    execution.options[:reraise] = true
+    execution.execute
+    assert_nothing_raised{ execution.join }
+    
+    execution = new_execution{ raise klass }
+    execution.options[:reraise] = true
+    execution.execute
+    assert_raise(klass){ execution.join }
+  end
+  
+  def test_new_with_options
+    old_options = ThreadStorm.options.dup
+    ThreadStorm.options[:timeout] = 10
+    execution = ThreadStorm::Execution.new
+    assert_equal 10, execution.options[:timeout]
+    execution = ThreadStorm::Execution.new :timeout => 5
+    assert_equal 5, execution.options[:timeout]
+    ThreadStorm.options.replace(old_options) # Be sure to restore to previous state.
+  end
+  
+end