concurrent-ruby 0.7.0-java

data/lib/concurrent/observable.rb

@@ -0,0 +1,40 @@
+require 'concurrent/atomic/copy_on_notify_observer_set'
+require 'concurrent/atomic/copy_on_write_observer_set'
+
+module Concurrent
+
+  module Observable
+
+    # @return [Object] the added observer
+    def add_observer(*args, &block)
+      observers.add_observer(*args, &block)
+    end
+
+    # as #add_observer but it can be used for chaining
+    # @return [Observable] self
+    def with_observer(*args, &block)
+      add_observer *args, &block
+      self
+    end
+
+    # @return [Object] the deleted observer
+    def delete_observer(*args)
+      observers.delete_observer(*args)
+    end
+
+    # @return [Observable] self
+    def delete_observers
+      observers.delete_observers
+      self
+    end
+
+    # @return [Integer] the observers count
+    def count_observers
+      observers.count_observers
+    end
+
+    protected
+
+    attr_accessor :observers
+  end
+end

data/lib/concurrent/options_parser.rb

@@ -0,0 +1,48 @@
+module Concurrent
+
+  # A mixin module for parsing options hashes related to gem-level configuration.
+  module OptionsParser
+
+    # Get the requested `Executor` based on the values set in the options hash.
+    #
+    # @param [Hash] opts the options defining the requested executor
+    # @option opts [Executor] :executor (`nil`) when set use the given `Executor` instance
+    # @option opts [Boolean] :operation (`false`) when true use the global operation pool
+    # @option opts [Boolean] :task (`true`) when true use the global task pool
+    #
+    # @return [Executor, nil] the requested thread pool, or nil when no option specified
+    def get_executor_from(opts = {})
+      if opts[:executor]
+        opts[:executor]
+      elsif opts[:operation] == true || opts[:task] == false
+        Concurrent.configuration.global_operation_pool
+      elsif opts[:operation] == false || opts[:task] == true
+        Concurrent.configuration.global_task_pool
+      else
+        nil
+      end
+    end
+
+    # Get the requested `Executor` based on the values set in the options hash.
+    #
+    # @param [Hash] opts the options defining the requested executor
+    # @option opts [Executor] :task_executor (`nil`) when set use the given `Executor` instance
+    #
+    # @return [Executor] the requested thread pool (default: global task pool)
+    def get_task_executor_from(opts = {})
+      opts[:task_executor] || opts[:executor] || Concurrent.configuration.global_task_pool
+    end
+
+    # Get the requested `Executor` based on the values set in the options hash.
+    #
+    # @param [Hash] opts the options defining the requested executor
+    # @option opts [Executor] :task_executor (`nil`) when set use the given `Executor` instance
+    #
+    # @return [Executor] the requested thread pool (default: global operation pool)
+    def get_operation_executor_from(opts = {})
+      opts[:operation_executor] || opts[:executor] || Concurrent.configuration.global_operation_pool
+    end
+
+    extend self
+  end
+end

data/lib/concurrent/promise.rb

