concurrent-ruby 0.3.2 → 0.4.0

data/lib/concurrent/channel.rb

@@ -0,0 +1,28 @@
+require 'concurrent/actor'
+require 'concurrent/stoppable'
+
+module Concurrent
+
+  class Channel < Actor
+    include Stoppable
+
+    def initialize(&block)
+      raise ArgumentError.new('no block given') unless block_given?
+      super()
+      @task = block
+    end
+
+    protected
+
+    def on_stop # :nodoc:
+      before_stop_proc.call if before_stop_proc
+      super
+    end
+
+    private
+
+    def act(*message)
+      return @task.call(*message)
+    end
+  end
+end

data/lib/concurrent/dereferenceable.rb

@@ -1,7 +1,24 @@
 module Concurrent
 
+  # Object references in Ruby are mutable. This can lead to serious problems when
+  # the `#value` of a concurrent object is a mutable reference. Which is always the
+  # case unless the value is a `Fixnum`, `Symbol`, or similar "primitive" data type.
+  # Most classes in this library that expose a `#value` getter method do so using
+  # this mixin module.
   module Dereferenceable
 
+    # Set the options which define the operations #value performs before
+    # returning data to the caller (dereferencing).
+    #
+    # @note Many classes that include this module will call #set_deref_options
+    # from within the constructor, thus allowing these options to be set at
+    # object creation.
+    #
+    # @param [Hash] opts the options defining dereference behavior.
+    # @option opts [String] :dup_on_deref Call #dup before returning the data (default: false)
+    # @option opts [String] :freeze_on_deref Call #freeze before returning the data (default: false)
+    # @option opts [String] :copy_on_deref Call the given `Proc` passing the internal value and
+    #   returning the value returned from the proc (default: `nil`)
     def set_deref_options(opts = {})
       mutex.synchronize do
         @dup_on_deref = opts[:dup_on_deref] || opts[:dup] || false
@@ -11,6 +28,8 @@ module Concurrent
       end
     end
 
+    # Return the value this object represents after applying the options specified
+    # by the #set_deref_options method.
     def value
       return nil if @value.nil?
       return @value if @do_nothing_on_deref
@@ -26,7 +45,8 @@ module Concurrent
 
     protected
 
-    def mutex
+    # @private
+    def mutex # :nodoc:
       @mutex ||= Mutex.new
     end
   end

data/lib/concurrent/event.rb

@@ -3,18 +3,37 @@ require 'concurrent/utilities'
 
 module Concurrent
 
+  # Old school kernel-style event reminiscent of Win32 programming in C++.
+  #
+  # When an `Event` is created it is in the `unset` state. Threads can choose to
+  # `#wait` on the event, blocking until released by another thread. When one
+  # thread wants to alert all blocking threads it calls the `#set` method which
+  # will then wake up all listeners. Once an `Event` has been set it remains set.
+  # New threads calling `#wait` will return immediately. An `Event` may be
+  # `#reset` at any time once it has been set.
+  #
+  # @see http://msdn.microsoft.com/en-us/library/windows/desktop/ms682655.aspx
   class Event
 
+    # Creates a new `Event` in the unset state. Threads calling `#wait` on the
+    # `Event` will block.
     def initialize
       @set = false
       @mutex = Mutex.new
       @waiters = []
     end
 
+    # Is the object in the set state?
+    #
+    # @return [Boolean] indicating whether or not the `Event` has been set
     def set?
       return @set == true
     end
 
+    # Trigger the event, setting the state to `set` and releasing all threads
+    # waiting on the event. Has no effect if the `Event` has already been set.
+    #
+    # @return [Boolean] should always return `true`
     def set
       return true if set?
       @mutex.synchronize do
@@ -24,11 +43,24 @@ module Concurrent
       return true
     end
 
+    # Reset a previously set event back to the `unset` state.
+    # Has no effect if the `Event` has not yet been set.
+    #
+    # @return [Boolean] should always return `true`
     def reset
-      @mutex.synchronize { @set = false; @waiters.clear }
+      return true unless set?
+      @mutex.synchronize do
+        @set = false
+        @waiters.clear # just in case there's garbage
+      end
       return true
     end
 
