concurrent-ruby 0.6.0.pre.1 → 0.6.0.pre.2

data/lib/concurrent/{ruby_thread_pool_worker.rb → executor/ruby_thread_pool_worker.rb}

@@ -3,10 +3,10 @@ require 'thread'
 module Concurrent
 
   # @!visibility private
-  class RubyThreadPoolWorker # :nodoc:
+  class RubyThreadPoolWorker
 
     # @!visibility private
-    def initialize(queue, parent) # :nodoc:
+    def initialize(queue, parent)
       @queue = queue
       @parent = parent
       @mutex = Mutex.new
@@ -14,14 +14,14 @@ module Concurrent
     end
 
     # @!visibility private
-    def dead? # :nodoc:
+    def dead?
       return @mutex.synchronize do
         @thread.nil? ? false : ! @thread.alive?
       end
     end
 
     # @!visibility private
-    def last_activity # :nodoc:
+    def last_activity
       @mutex.synchronize { @last_activity }
     end
 
@@ -33,7 +33,7 @@ module Concurrent
     end
 
     # @!visibility private
-    def kill # :nodoc:
+    def kill
       @mutex.synchronize do
         Thread.kill(@thread) unless @thread.nil?
         @thread = nil
@@ -41,7 +41,7 @@ module Concurrent
     end
 
     # @!visibility private
-    def run(thread = Thread.current) # :nodoc:
+    def run(thread = Thread.current)
       @mutex.synchronize do
         raise StandardError.new('already running') unless @thread.nil?
         @thread = thread

data/lib/concurrent/{safe_task_executor.rb → executor/safe_task_executor.rb}

@@ -1,3 +1,5 @@
+require 'thread'
+
 module Concurrent
 
   # A simple utility class that executes a callable and returns and array of three elements:
@@ -5,24 +7,29 @@ module Concurrent
   # value - filled by the callable result if it has been executed without errors, nil otherwise
   # reason - the error risen by the callable if it has been executed with errors, nil otherwise
   class SafeTaskExecutor
-    def initialize(task)
+
+    def initialize(task, opts = {})
       @task = task
+      @mutex = Mutex.new
+      @exception_class = opts.fetch(:rescue_exception, false) ? Exception : StandardError
     end
 
     # @return [Array]
-    def execute
-      success = false
-      value = reason = nil
-
-      begin
-        value = @task.call
-        success = true
-      rescue => ex
-        reason = ex
+    def execute(*args)
+      @mutex.synchronize do
         success = false
-      end
+        value = reason = nil
+
+        begin
+          value = @task.call(*args)
+          success = true
+        rescue @exception_class => ex
+          reason = ex
+          success = false
+        end
 
-      [success, value, reason]
+        [success, value, reason]
+      end
     end
   end
-end
+end

data/lib/concurrent/executor/single_thread_executor.rb

@@ -0,0 +1,35 @@
+require 'concurrent/executor/ruby_single_thread_executor'
+
+module Concurrent
+
+  if RUBY_PLATFORM == 'java'
+
+    require 'concurrent/executor/java_single_thread_executor'
+
+    # @!macro [attach] single_thread_executor
+    #
+    #   A thread pool with a set number of threads. The number of threads in the pool
+    #   is set on construction and remains constant. When all threads are busy new
+    #   tasks `#post` to the thread pool are enqueued until a thread becomes available.
+    #   Should a thread crash for any reason the thread will immediately be removed
+    #   from the pool and replaced.
+    #
+    #   The API and behavior of this class are based on Java's `SingleThreadExecutor`
+    #
+    #   @note When running on the JVM (JRuby) this class will inherit from `JavaSingleThreadExecutor`.
+    #     On all other platforms it will inherit from `RubySingleThreadExecutor`.
+    #
+    #   @see Concurrent::RubySingleThreadExecutor
+    #   @see Concurrent::JavaSingleThreadExecutor
+    #
+    #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
+    #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
+    #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html
+    class SingleThreadExecutor < JavaSingleThreadExecutor
+    end
+  else
+    # @!macro single_thread_executor
+    class SingleThreadExecutor < RubySingleThreadExecutor
+    end
+  end
+end

data/lib/concurrent/executor/thread_pool_executor.rb