@@ -0,0 +1,170 @@
+require 'thread'
+
+require 'concurrent/obligation'
+require 'concurrent/options_parser'
+
+module Concurrent
+
+  # TODO unify promise and future to single class, with dataflow
+  class Promise
+    include Obligation
+
+    # Initialize a new Promise with the provided options.
+    #
+    # @param [Hash] opts the options used to define the behavior at update and deref
+    #
+    # @option opts [Promise] :parent the parent `Promise` when building a chain/tree
+    # @option opts [Proc] :on_fulfill fulfillment handler
+    # @option opts [Proc] :on_reject rejection handler
+    #
+    # @option opts [Boolean] :operation (false) when `true` will execute the future on the global
+    #   operation pool (for long-running operations), when `false` will execute the future on the
+    #   global task pool (for short-running tasks)
+    # @option opts [object] :executor when provided will run all operations on
+    #   this executor rather than the global thread pool (overrides :operation)
+    #
+    # @option opts [String] :dup_on_deref (false) call `#dup` before returning the data
+    # @option opts [String] :freeze_on_deref (false) call `#freeze` before returning the data
+    # @option opts [String] :copy_on_deref (nil) call the given `Proc` passing the internal value and
+    #   returning the value returned from the proc
+    #
+    # @see http://wiki.commonjs.org/wiki/Promises/A
+    # @see http://promises-aplus.github.io/promises-spec/
+    def initialize(opts = {}, &block)
+      opts.delete_if { |k, v| v.nil? }
+
+      @executor = OptionsParser::get_executor_from(opts) || Concurrent.configuration.global_operation_pool
+      @parent = opts.fetch(:parent) { nil }
+      @on_fulfill = opts.fetch(:on_fulfill) { Proc.new { |result| result } }
+      @on_reject = opts.fetch(:on_reject) { Proc.new { |reason| raise reason } }
+
+      @promise_body = block || Proc.new { |result| result }
+      @state = :unscheduled
+      @children = []
+
+      init_obligation
+    end
+
+    # @return [Promise]
+    def self.fulfill(value, opts = {})
+      Promise.new(opts).tap { |p| p.send(:synchronized_set_state!, true, value, nil) }
+    end
+
+
+    # @return [Promise]
+    def self.reject(reason, opts = {})
+      Promise.new(opts).tap { |p| p.send(:synchronized_set_state!, false, nil, reason) }
+    end
+
+    # @return [Promise]
+    # @since 0.5.0
+    def execute
+      if root?
+        if compare_and_set_state(:pending, :unscheduled)
+          set_pending
+          realize(@promise_body)
+        end
+      else
+        @parent.execute
+      end
+      self
+    end
+
+    # @since 0.5.0
+    def self.execute(opts = {}, &block)
+      new(opts, &block).execute
+    end
+
+    # @return [Promise] the new promise
+    def then(rescuer = nil, &block)
+      raise ArgumentError.new('rescuers and block are both missing') if rescuer.nil? && !block_given?
+      block = Proc.new { |result| result } if block.nil?
+      child = Promise.new(
+        parent: self,
+        executor: @executor,
+        on_fulfill: block,
+        on_reject: rescuer
+      )
+
+      mutex.synchronize do
+        child.state = :pending if @state == :pending
+        child.on_fulfill(apply_deref_options(@value)) if @state == :fulfilled
+        child.on_reject(@reason) if @state == :rejected
+        @children << child
+      end
+
+      child
+    end
+
+    # @return [Promise]
+    def on_success(&block)
+      raise ArgumentError.new('no block given') unless block_given?
+      self.then &block
+    end
+
+    # @return [Promise]
+    def rescue(&block)
+      self.then(block)
+    end
+
+    alias_method :catch, :rescue
+    alias_method :on_error, :rescue
+
+    protected
+
+    def set_pending
+      mutex.synchronize do
+        @state = :pending
+        @children.each { |c| c.set_pending }
+      end
+    end
+
+    # @!visibility private
+    def root? # :nodoc:
+      @parent.nil?
+    end
+
+    # @!visibility private
+    def on_fulfill(result)
+      realize Proc.new { @on_fulfill.call(result) }
+      nil
+    end
+
+    # @!visibility private
+    def on_reject(reason)
+      realize Proc.new { @on_reject.call(reason) }
+      nil
+    end
+
+    def notify_child(child)
+      if_state(:fulfilled) { child.on_fulfill(apply_deref_options(@value)) }
+      if_state(:rejected) { child.on_reject(@reason) }
+    end
+
+    # @!visibility private
+    def realize(task)
+      @executor.post do
+        success, value, reason = SafeTaskExecutor.new(task).execute
+
+        children_to_notify = mutex.synchronize do
+          set_state!(success, value, reason)
+          @children.dup
+        end
+
+        children_to_notify.each { |child| notify_child(child) }
+      end
+    end
+
+    def set_state!(success, value, reason)
+      set_state(success, value, reason)
+      event.set
+    end
+
+    def synchronized_set_state!(success, value, reason)
+      mutex.lock
+      set_state!(success, value, reason)
+    ensure
+      mutex.unlock
+    end
+  end
+end