+    # Wait a given number of seconds for the `Event` to be set by another
+    # thread. Will wait forever when no `timeout` value is given. Returns
+    # immediately if the `Event` has already been set.
+    #
+    # @return [Boolean] true if the `Event` was set before timeout else false
     def wait(timeout = nil)
       return true if set?
 

data/lib/concurrent/postable.rb

@@ -0,0 +1,98 @@
+module Concurrent
+
+  module Postable
+
+    # @!visibility private
+    Package = Struct.new(:message, :handler, :notifier) # :nodoc:
+
+    # Sends a message to and returns. It's a fire-and-forget interaction.
+    #
+    # @param [Array] message one or more arguments representing a single message
+    #   to be sent to the receiver.
+    #
+    # @return [Object] false when the message cannot be queued else the number
+    #   of messages in the queue *after* this message has been post
+    #
+    # @raise ArgumentError when the message is empty
+    #
+    # @example
+    #   class EchoActor < Concurrent::Actor
+    #     def act(*message)
+    #       p message
+    #     end
+    #   end
+    #   
+    #   echo = EchoActor.new
+    #   echo.run!
+    #   
+    #   echo.post("Don't panic") #=> true
+    #   #=> ["Don't panic"]
+    #   
+    #   echo.post(1, 2, 3, 4, 5) #=> true
+    #   #=> [1, 2, 3, 4, 5]
+    #   
+    #   echo << "There's a frood who really knows where his towel is." #=> #<EchoActor:0x007fc8012b8448...
+    #   #=> ["There's a frood who really knows where his towel is."]
+    def post(*message)
+      raise ArgumentError.new('empty message') if message.empty?
+      return false unless ready?
+      queue.push(Package.new(message))
+      return queue.length
+    end
+
+    def <<(message)
+      post(*message)
+      return self
+    end
+
+    def post?(*message)
+      raise ArgumentError.new('empty message') if message.empty?
+      return nil unless ready?
+      contract = Contract.new
+      queue.push(Package.new(message, contract))
+      return contract
+    end
+
+    def post!(seconds, *message)
+      raise ArgumentError.new('empty message') if message.empty?
+      raise Concurrent::Runnable::LifecycleError unless ready?
+      raise Concurrent::TimeoutError if seconds.to_f <= 0.0
+      event = Event.new
+      cback = Queue.new
+      queue.push(Package.new(message, cback, event))
+      if event.wait(seconds)
+        result = cback.pop
+        if result.is_a?(Exception)
+          raise result
+        else
+          return result
+        end
+      else
+        event.set # attempt to cancel
+        raise Concurrent::TimeoutError
+      end
+    end
+
+    def forward(receiver, *message)
+      raise ArgumentError.new('empty message') if message.empty?
+      return false unless ready?
+      queue.push(Package.new(message, receiver))
+      return queue.length
+    end
+
+    def ready?
+      if self.respond_to?(:running?) && ! running?
+        return false
+      else
+        return true
+      end
+    end
+
+    private
+
+    # @private
+    def queue # :nodoc:
+      @queue ||= Queue.new
+    end
+  end
+end

data/lib/concurrent/stoppable.rb

@@ -0,0 +1,20 @@
+require 'concurrent/runnable'
+
+module Concurrent
+
+  module Stoppable
+
+    def before_stop(&block)
+      raise ArgumentError.new('no block given') unless block_given?
+      raise Runnable::LifecycleError.new('#before_stop already set') if @before_stop_proc
+      @before_stop_proc = block
+      return self
+    end
+
+    protected
+
+    def before_stop_proc
+      return @before_stop_proc
+    end
+  end
+end

data/lib/concurrent/timer_task.rb

@@ -3,32 +3,236 @@ require 'observer'
 
 require 'concurrent/dereferenceable'
 require 'concurrent/runnable'
+require 'concurrent/stoppable'
 require 'concurrent/utilities'
 
 module Concurrent
 