@@ -0,0 +1,68 @@
+require 'concurrent/executor/ruby_thread_pool_executor'
+
+module Concurrent
+
+  if RUBY_PLATFORM == 'java'
+    require 'concurrent/executor/java_thread_pool_executor'
+    # @!macro [attach] thread_pool_executor
+    #
+    #   An abstraction composed of one or more threads and a task queue. Tasks
+    #   (blocks or `proc` objects) are submit to the pool and added to the queue.
+    #   The threads in the pool remove the tasks and execute them in the order
+    #   they were received. When there are more tasks queued than there are
+    #   threads to execute them the pool will create new threads, up to the
+    #   configured maximum. Similarly, threads that are idle for too long will
+    #   be garbage collected, down to the configured minimum options. Should a
+    #   thread crash it, too, will be garbage collected.
+    #
+    #   `ThreadPoolExecutor` is based on the Java class of the same name. From
+    #   the official Java documentationa;
+    #
+    #   > Thread pools address two different problems: they usually provide
+    #   > improved performance when executing large numbers of asynchronous tasks,
+    #   > due to reduced per-task invocation overhead, and they provide a means
+    #   > of bounding and managing the resources, including threads, consumed
+    #   > when executing a collection of tasks. Each ThreadPoolExecutor also
+    #   > maintains some basic statistics, such as the number of completed tasks.
+    #   >
+    #   > To be useful across a wide range of contexts, this class provides many
+    #   > adjustable parameters and extensibility hooks. However, programmers are
+    #   > urged to use the more convenient Executors factory methods
+    #   > [CachedThreadPool] (unbounded thread pool, with automatic thread reclamation),
+    #   > [FixedThreadPool] (fixed size thread pool) and [SingleThreadExecutor] (single
+    #   > background thread), that preconfigure settings for the most common usage
+    #   > scenarios.
+    #
+    #   Thread pools support several configuration options:
+    #
+    #   * `max_threads`: The maximum number of threads that may be created in the pool.
+    #   * `min_threads`: The minimum number of threads that may be retained in the pool.
+    #   * `idletime`: The number of seconds that a thread may be idle before being reclaimed.
+    #   * `max_queue`: The maximum number of tasks that may be waiting in the work queue at
+    #     any one time. When the queue size reaches `max_queue` subsequent tasks will be
+    #     rejected in accordance with the configured `overflow_policy`.
+    #   * `overflow_policy`: The policy defining how rejected tasks are handled.    #
+    #
+    #   Three overflow policies are supported:
+    #
+    #   * `:abort`: Raise a `RejectedExecutionError` exception and discard the task.
+    #   * `:discard`: Silently discard the task and return `nil` as the task result.
+    #   * `:caller_runs`: Execute the task on the calling thread.
+    #
+    #   @note When running on the JVM (JRuby) this class will inherit from `JavaThreadPoolExecutor`.
+    #     On all other platforms it will inherit from `RubyThreadPoolExecutor`.
+    #
+    #   @see Concurrent::RubyThreadPoolExecutor
+    #   @see Concurrent::JavaThreadPoolExecutor
+    #
+    #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
+    #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
+    #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html
+    class ThreadPoolExecutor < JavaThreadPoolExecutor
+    end
+  else
+    # @!macro thread_pool_executor
+    class ThreadPoolExecutor < RubyThreadPoolExecutor
+    end
+  end
+end

data/lib/concurrent/executor/timer_set.rb