data/lib/concurrent/scheduled_task.rb

@@ -0,0 +1,79 @@
+require 'concurrent/ivar'
+require 'concurrent/utility/timer'
+require 'concurrent/executor/safe_task_executor'
+
+module Concurrent
+
+  class ScheduledTask < IVar
+
+    attr_reader :schedule_time
+
+    def initialize(intended_time, opts = {}, &block)
+      raise ArgumentError.new('no block given') unless block_given?
+      TimerSet.calculate_schedule_time(intended_time) # raises exceptons
+
+      super(NO_VALUE, opts)
+
+      self.observers = CopyOnNotifyObserverSet.new
+      @intended_time = intended_time
+      @state         = :unscheduled
+      @task          = block
+      @executor      = OptionsParser::get_executor_from(opts) || Concurrent.configuration.global_operation_pool
+    end
+
+    # @since 0.5.0
+    def execute
+      if compare_and_set_state(:pending, :unscheduled)
+        @schedule_time = TimerSet.calculate_schedule_time(@intended_time)
+        Concurrent::timer(@schedule_time.to_f - Time.now.to_f) { @executor.post &method(:process_task) }
+        self
+      end
+    end
+
+    # @since 0.5.0
+    def self.execute(intended_time, opts = {}, &block)
+      return ScheduledTask.new(intended_time, opts, &block).execute
+    end
+
+    def cancelled?
+      state == :cancelled
+    end
+
+    def in_progress?
+      state == :in_progress
+    end
+
+    def cancel
+      if_state(:unscheduled, :pending) do
+        @state = :cancelled
+        event.set
+        true
+      end
+    end
+    alias_method :stop, :cancel
+
+    def add_observer(*args, &block)
+      if_state(:unscheduled, :pending, :in_progress) do
+        observers.add_observer(*args, &block)
+      end
+    end
+
+    protected :set, :fail, :complete
+
+    private
+
+    def process_task
+      if compare_and_set_state(:in_progress, :pending)
+        success, val, reason = SafeTaskExecutor.new(@task).execute
+
+        mutex.synchronize do
+          set_state(success, val, reason)
+          event.set
+        end
+
+        time = Time.now
+        observers.notify_and_delete_observers { [time, self.value, reason] }
+      end
+    end
+  end
+end

data/lib/concurrent/timer_task.rb

