thread_storm 0.5.1 → 0.7.0

data/CHANGELOG

@@ -1,3 +1,15 @@
+0.6.0
+ - Fixed a bug with the :execute_blocks option.
+ - ThreadStorm::Execution#options (options specific to an execution).
+ - Added ThreadStorm#options (options specific to a ThreadStorm instance).
+ - Added ThreadStorm.options (global options).
+ - Removed ThreadStorm#size.
+ - Removed ThreadStorm#busy_workers.
+ - ThreadStorm#execution can now take an execution instance.
+ - ThreadStorm::Execution.new creates an execution in the :new state.
+ - Execution states (:new, :queued, :started, :finished)
+ - Changed Execution#duration to return nil if the execution is not in the :started or :finished state.
+
 0.5.1
  - Fixed crash when calling Execution#duration before it has started.
  - ThreadStorm#clear_executions can now take no arguments at all.

data/README.rdoc

@@ -4,6 +4,8 @@ Simple thread pool with a few advanced features.
 
 == Features
 
+Some notable features.
+
   * execution state querying
   * timeouts and configurable timeout implementation
   * graceful error handling
@@ -11,6 +13,8 @@ Simple thread pool with a few advanced features.
 
 == Example
 
+A simple example to get you started.
+
   storm = ThreadStorm.new :size => 2
   storm.execute{ sleep(0.01); "a" }
   storm.execute{ sleep(0.01); "b" }
@@ -24,29 +28,49 @@ You can query the state of an execution.
 
   storm = ThreadStorm.new :size => 2
   execution = storm.execute{ sleep(0.01); "a" }