+  # 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
+  # wakes up and performs the task. Lather, 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 coupled with the concurrency logic. Second, an exception in
+  # raised while performing 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 significant problem. `TimerTask` 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 separate thread. Should the task experience an unrecoverable
+  # crash only the task thread will crash. This makes the `TimerTask` very fault tolerant
+  # Additionally, the `TimerTask` thread can respond to the success or failure of the task,
+  # performing logging or ancillary operations. `TimerTask` can also be configured with a
+  # timeout value allowing it to kill a task that runs too long.
+  # 
+  # One other advantage of `TimerTask` is it forces the bsiness logic to be completely decoupled
+  # from the concurrency logic. The business logic can be tested separately then passed to the
+  # `TimerTask` for scheduling and running.
+  # 
+  # In some cases it may be necessary for a `TimerTask` to affect its own execution cycle.
+  # To facilitate this a reference to the task object is passed into the block as a block
+  # argument every time the task is executed.
+  # 
+  # The `TimerTask` class includes the `Dereferenceable` mixin module so the result of
+  # the last execution is always available via the `#value` method. Derefencing options
+  # can be passed to the `TimerTask` during construction or at any later time using the
+  # `#set_deref_options` method.
+  # 
+  # `TimerTask` supports notification through the Ruby standard library
+  # {http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html Observable}
+  # module. On execution the `TimerTask` will notify the observers
+  # with threes 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.
+  #
+  # @example Basic usage
+  #   require 'concurrent'
+  #   
+  #   task = Concurrent::TimerTask.new{ puts 'Boom!' }
+  #   task.run!
+  #   
+  #   task.execution_interval #=> 60 (default)
+  #   task.timeout_interval   #=> 30 (default)
+  #   
+  #   # wait 60 seconds...
+  #   #=> 'Boom!'
+  #   
+  #   task.stop #=> true
+  #
+  # @example Configuring `:execution_interval` and `:timeout_interval`
+  #   task = Concurrent::TimerTask.new(execution_interval: 5, timeout_interval: 5) do
+  #          puts 'Boom!'
+  #        end
+  #   
+  #   task.execution_interval #=> 5
+  #   task.timeout_interval   #=> 5
+  #
+  # @example Immediate execution with `:run_now`
+  #   task = Concurrent::TimerTask.new(run_now: true){ puts 'Boom!' }
+  #   task.run!
+  #   
+  #   #=> 'Boom!'
+  #
+  # @example Last `#value` and `Dereferenceable` mixin
+  #   task = Concurrent::TimerTask.new(
+  #     dup_on_deref: true,
+  #     execution_interval: 5
+  #   ){ Time.now }
+  #   
+  #   task.run!
+  #   Time.now   #=> 2013-11-07 18:06:50 -0500
+  #   sleep(10)
+  #   task.value #=> 2013-11-07 18:06:55 -0500
+  #
+  # @example Controlling execution from within the block
+  #   timer_task = Concurrent::TimerTask.new(execution_interval: 1) do |task|
+  #     task.execution_interval.times{ print 'Boom! ' }
+  #     print "\n"
+  #     task.execution_interval += 1
+  #     if task.execution_interval > 5
+  #       puts 'Stopping...'
+  #       task.stop
+  #     end
+  #   end
+  #   
+  #   timer_task.run # blocking call - this task will stop itself
+  #   #=> Boom!
+  #   #=> Boom! Boom!
+  #   #=> Boom! Boom! Boom!
+  #   #=> Boom! Boom! Boom! Boom!
+  #   #=> Boom! Boom! Boom! Boom! Boom!
+  #   #=> Stopping...
+  #
+  # @example Observation
+  #   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.new(execution_interval: 1, timeout_interval: 1){ 42 }
+  #   task.add_observer(TaskObserver.new)
+  #   task.run!
+  #   
+  #   #=> (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.stop
+  #   
+  #   task = Concurrent::TimerTask.new(execution_interval: 1, timeout_interval: 1){ sleep }
+  #   task.add_observer(TaskObserver.new)
+  #   task.run!
+  #   
+  #   #=> (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.stop
+  #   
+  #   task = Concurrent::TimerTask.new(execution_interval: 1){ raise StandardError }
+  #   task.add_observer(TaskObserver.new)
+  #   task.run!
+  #   
+  #   #=> (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.stop
+  #
+  # @see http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html
+  # @see http://docs.oracle.com/javase/7/docs/api/java/util/TimerTask.html
   class TimerTask
     include Dereferenceable
     include Runnable
+    include Stoppable
     include Observable
 
+    # Default `:execution_interval`
     EXECUTION_INTERVAL = 60