@@ -0,0 +1,341 @@
+require 'concurrent/dereferenceable'
+require 'concurrent/observable'
+require 'concurrent/atomic/atomic_boolean'
+require 'concurrent/executor/executor'
+require 'concurrent/executor/safe_task_executor'
+
+module Concurrent
+
+  # A very common currency pattern is to run a thread that performs a task at regular
+  # intervals. The thread that performs 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 because 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 business 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
+  #   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 RubyExecutor
+    include Concurrent::Observable
+
+    # Default `:execution_interval` in seconds.
+    EXECUTION_INTERVAL = 60
+
+    # Default `:timeout_interval` in seconds.
+    TIMEOUT_INTERVAL = 30
+
+    # Create a new TimerTask with the given task and configuration.
+    #
+    # @!macro [attach] timer_task_initialize
+    #   @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 instantiation 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.
+    #
+    #   @return [TimerTask] the new `TimerTask`
+    #  
+    #   @see Concurrent::Dereferenceable#  set_deref_options
+    def initialize(opts = {}, &task)
+      raise ArgumentError.new('no block given') unless block_given?
+
+      init_executor
+      set_deref_options(opts)
+
+      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]
+      @executor = Concurrent::SafeTaskExecutor.new(task)
+      @running = Concurrent::AtomicBoolean.new(false)
+
+      self.observers = CopyOnNotifyObserverSet.new
+    end
+
+    # Is the executor running?
+    #
+    # @return [Boolean] `true` when running, `false` when shutting down or shutdown
+    def running?
+      @running.true?
+    end
+
+    # Execute a previously created `TimerTask`.
+    #
+    # @return [TimerTask] a reference to `self`
+    #
+    # @example Instance and execute in separate steps
+    #   task = Concurrent::TimerTask.new(execution_interval: 10){ print "Hello World\n" }
+    #   task.running? #=> false
+    #   task.execute
+    #   task.running? #=> true
+    #
+    # @example Instance and execute in one line
+    #   task = Concurrent::TimerTask.new(execution_interval: 10){ print "Hello World\n" }.execute
+    #   task.running? #=> true
+    #
+    # @since 0.6.0
+    def execute
+      mutex.synchronize do
+        if @running.false?
+          @running.make_true
+          schedule_next_task(@run_now ? 0 : @execution_interval)
+        end
+      end
+      self
+    end
+
+    # Create and execute a new `TimerTask`.
+    #
+    # @!macro timer_task_initialize
+    #
+    # @example 
+    #   task = Concurrent::TimerTask.execute(execution_interval: 10){ print "Hello World\n" }
+    #   task.running? #=> true
+    #
+    # @since 0.6.0
+    def self.execute(opts = {}, &task)
+      TimerTask.new(opts, &task).execute
+    end
+
+    # @!attribute [rw] execution_interval
+    # @return [Fixnum] Number of seconds after the task completes before the
+    #   task is performed again.
+    def execution_interval
+      mutex.lock
+      @execution_interval
+    ensure
+      mutex.unlock
+    end
+
+    # @!attribute [rw] execution_interval
+    # @return [Fixnum] Number of seconds after the task completes before the
+    #   task is performed again.
+    def execution_interval=(value)
+      if (value = value.to_f) <= 0.0
+        raise ArgumentError.new('must be greater than zero')
+      else
+        begin
+          mutex.lock
+          @execution_interval = value
+        ensure
+          mutex.unlock
+        end
+      end
+    end
+
+    # @!attribute [rw] timeout_interval
+    # @return [Fixnum] Number of seconds the task can run before it is
+    #   considered to have failed.
+    def timeout_interval
+      mutex.lock
+      @timeout_interval
+    ensure
+      mutex.unlock
+    end
+
+    # @!attribute [rw] timeout_interval
+    # @return [Fixnum] Number of seconds the task can run before it is
+    #   considered to have failed.
+    def timeout_interval=(value)
+      if (value = value.to_f) <= 0.0
+        raise ArgumentError.new('must be greater than zero')
+      else
+        begin
+          mutex.lock
+          @timeout_interval = value
+        ensure
+          mutex.unlock
+        end
+      end
+    end
+
+    private :post, :<<
+
+    protected
+
+    # @!visibility private
+    def shutdown_execution
+      @running.make_false
+      super
+    end
+
+    # @!visibility private
+    def kill_execution
+      @running.make_false
+      super
+    end
+
+    # @!visibility private
+    def schedule_next_task(interval = execution_interval)
+      Concurrent::timer(interval, Concurrent::Event.new, &method(:execute_task))
+    end
+
+    # @!visibility private
+    def execute_task(completion)
+      return unless @running.true?
+      Concurrent::timer(timeout_interval, completion, &method(:timeout_task))
+      success, value, reason = @executor.execute(self)
+      if completion.try?
+        self.value = value
+        schedule_next_task
+        time = Time.now
+        observers.notify_observers do
+          [time, self.value, reason]
+        end
+      end
+    end
+
+    # @!visibility private
+    def timeout_task(completion)
+      return unless @running.true?
+      if completion.try?
+        self.value = value
+        schedule_next_task
+        observers.notify_observers(Time.now, nil, Concurrent::TimeoutError.new)
+      end
+    end
+  end
+end