@@ -0,0 +1,138 @@
+require 'thread'
+require_relative 'executor'
+require 'concurrent/options_parser'
+require 'concurrent/atomic/event'
+require 'concurrent/collection/priority_queue'
+require 'concurrent/executor/single_thread_executor'
+
+module Concurrent
+
+  # Executes a collection of tasks at the specified times. A master thread
+  # monitors the set and schedules each task for execution at the appropriate
+  # time. Tasks are run on the global task pool or on the supplied executor.
+  class TimerSet
+    include Executor
+
+    # Create a new set of timed tasks.
+    #
+    # @param [Hash] opts the options controlling how the future will be processed
+    # @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)
+    def initialize(opts = {})
+      @queue = PriorityQueue.new(order: :min)
+      @task_executor = OptionsParser::get_executor_from(opts)
+      @timer_executor = SingleThreadExecutor.new
+      @condition = Condition.new
+      init_executor
+    end
+
+    # Post a task to be execute at the specified time. The given time may be either
+    # a `Time` object or the number of seconds to wait. If the intended execution
+    # time is within 1/100th of a second of the current time the task will be
+    # immediately post to the executor.
+    #
+    # @param [Object] intended_time the time to schedule the task for execution
+    #
+    # @yield the task to be performed
+    #
+    # @return [Boolean] true if the message is post, false after shutdown
+    #
+    # @raise [ArgumentError] if the intended execution time is not in the future
+    # @raise [ArgumentError] if no block is given
+    def post(intended_time, *args, &task)
+      time = TimerSet.calculate_schedule_time(intended_time).to_f
+      raise ArgumentError.new('no block given') unless block_given?
+
+      mutex.synchronize do
+        return false unless running?
+
+        if (time - Time.now.to_f) <= 0.01
+          @task_executor.post(*args, &task)
+        else
+          @queue.push(Task.new(time, args, task))
+          @timer_executor.post(&method(:process_tasks))
+        end
+
+        true
+      end
+
+    end
+
+    alias_method :kill, :shutdown
+
+    # Calculate an Epoch time with milliseconds at which to execute a
+    # task. If the given time is a `Time` object it will be converted
+    # accordingly. If the time is an integer value greater than zero
+    # it will be understood as a number of seconds in the future and
+    # will be added to the current time to calculate Epoch.
+    #
+    # @param [Object] intended_time the time (as a `Time` object or an integer)
+    #   to schedule the task for execution
+    # @param [Time] now (Time.now) the time from which to calculate an interval
+    #
+    # @return [Fixnum] the intended time as seconds/millis from Epoch
+    #
+    # @raise [ArgumentError] if the intended execution time is not in the future
+    def self.calculate_schedule_time(intended_time, now = Time.now)
+      if intended_time.is_a?(Time)
+        raise ArgumentError.new('schedule time must be in the future') if intended_time <= now
+        intended_time
+      else
+        raise ArgumentError.new('seconds must be greater than zero') if intended_time.to_f < 0.0
+        now + intended_time
+      end
+    end
+
+    private
+
+    # A struct for encapsulating a task and its intended execution time.
+    # It facilitates proper prioritization by overriding the comparison
+    # (spaceship) operator as a comparison of the intended execution
+    # times.
+    #
+    # @!visibility private
+    Task = Struct.new(:time, :args, :op) do
+      include Comparable
+
+      def <=>(other)
+        self.time <=> other.time
+      end
+    end
+
+    private_constant :Task
+
+    # @!visibility private
+    def shutdown_execution
+      @queue.clear
+      @timer_executor.kill
+      stopped_event.set
+    end
+
+    # Run a loop and execute tasks in the scheduled order and at the approximate
+    # scheduled time. If no tasks remain the thread will exit gracefully so that
+    # garbage collection can occur. If there are no ready tasks it will sleep
+    # for up to 60 seconds waiting for the next scheduled task.
+    #
+    # @!visibility private
+    def process_tasks
+      loop do
+        break if @queue.empty?
+
+        task = @queue.peek
+        interval = task.time - Time.now.to_f
+
+        if interval <= 0
+          @task_executor.post(*task.args, &task.op)
+          @queue.pop
+        else
+          mutex.synchronize do
+            @condition.wait(mutex, [interval, 60].min)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/executors.rb

@@ -0,0 +1,9 @@
+require 'concurrent/executor/cached_thread_pool'
+require 'concurrent/executor/fixed_thread_pool'
+require 'concurrent/executor/immediate_executor'
+require 'concurrent/executor/per_thread_executor'
+require 'concurrent/executor/safe_task_executor'
+require 'concurrent/executor/single_thread_executor'
+require 'concurrent/executor/thread_pool_executor'
+require 'concurrent/executor/timer_set'
+require 'concurrent/executor/one_by_one'

data/lib/concurrent/future.rb

@@ -1,61 +1,60 @@
 require 'thread'
 
-require 'concurrent/configuration'
 require 'concurrent/obligation'
-require 'concurrent/safe_task_executor'
+require 'concurrent/options_parser'
+require 'concurrent/executor/safe_task_executor'
 
 module Concurrent
 
-  # A +Future+ represents a promise to complete an action at some time in the future.
+  # A `Future` represents a promise to complete an action at some time in the future.
   # The action is atomic and permanent. The idea behind a future is to send an operation
   # for asynchronous completion, do other stuff, then return and retrieve the result
   # of the async operation at a later time.
   #
-  # A +Future+ has four possible states: *:unscheduled*, *:pending*, *:rejected*, or *:fulfilled*.
-  # When a +Future+ is created its state is set to *:unscheduled*. Once the +#execute+ method is
+  # A `Future` has four possible states: *:unscheduled*, *:pending*, *:rejected*, or *:fulfilled*.
+  # When a `Future` is created its state is set to *:unscheduled*. Once the `#execute` method is
   # called the state becomes *:pending* and will remain in that state until processing is
-  # complete. A completed +Future+ is either *:rejected*, indicating that an exception was
-  # thrown during processing, or *:fulfilled*, indicating success. If a +Future+ is *:fulfilled*
-  # its +value+ will be updated to reflect the result of the operation. If *:rejected* the
-  # +reason+ will be updated with a reference to the thrown exception. The predicate methods
-  # +#unscheduled?+, +#pending?+, +#rejected?+, and +fulfilled?+ can be called at any time to
-  # obtain the state of the +Future+, as can the +#state+ method, which returns a symbol. 
+  # complete. A completed `Future` is either *:rejected*, indicating that an exception was
+  # thrown during processing, or *:fulfilled*, indicating success. If a `Future` is *:fulfilled*
+  # its `value` will be updated to reflect the result of the operation. If *:rejected* the
+  # `reason` will be updated with a reference to the thrown exception. The predicate methods
+  # `#unscheduled?`, `#pending?`, `#rejected?`, and `fulfilled?` can be called at any time to
+  # obtain the state of the `Future`, as can the `#state` method, which returns a symbol. 
   #