-  storm.execute{ sleep(0.01); "b" }
-  storm.execute{ sleep(0.01); "c" }
-  storm.join
-  execution.started?   # true
-  execution.finished?  # true
-  execution.timed_out? # false
-  execution.duration   # ~0.01
-  execution.value      # "a"
+  execution.join
+  execution.finished? # true
+
+
+An execution can be in one of 4 states at any given time: +initialized+, +queued+, +started+, +finished+
+
+Initialized means the execution has been created, but not yet scheduled to be run by the thread pool (i.e. ThreadStorm#execute hasn't been called on it yet).
+
+Queued means the execution has been scheduled to run, but there are no free threads available to run it yet.
+
+Started means that it is currently running on a thread.
+
+Finished means it has completed running.
+
+== Execution status
+
+You can query the status of an execution.
+
+  storm = ThreadStorm.new :size => 2
+  execution = storm.execute{ sleep(0.01); "a" }
+  execution.join
+  execution.success? # true
+  execution.failure? # false
+  execution.timeout? # false
+
+An execution can have one of three statuses after it has entered the +finished+ state: +success+, +failure+, +timeout+
+
+Success means it finished without raising an exception.
+
+Failure means it raised an exception.
+
+Timeout means it ran longer than the timeout limit and was aborted.
 
 == Timeouts
 
 You can restrict how long executions are allowed to run for.
 
-  storm = ThreadStorm.new :size => 2, :timeout => 0.02, :default_value => "failed"
-  storm.execute{ sleep(0.01); "a" }
-  storm.execute{ sleep(0.03); "b" }
-  storm.execute{ sleep(0.01); "c" }
-  storm.join
-  storm.executions[1].started?   # true
-  storm.executions[1].finished?  # true
-  storm.executions[1].timed_out? # true
-  storm.executions[1].duration   # ~0.02
-  storm.executions[1].value      # "failed"
+  storm = ThreadStorm.new :size => 2, :timeout => 0.02
+  execution = storm.execute{ sleep(0.03); "b" }
+  execution.join
+  execution.finished?  # true
+  execution.timeout?   # true
+  executions.duration   # ~0.02
 
 == Error handling
 
@@ -54,8 +78,9 @@ If an execution causes an exception, it will be reraised when ThreadStorm#join (
 
   storm = ThreadStorm.new :size => 2, :reraise => false, :default_value => "failure"
   execution = storm.execute{ raise("busted"); "a" }
-  storm.join
-  execution.value # "failure"
+  execution.join
+  execution.failure?  # true
+  execution.value     # "failure"
   execution.exception # RuntimeError: busted
 
 == Joining vs shutting down
@@ -74,20 +99,35 @@ Sometimes it can be a pain to remember to call #shutdown, so as a convenience, y
 
 == Configurable timeout method
 
-<tt>Timeout.timeout</tt> is unreliable in MRI 1.8.x.  To address this, you can have ThreadStorm use an alternative implementation.
+<tt>Timeout.timeout</tt> is unreliable in MRI 1.8.  To address this, you can have ThreadStorm use an alternative implementation.
 
  require "system_timer"
  storm = ThreadStorm.new :timeout_method => SystemTimer.method(:timeout) do
    ...
  end
  
-The <tt>:timeout_method</tt> option takes any callable object (i.e. <tt>responds_to?(:call)</tt>) that implements something similar to <tt>Timeout.timeout</tt> (i.e. takes the same arguments and raises <tt>Timeout::Error</tt>).
+The <tt>:timeout_method</tt> option takes any callable object that has the same signature as <tt>Timeout.timeout</tt>.
 
   require "system_timer"
   storm = ThreadStorm.new :timeout_method => Proc.new{ |seconds, &block| SystemTimer.timeout(seconds, &block) }
     ...
   end
 
+== Caveats and Gotchas
+
+This is tricky...
+
+  ThreadStorm.new do |s|
+    s.execute{ raise RuntimeError }
+    begin
+      s.join
+    rescue RuntimeError => e
+      puts "execution failed"
+    end
+  end
+
+This will still raise an exception because ThreadStorm#join will be called again after the block is finished. This same problem happens with ThreadStorm#run.
+
 == Copyright
 
 Copyright (c) 2010 Christopher J. Bottaro. See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-0.5.1
+0.7.0

data/lib/thread_storm/active_support.rb

@@ -35,6 +35,10 @@ end
 
 class Object #:nodoc:
   
+  def metaclass
+    class << self; self; end
+  end
+  
   def tap
     yield(self)
     self

data/lib/thread_storm/execution.rb

@@ -3,92 +3,302 @@ require "monitor"
 class ThreadStorm
   # Encapsulates a unit of work to be sent to the thread pool.
   class Execution
-    attr_writer :value, :exception #:nodoc:
-    attr_reader :args, :block, :thread #:nodoc:
     
-    def initialize(args, default_value, &block) #:nodoc:
-      @args = args
-      @value = default_value
-      @block = block
-      @start_time = nil
-      @finish_time = nil
+    # When an execution has been created, but hasn't been scheduled to run.
+    STATE_INITIALIZED = 0
+    # When an execution has been scheduled to run but is waiting for an available thread.
+    STATE_QUEUED      = 1
+    # When an execution is running on a thread.
+    STATE_STARTED     = 2
+    # When an execution has finished running.
+    STATE_FINISHED    = 3
+    
+    # A hash mapping state symbols (:initialized, :queued, :started, :finished) to their
+    # corresponding state constant values.
+    STATE_SYMBOLS = {
+      :initialized  => STATE_INITIALIZED,
+      :queued       => STATE_QUEUED,
+      :started      => STATE_STARTED,
+      :finished     => STATE_FINISHED
+    }
+    
+    # Inverted STATE_SYMBOLS.
+    STATE_SYMBOLS_INVERTED = STATE_SYMBOLS.invert
+    
+    # The arguments passed into new or ThreadStorm#execute.
+    attr_reader :args
+    
+    # The value of an execution's block.
+    attr_reader :value
+    
+    # If an exception was raised when running an execution, it is stored here.
+    attr_reader :exception
+    
+    # Options specific to an Execution instance.  Note that you cannot modify
+    # the options once ThreadStorm#execute has been called on the execution.
+    attr_reader :options
+    
+    attr_reader :block, :thread #:nodoc:
+    
+    # call-seq:
+    #   new(options = {}) -> Execution
+    #   new(*args){ |*args| ... } -> Execution
+    #
+    # Create an execution. The execution will be in the :initialized state. Call
+    # ThreadStorm#execute to schedule the execution to be run and transition
+    # it into the :queued state.
+    # 
+    # Default options come from the global <tt>ThreadStorm.options</tt>.  If you want options specific
+    # to a ThreadStorm instance, use ThreadStorm#new_execution.
+    def initialize(*args, &block)
+      if block_given?
+        @args = args
+        @block = block
+        @options = ThreadStorm.options.dup
+      elsif args.length == 0
+        @args = []
+        @block = nil
+        @options = ThreadStorm.options.dup
+      elsif args.length == 1 and args.first.kind_of?(Hash)
+        @args = []
+        @block = nil
+        @options = ThreadStorm.options.merge(args.first)
+      else
+        raise ArgumentError, "illegal call-seq"
+      end
+      
+      @state = nil
+      @state_at = []
+      @value = nil
       @exception = nil
-      @timed_out = false
       @thread = nil
       @lock = Monitor.new
       @cond = @lock.new_cond
+      @callback_exceptions = {}
+      
+      enter_state(:initialized)
     end
     
-    def start! #:nodoc:
-      @thread = Thread.current
-      @start_time = Time.now
+    # This code:
+    #   execution = ThreadStorm::Execution.new
+    #   execution.define(1, 2, 3){ |a1, a2, a3| ... some code ... }
+    # Is equivalent to:
+    #   ThreadStorm::Execution.new(1, 2, 3){ |a1, a2, a3| ... some code ... }
+    # The advantage is that you can use the first form of Execution.new to pass in options.
+    def define(*args, &block)
+      @args = args
+      @block = block
+      self
     end
     
-    # True if this execution has started running.
-    def started?
-      !!start_time
+    # Returns the state of an execution.  If _how_ is set to :sym, returns the state as symbol.
+    def state(how = :const)
+      if how == :sym
+        STATE_SYMBOLS_INVERTED[@state] or raise RuntimeError, "invalid state: #{@state.inspect}"
+      else
+        @state
+      end
     end
     
-    # When this execution began to run.
-    def start_time
-      @start_time
+    # Returns true if the execution is currently in the given state.
+    # _state_ can be either a state constant or symbol.
+    def state?(state)
+      self.state == state_to_const(state)
     end
     
-    def finish! #:nodoc:
-      @lock.synchronize do
-        @finish_time = Time.now
-        @cond.signal
-      end
+    # Returns true if the execution is currently in the :initialized state.
+    def initialized?
+      state?(STATE_INITIALIZED)
     end
     
-    # True if this execution has finished running.
+    # Returns true if the execution is currently in the :queued state.
+    def queued?
+      state?(STATE_QUEUED)
+    end
+    
+    # Returns true if the execution is currently in the :started state.
+    def started?
+      state?(STATE_STARTED)
+    end
+    
+    # Returns true if the execution is currently in the :finished state.
     def finished?
-      !!finish_time
+      state?(STATE_FINISHED)
+    end
+    
+    # Returns the time when the execution entered the given state.
+    # _state_ can be either a state constant or symbol.
+    def state_at(state)
+      @state_at[state_to_const(state)]
     end
     
-    # When this execution finished running (either cleanly or with error).
-    def finish_time
-      @finish_time
+    # When this execution entered the :initialized state.
+    def initialized_at
+      state_at(:initialized)
     end
     
-    # How long this this execution ran for (i.e. finish_time - start_time)
-    # or if it hasn't finished, how long it has been running for.
-    def duration
-      if finished?
-        finish_time - start_time
-      elsif started?
-        Time.now - start_time
+    # When this execution entered the :queued state.
+    def queued_at
+      state_at(:queued)
+    end
+    
+    # When this execution entered the :started state.
+    def started_at
+      state_at(:started)
+    end
+    
+    # When this execution entered the :finished state.
+    def finished_at
+      state_at(:finished)
+    end
+    
+    # How long an execution was (or has been) in a given state.
+    # _state_ can be either a state constant or symbol.
+    def duration(state = :started)
+      state = state_to_const(state)
+      if state == @state
+        Time.now - state_at(state)
+      elsif state < @state and state_at(state)
+        next_state_at(state) - state_at(state)
       else
-        -1
+        nil
       end
     end
     
-    def timed_out! #:nodoc:
-      @timed_out = true
+    # This is soley for ThreadStorm to put the execution into the queued state.
+    def queued! #:nodoc:
+      options.freeze
+      enter_state(STATE_QUEUED)
     end
     
+    def execute #:nodoc:
+      timeout           = options[:timeout]
+      timeout_method    = options[:timeout_method]
+      timeout_exception = options[:timeout_exception]
+      default_value     = options[:default_value]
+      
+      @thread = Thread.current
+      enter_state(STATE_STARTED)
+      
+      begin
+        timeout_method.call(timeout){ @value = @block.call(*args) }
+      rescue timeout_exception => e
+        @exception = e
+        @value = default_value
+      rescue Exception => e
+        @exception = e
+        @value = default_value
+      ensure
+        enter_state(STATE_FINISHED)
+      end
+    end
+    
+    # True if the execution finished without failure (exception) or timeout.
+    def success?
+      !exception? and !timeout?
+    end
+    
+    # True if this execution raised an exception.
+    def failure?
+      !!@exception and !timeout?
+    end
+    
+    # Deprecated... for backwards compatibility.
+    alias_method :exception?, :failure? #:nodoc:
+    
     # True if the execution went over the timeout limit.
-    def timed_out?
-      !!@timed_out
+    def timeout?
+      !!@exception and @exception.kind_of?(options[:timeout_exception])
     end
     
-    # Block until this execution has finished running. 
-    def join
-      @lock.synchronize do
-        @cond.wait_until{ finished? }
+    # Deprecated... for backwards compatibility.
+    alias_method :timed_out?, :timeout? #:nodoc:
+    
+    def callback_exception?(state = nil)
+      ![nil, {}].include?(callback_exception(state))
+    end
+    
+    def callback_exception(state = nil)
+      if state
+        @callback_exceptions[state]
+      else
+        @callback_exceptions
       end
     end
     
-    # If this execution finished with an exception, it is stored here.
-    def exception
-      @exception
+    # Block until this execution has finished running. 
+    def join
+      @lock.synchronize{ @cond.wait_until{ finished? } }
+      raise exception if exception? and options[:reraise]
+      true
     end
     
     # The value returned by the execution's code block.
     # This implicitly calls join.
     def value
-      join
-      @value
+      join and @value
+    end
+    
+  private
+    
+    # Enters _state_ doing some error checking, callbacks, and special case for entering the finished state.
+    def enter_state(state) #:nodoc:
+      state = state_to_const(state)
+      raise RuntimeError, "invalid state transition from #{@state} to #{state}" unless @state.nil? or state > @state
+      
+      # We need state changes and callbacks to be atomic so that if we query a state change
+      # we can be sure that its corresponding callback has finished running as well. Thus
+      # we need to make sure to synchronize querying state (see #state).
+      
+      handle_callback(state)
+      
+      @lock.synchronize do
+        do_enter_state(state)
+        @cond.broadcast if state == STATE_FINISHED # Wake any threads that called join and are waiting.
+      end
+    end
+    
+    # Enters _state_ and set records the time.
+    def do_enter_state(state)
+      @state = state
+      @state_at[@state] = Time.now
+    end
+    
+    def handle_callback(state)
+      state = state_to_sym(state)
+      callback = options["#{state}_callback".to_sym]
+      return unless callback
+      begin
+        callback.call(self)
+      rescue Exception => e
+        @callback_exceptions[state] = e
+      end
+    end
+    
+    # Finds the next state from _state_ that has a state_at time.
+    # Ex:
+    #   [0:10, nil, 0:15, 0:20]
+    #   next_state_at(0) -> 0:15
+    def next_state_at(state)
+      @state_at[state+1..-1].detect{ |time| !time.nil? }
+    end
+    
+    # Normalizes _state_ to a constant (integer).
+    def state_to_const(state)
+      if state.kind_of?(Symbol)
+        STATE_SYMBOLS[state]
+      else
+        state
+      end
+    end
+    
+    # Normalizes _state_ to a symbol.
+    def state_to_sym(state)
+      if state.kind_of?(Symbol)
+        state
+      else
+        STATE_SYMBOLS_INVERTED[state]
+      end
     end
     
   end

data/lib/thread_storm/queue.rb

@@ -0,0 +1,69 @@
+require "monitor"
+
+class ThreadStorm
+  # This is tricky... we need to maintain both real queue size and fake queue size.
+  # If we use just the real queue size alone, then we will see the following
+  # (incorrect) behavior:
+  #   storm = ThreadStorm.new :size => 2, :execute_blocks => true
+  #   storm.execute{ sleep }
+  #   storm.execute{ sleep }
+  #   storm.execute{ sleep } # Doesn't block, but should.
+  #   storm.execute{ sleep } # Finally blocks.
+  # The reason is that popping the queue (and thus decrementing its size) does not
+  # imply that the worker thread has actually finished the execution and is ready to
+  # accept another one.
+  class Queue #:nodoc:
+    
+    def initialize(max_size, enqueue_blocks)
+      @max_size       = max_size
+      @enqueue_blocks = enqueue_blocks
+      @size           = 0
+      @array          = []
+      @lock           = Monitor.new
+      @cond1          = @lock.new_cond # Wish I could come up with better names.
+      @cond2          = @lock.new_cond
+    end
+    
+    def synchronize(&block)
+      @lock.synchronize{ yield(self) }
+    end
+    
+    # +enqueue+ needs to wait on the fake size, otherwise @max_size+1 calls to
+    # +enqueue+ could be made when @enqueue_blocks is true.
+    def enqueue(item)
+      @lock.synchronize do
+        @cond2.wait_until{ @size < @max_size } if @enqueue_blocks
+        @size += 1
+        @array << item
+        @cond1.broadcast
+      end
+    end
+    
+    # +dequeue+ needs to wait until the real size, otherwise a single call to
+    # +enqueue+ could result to multiple successful calls to +dequeue+ before
+    # a call to +decr_size+ is made.
+    def dequeue
+      @lock.synchronize do
+        @cond1.wait_until{ @array.size > 0 }
+        @array.shift
+      end
+    end
+    
+    # Decrement the fake size, thus signaling that we're ready to call +enqueue+.
+    def decr_size
+      @lock.synchronize do
+        @size -= 1 unless @size == 0
+        @cond2.broadcast
+      end
+    end
+    
+    def shutdown
+      @lock.synchronize do
+        @array = [nil] * @max_size
+        @size = @max_size
+        @cond1.broadcast
+      end
+    end
+    
+  end
+end

data/lib/thread_storm/worker.rb

@@ -1,76 +1,18 @@
 class ThreadStorm
   class Worker #:nodoc:
-    attr_reader :thread, :execution
+    attr_reader :thread
     
-    # Takes the threadsafe queue and options from the thread pool.
-    def initialize(queue, sentinel, options)
+    def initialize(queue)
       @queue     = queue
-      @sentinel  = sentinel
-      @options   = options
-      @execution = nil # Current execution we're working on.
       @thread    = Thread.new(self){ |me| me.run }
     end
     
-    def timeout
-      @timeout ||= @options[:timeout]
-    end
-    
-    def timeout_method
-      @timeout_method ||= @options[:timeout_method]
-    end
-    
     # Pop executions and process them until we're signaled to die.
     def run
-      pop_and_process_execution while not die?
-    end
-    
-    # Pop an execution off the queue and process it, or pass off control to a different thread.
-    def pop_and_process_execution
-      @sentinel.synchronize do |e_cond, p_cond|
-        # Become idle and signal that we're idle.
-        @execution = nil
-        e_cond.signal
-        
-        # Give up the lock and wait until there is work to do.
-        p_cond.wait_while{ @queue.empty? }
-        
-        # Get the work to do (implicitly becoming busy).
-        @execution = @queue.pop
+      while (execution = @queue.dequeue)
+        execution.execute
+        @queue.decr_size
       end
-      
-      process_execution_with_timeout unless die?
-    end
-    
-    # Process the execution, handling timeouts and exceptions.
-    def process_execution_with_timeout
-      execution.start!
-      begin
-        if timeout
-          timeout_method.call(timeout){ process_execution }
-        else
-          process_execution
-        end
-      rescue Timeout::Error => e
-        execution.timed_out!
-      rescue Exception => e
-        execution.exception = e
-      ensure
-        execution.finish!
-      end
-    end
-    
-    # Seriously, process the execution.
-    def process_execution
-      execution.value = execution.block.call(*execution.args)
-    end
-    
-    def busy?
-      !!@execution and not die?
-    end
-    
-    # True if this worker's thread should die.
-    def die?
-      @execution == :die
     end
     
   end