+
+    # Default `:timeout_interval`
     TIMEOUT_INTERVAL = 30
 
-    attr_accessor :execution_interval
-    attr_accessor :timeout_interval
+    # Number of seconds after the task completes before the task is
+    # performed again.
+    attr_reader :execution_interval
+
+    # Number of seconds the task can run before it is considered to have failed.
+    # Failed tasks are forcibly killed.
+    attr_reader :timeout_interval
 
+    # Create a new TimerTask with the given task and configuration.
+    #
+    # @param [Hash] opts the options defining task execution.
+    # @option opts [Integer] :execution_interval number of seconds between
+    #   task executions (default: EXECUTION_INTERVAL)
+    # @option opts [Integer] :timeout_interval number of seconds a task can
+    #   run before it is considered to have failed (default: TIMEOUT_INTERVAL)
+    # @option opts [Boolean] :run_now Whether to run the task immediately
+    #   upon instanciation or to wait until the first #execution_interval
+    #   has passed (default: false)
+    #
+    # @raise ArgumentError when no block is given.
+    #
+    # @yield to the block after :execution_interval seconds have passed since
+    #   the last yield
+    # @yieldparam task a reference to the `TimerTask` instance so that the
+    #   block can control its own lifecycle. Necessary since `self` will
+    #   refer to the execution context of the block rather than the running
+    #   `TimerTask`.
+    #
+    # @note Calls Concurrent::Dereferenceable#set_deref_options passing `opts`.
+    #   All options supported by Concurrent::Dereferenceable can be set
+    #   during object initialization.
+    #
+    # @see Concurrent::Dereferenceable#set_deref_options
     def initialize(opts = {}, &block)
       raise ArgumentError.new('no block given') unless block_given?
 
-      @execution_interval = opts[:execution] || opts[:execution_interval] || EXECUTION_INTERVAL
-      @timeout_interval = opts[:timeout] || opts[:timeout_interval] || TIMEOUT_INTERVAL
+      self.execution_interval = opts[:execution] || opts[:execution_interval] || EXECUTION_INTERVAL
+      self.timeout_interval = opts[:timeout] || opts[:timeout_interval] || TIMEOUT_INTERVAL
       @run_now = opts[:now] || opts[:run_now] || false
 
       @task = block
       set_deref_options(opts)
     end
 
+    # Number of seconds after the task completes before the task is
+    # performed again.
+    #
+    # @param [Float] value number of seconds
+    #
+    # @raise ArgumentError when value is non-numeric or not greater than zero
+    def execution_interval=(value)
+      if (value = value.to_f) <= 0.0
+        raise ArgumentError.new("'execution_interval' must be non-negative number")
+      end
+      @execution_interval = value
+    end
+
+    # Number of seconds the task can run before it is considered to have failed.
+    # Failed tasks are forcibly killed.
+    #
+    # @param [Float] value number of seconds
+    #
+    # @raise ArgumentError when value is non-numeric or not greater than zero
+    def timeout_interval=(value)
+      if (value = value.to_f) <= 0.0
+        raise ArgumentError.new("'timeout_interval' must be non-negative number")
+      end
+      @timeout_interval = value
+    end
+
+    # Terminate with extreme prejudice. Useful in cases where `#stop` doesn't
+    # work because one of the threads becomes unresponsive.
+    #
+    # @return [Boolean] indicating whether or not the `TimerTask` was killed
+    #
+    # @note Do not use this method unless `#stop` has failed.
     def kill
       return true unless running?
       mutex.synchronize do
@@ -48,16 +252,17 @@ module Concurrent
 
     protected
 
-    def on_run
+    def on_run # :nodoc:
       @monitor = Thread.current
     end
 
-    def on_stop
+    def on_stop # :nodoc:
+      before_stop_proc.call if before_stop_proc
       @monitor.wakeup if @monitor.alive?
       Thread.pass
     end
 
-    def on_task
+    def on_task # :nodoc:
       if @run_now
         @run_now = false
       else
@@ -66,7 +271,7 @@ module Concurrent
       execute_task
     end
 
-    def execute_task
+    def execute_task # :nodoc:
       @value = ex = nil
       @worker = Thread.new do
         Thread.current.abort_on_exception = false