-  # Retrieving the value of a +Future+ is done through the +#value+ (alias: +#deref+) method.
-  # Obtaining the value of a +Future+ is a potentially blocking operation. When a +Future+ is
-  # *:rejected* a call to +#value+ will return +nil+ immediately. When a +Future+ is
-  # *:fulfilled* a call to +#value+ will immediately return the current value. When a
-  # +Future+ is *:pending* a call to +#value+ will block until the +Future+ is either
-  # *:rejected* or *:fulfilled*. A *timeout* value can be passed to +#value+ to limit how
-  # long the call will block. If +nil+ the call will block indefinitely. If +0+ the call will
+  # Retrieving the value of a `Future` is done through the `#value` (alias: `#deref`) method.
+  # Obtaining the value of a `Future` is a potentially blocking operation. When a `Future` is
+  # *:rejected* a call to `#value` will return `nil` immediately. When a `Future` is
+  # *:fulfilled* a call to `#value` will immediately return the current value. When a
+  # `Future` is *:pending* a call to `#value` will block until the `Future` is either
+  # *:rejected* or *:fulfilled*. A *timeout* value can be passed to `#value` to limit how
+  # long the call will block. If `nil` the call will block indefinitely. If `0` the call will
   # not block. Any other integer or float value will indicate the maximum number of seconds to block.
   #
-  # The +Future+ class also includes the behavior of the Ruby standard library +Observable+ module,
+  # The `Future` class also includes the behavior of the Ruby standard library `Observable` module,
   # but does so in a thread-safe way. On fulfillment or rejection all observers will be notified
-  # according to the normal +Observable+ behavior. The observer callback function will be called
-  # with three parameters: the +Time+ of fulfillment/rejection, the final +value+, and the final
-  # +reason+. Observers added after fulfillment/rejection will still be notified as normal.
+  # according to the normal `Observable` behavior. The observer callback function will be called
+  # with three parameters: the `Time` of fulfillment/rejection, the final `value`, and the final
+  # `reason`. Observers added after fulfillment/rejection will still be notified as normal.
   #
   # @see http://ruby-doc.org/stdlib-2.1.1/libdoc/observer/rdoc/Observable.html Ruby Observable module
   # @see http://clojuredocs.org/clojure_core/clojure.core/future Clojure's future function
   # @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Future.html java.util.concurrent.Future
   class Future < IVar
     include Obligation
-    include OptionsParser
 
-    # Create a new +Future+ in the +:unscheduled+ state.
+    # Create a new `Future` in the `:unscheduled` state.
     #
     # @yield the asynchronous operation to perform
     #
-    # @param [Hash] opts the options to create a message with
-    # @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
+    # @param [Hash] opts the options controlling how the future will be processed
+    # @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
+    # @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
     #
     # @raise [ArgumentError] if no block is given
@@ -64,14 +63,14 @@ module Concurrent
       super(IVar::NO_VALUE, opts)
       @state = :unscheduled
       @task = block
-      @executor = get_executor_from(opts)
+      @executor = OptionsParser::get_executor_from(opts)
     end
 
-    # Execute an +:unscheduled+ +Future+. Immediately sets the state to +:pending+ and
+    # Execute an `:unscheduled` `Future`. Immediately sets the state to `:pending` and
     # passes the block to a new thread/thread pool for eventual execution.
-    # Does nothing if the +Future+ is in any state other than +:unscheduled+.
+    # Does nothing if the `Future` is in any state other than `:unscheduled`.
     #
-    # @return [Future] a reference to +self+
+    # @return [Future] a reference to `self`
     #
     # @example Instance and execute in separate steps
     #   future = Concurrent::Future.new{ sleep(1); 42 }
@@ -91,17 +90,17 @@ module Concurrent
       end
     end
 
-    # Create a new +Future+ object with the given block, execute it, and return the
-    # +:pending+ object.
+    # Create a new `Future` object with the given block, execute it, and return the
+    # `:pending` object.
     #
     # @yield the asynchronous operation to perform
     #
-    # @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
+    # @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
     #
-    # @return [Future] the newly created +Future+ in the +:pending+ state
+    # @return [Future] the newly created `Future` in the `:pending` state
     #
     # @raise [ArgumentError] if no block is given
     #