concurrent-ruby 0.8.0.pre2-java → 0.9.0-java

data/lib/concurrent/executor/safe_task_executor.rb

@@ -1,4 +1,4 @@
-require 'thread'
+require 'concurrent/synchronization'
 
 module Concurrent
 
@@ -6,17 +6,18 @@ module Concurrent
   # success - indicating if the callable has been executed without errors
   # 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
+  class SafeTaskExecutor < Synchronization::Object
 
     def initialize(task, opts = {})
+      super()
       @task = task
-      @mutex = Mutex.new
       @exception_class = opts.fetch(:rescue_exception, false) ? Exception : StandardError
+      ensure_ivar_visibility!
     end
 
     # @return [Array]
     def execute(*args)
-      @mutex.synchronize do
+      synchronize do
         success = false
         value = reason = nil
 

data/lib/concurrent/executor/serialized_execution.rb

@@ -1,14 +1,18 @@
 require 'delegate'
-require 'concurrent/executor/executor'
-require 'concurrent/logging'
-require 'concurrent/atomic/synchronization'
+require 'concurrent/executor/executor_service'
+require 'concurrent/concern/logging'
+require 'concurrent/synchronization'
 
 module Concurrent
 
   # Ensures passed jobs in a serialized order never running at the same time.
-  class SerializedExecution
-    include Logging
-    include Synchronization
+  class SerializedExecution < Synchronization::Object
+    include Concern::Logging
+
+    def initialize()
+      super()
+      synchronize { ns_initialize }
+    end
 
     Job = Struct.new(:executor, :args, :block) do
       def call
@@ -16,13 +20,6 @@ module Concurrent
       end
     end
 
-    def initialize
-      synchronize do
-        @being_executed = false
-        @stash          = []
-      end
-    end
-
     # Submit a task to the executor for asynchronous processing.
     #
     # @param [Executor] executor to be used for this job
@@ -69,7 +66,12 @@ module Concurrent
       true
     end
 
-    private
+    protected
+
+    def ns_initialize
+      @being_executed = false
+      @stash          = []
+    end
 
     def call_job(job)
       did_it_run = begin
@@ -98,17 +100,19 @@ module Concurrent
         job = @stash.shift || (@being_executed = false)
       end
 
+      # TODO maybe be able to tell caching pool to just enqueue this job, because the current one end at the end
+      # of this block
       call_job job if job
     end
   end
 
-  # A wrapper/delegator for any `Executor` or `ExecutorService` that
+  # A wrapper/delegator for any `ExecutorService` that
   # guarantees serialized execution of tasks.
   #
   # @see [SimpleDelegator](http://www.ruby-doc.org/stdlib-2.1.2/libdoc/delegate/rdoc/SimpleDelegator.html)
   # @see Concurrent::SerializedExecution
   class SerializedExecutionDelegator < SimpleDelegator
-    include SerialExecutor
+    include SerialExecutorService
 
     def initialize(executor)
       @executor   = executor
@@ -116,9 +120,9 @@ module Concurrent
       super(executor)
     end
 
-    # @!macro executor_method_post
+    # @!macro executor_service_method_post
     def post(*args, &task)
-      raise ArgumentError.new('no block given') unless block_given?
+      Kernel.raise ArgumentError.new('no block given') unless block_given?
       return false unless running?
       @serializer.post(@executor, *args, &task)
     end

data/lib/concurrent/executor/{per_thread_executor.rb → simple_executor_service.rb}

@@ -1,5 +1,5 @@
 require 'concurrent/atomics'
-require 'concurrent/executor/executor'
+require 'concurrent/executor/executor_service'
 
 module Concurrent
 
@@ -15,17 +15,9 @@ module Concurrent
   # lead to suboptimal performance.
   #
   # @note Intended for use primarily in testing and debugging.
-  class PerThreadExecutor
-    include Executor
+  class SimpleExecutorService < RubyExecutorService
 
-    # Creates a new executor
-    def initialize
-      @running = Concurrent::AtomicBoolean.new(true)
-      @stopped = Concurrent::Event.new
-      @count = Concurrent::AtomicFixnum.new(0)
-    end
-
-    # @!macro executor_method_post
+    # @!macro executor_service_method_post
     def self.post(*args)
       raise ArgumentError.new('no block given') unless block_given?
       Thread.new(*args) do
@@ -35,13 +27,13 @@ module Concurrent
       true
     end
 
-    # @!macro executor_method_left_shift
+    # @!macro executor_service_method_left_shift
     def self.<<(task)
       post(&task)
       self
     end
 
-    # @!macro executor_method_post
+    # @!macro executor_service_method_post
     def post(*args, &task)
       raise ArgumentError.new('no block given') unless block_given?
       return false unless running?
@@ -57,44 +49,61 @@ module Concurrent
       end
     end
 
-    # @!macro executor_method_left_shift
+    # @!macro executor_service_method_left_shift
     def <<(task)
       post(&task)
       self
     end
 
-    # @!macro executor_method_running_question
+    # @!macro executor_service_method_running_question
     def running?
       @running.true?
     end
 
-    # @!macro executor_method_shuttingdown_question
+    # @!macro executor_service_method_shuttingdown_question
     def shuttingdown?
       @running.false? && ! @stopped.set?
     end
 
-    # @!macro executor_method_shutdown_question
+    # @!macro executor_service_method_shutdown_question
     def shutdown?
       @stopped.set?
     end
 
-    # @!macro executor_method_shutdown
+    # @!macro executor_service_method_shutdown
     def shutdown
       @running.make_false
       @stopped.set if @count.value == 0
       true
     end
 
-    # @!macro executor_method_kill
+    # @!macro executor_service_method_kill
     def kill
       @running.make_false
       @stopped.set
       true
     end
 
-    # @!macro executor_method_wait_for_termination
+    # @!macro executor_service_method_wait_for_termination
     def wait_for_termination(timeout = nil)
       @stopped.wait(timeout)
     end
+
+    protected
+
+    def ns_initialize
+      @running = Concurrent::AtomicBoolean.new(true)
+      @stopped = Concurrent::Event.new
+      @count = Concurrent::AtomicFixnum.new(0)
+    end
+  end
+
+  # @deprecated
+  class PerThreadExecutor < SimpleExecutorService
+
+    def initialize
+      deprecated 'use SimpleExecutorService instead'
+      super
+    end
   end
 end

data/lib/concurrent/executor/single_thread_executor.rb

@@ -2,34 +2,45 @@ require 'concurrent/executor/ruby_single_thread_executor'
 
 module Concurrent
 
-  if RUBY_PLATFORM == 'java'
-
+  if Concurrent.on_jruby?
     require 'concurrent/executor/java_single_thread_executor'
+  end
 
-    # @!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`
+  SingleThreadExecutorImplementation = case
+                                       when Concurrent.on_jruby?
+                                         JavaSingleThreadExecutor
+                                       else
+                                         RubySingleThreadExecutor
+                                       end
+  private_constant :SingleThreadExecutorImplementation
+
+  # @!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`
+  #
+  # @!macro thread_pool_options
+  # @!macro abstract_executor_service_public_api
+  class SingleThreadExecutor < SingleThreadExecutorImplementation
+
+    # @!macro [new] single_thread_executor_method_initialize
     #
-    #   @note When running on the JVM (JRuby) this class will inherit from `JavaSingleThreadExecutor`.
-    #     On all other platforms it will inherit from `RubySingleThreadExecutor`.
+    #   Create a new thread pool.
     #
-    #   @see Concurrent::RubySingleThreadExecutor
-    #   @see Concurrent::JavaSingleThreadExecutor
+    #   @option opts [Symbol] :fallback_policy (:discard) the policy for
+    #     handling new tasks that are received when the queue size has
+    #     reached `max_queue` or after the executor has shut down
     #
     #   @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
+
+    # @!method initialize(opts = {})
+    #   @!macro single_thread_executor_method_initialize
   end
 end

data/lib/concurrent/executor/thread_pool_executor.rb

@@ -1,68 +1,81 @@
+require 'concurrent/utility/engine'
 require 'concurrent/executor/ruby_thread_pool_executor'
 
 module Concurrent
 
-  if RUBY_PLATFORM == 'java'
+  if Concurrent.on_jruby?
     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 `fallback_policy`.
-    #   * `fallback_policy`: The policy defining how rejected tasks are handled.    #
-    #
-    #   Three fallback policies are supported:
-    #
-    #   * `:abort`: Raise a `RejectedExecutionError` exception and discard the task.
-    #   * `:discard`: Discard the task and return false.
-    #   * `: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
+  end
+
+  ThreadPoolExecutorImplementation = case
+                                     when Concurrent.on_jruby?
+                                       JavaThreadPoolExecutor
+                                     else
+                                       RubyThreadPoolExecutor
+                                     end
+  private_constant :ThreadPoolExecutorImplementation
+
+  # @!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.
+  #
+  # @!macro thread_pool_options
+  #
+  # @!macro thread_pool_executor_public_api
+  class ThreadPoolExecutor < ThreadPoolExecutorImplementation
+
+    # @!macro [new] thread_pool_executor_method_initialize
     #
-    #   @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
+    #   Create a new thread pool.
+    #  
+    #   @param [Hash] opts the options which configure the thread pool.
+    #  
+    #   @option opts [Integer] :max_threads (DEFAULT_MAX_POOL_SIZE) the maximum
+    #     number of threads to be created
+    #   @option opts [Integer] :min_threads (DEFAULT_MIN_POOL_SIZE) the minimum
+    #     number of threads to be retained
+    #   @option opts [Integer] :idletime (DEFAULT_THREAD_IDLETIMEOUT) the maximum
+    #     number of seconds a thread may be idle before being reclaimed
+    #   @option opts [Integer] :max_queue (DEFAULT_MAX_QUEUE_SIZE) the maximum
+    #     number of tasks allowed in the work queue at any one time; a value of
+    #     zero means the queue may grow without bound
+    #   @option opts [Symbol] :fallback_policy (:abort) the policy for handling new
+    #     tasks that are received when the queue size has reached
+    #     `max_queue` or the executor has shut down
+    #  
+    #   @raise [ArgumentError] if `:max_threads` is less than one
+    #   @raise [ArgumentError] if `:min_threads` is less than zero
+    #   @raise [ArgumentError] if `:fallback_policy` is not one of the values specified
+    #     in `FALLBACK_POLICIES`
+    #  
+    #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ThreadPoolExecutor.html
+
+    # @!method initialize(opts = {})
+    #   @!macro thread_pool_executor_method_initialize
   end
 end

data/lib/concurrent/executor/timer_set.rb

@@ -1,114 +1,126 @@
-require 'thread'
-require_relative 'executor'
-require 'concurrent/options_parser'
+require 'concurrent/scheduled_task'
 require 'concurrent/atomic/event'
 require 'concurrent/collection/priority_queue'
+require 'concurrent/concern/deprecation'
+require 'concurrent/executor/executor_service'
 require 'concurrent/executor/single_thread_executor'
 
 module Concurrent
 
-  # Executes a collection of tasks at the specified times. A master thread
+  # Executes a collection of tasks, each after a given delay. A master task
   # 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 RubyExecutor
+  # time. Tasks are run on the global thread pool or on the supplied executor.
+  # Each task is represented as a `ScheduledTask`.
+  #
+  # @see Concurrent::ScheduledTask
+  #
+  # @!macro monotonic_clock_warning
+  class TimerSet < RubyExecutorService
+    extend Concern::Deprecation
 
     # 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)
+    # @!macro [attach] executor_options
+    #  
+    #   @param [Hash] opts the options used to specify the executor on which to perform actions
+    #   @option opts [Executor] :executor when set use the given `Executor` instance.
+    #     Three special values are also supported: `:task` returns the global task pool,
+    #     `:operation` returns the global operation pool, and `:immediate` returns a new
+    #     `ImmediateExecutor` object.
     def initialize(opts = {})
-      @queue          = PriorityQueue.new(order: :min)
-      @task_executor  = OptionsParser::get_executor_from(opts) || Concurrent.configuration.global_task_pool
-      @timer_executor = SingleThreadExecutor.new
-      @condition      = Condition.new
-      init_executor
+      super(opts)
     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.
+    # Post a task to be execute run after a given delay (in seconds). If the
+    # delay is less than 1/100th of a second the task will be immediately post
+    # to the executor.
+    #
+    # @param [Float] delay the number of seconds to wait for before executing the task.
+    # @param [Array<Object>] args the arguments passed to the task on execution.
     #
-    # @param [Object] intended_time the time to schedule the task for execution
+    # @yield the task to be performed.
     #
-    # @yield the task to be performed
+    # @return [Concurrent::ScheduledTask, false] IVar representing the task if the post
+    #   is successful; false after shutdown.
     #
-    # @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.
     #
-    # @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
+    # @!macro deprecated_scheduling_by_clock_time
+    def post(delay, *args, &task)
       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
-      end
-
-      @condition.signal
-      true
+      return false unless running?
+      opts = {
+        executor: @task_executor,
+        args: args,
+        timer_set: self
+      }
+      task = ScheduledTask.execute(delay, opts, &task) # may raise exception
+      task.unscheduled? ? false : task
     end
 
-    # For a timer, #kill is like an orderly shutdown, except we need to manually
-    # (and destructively) clear the queue first
+    # Begin an immediate shutdown. In-progress tasks will be allowed to
+    # complete but enqueued tasks will be dismissed and no new tasks
+    # will be accepted. Has no additional effect if the thread pool is
+    # not running.
     def kill
-      mutex.synchronize { @queue.clear }
       shutdown
     end
 
-    # 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.
+    private :<<
+
+    protected
+
+    # Initialize the object.
     #
-    # @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
+    # @param [Hash] opts the options to create the object with.
+    # @!visibility private
+    def ns_initialize(opts)
+      @queue          = Collection::PriorityQueue.new(order: :min)
+      @task_executor  = Executor.executor_from_options(opts) || Concurrent.global_io_executor
+      @timer_executor = SingleThreadExecutor.new
+      @condition      = Event.new
+      self.auto_terminate = opts.fetch(:auto_terminate, true)
+    end
+
+    # Post the task to the internal queue.
     #
-    # @return [Fixnum] the intended time as seconds/millis from Epoch
+    # @note This is intended as a callback method from ScheduledTask
+    #   only. It is not intended to be used directly. Post a task
+    #   by using the `SchedulesTask#execute` method.
     #
-    # @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
+    # @!visibility private
+    def post_task(task)
+      synchronize{ ns_post_task(task) }
+    end
+
+    # @!visibility private
+    def ns_post_task(task)
+      return false unless ns_running?
+      if (task.initial_delay) <= 0.01
+        task.executor.post{ task.process_task }
       else
-        raise ArgumentError.new('seconds must be greater than zero') if intended_time.to_f < 0.0
-        now + intended_time
+        @queue.push(task)
+        # only post the process method when the queue is empty
+        @timer_executor.post(&method(:process_tasks)) if @queue.length == 1
+        @condition.set
       end
+      true
     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.
+    # Remove the given task from the queue.
+    #
+    # @note This is intended as a callback method from `ScheduledTask`
+    #   only. It is not intended to be used directly. Cancel a task
+    #   by using the `ScheduledTask#cancel` method.
     #
     # @!visibility private
-    Task = Struct.new(:time, :args, :op) do
-      include Comparable
-
-      def <=>(other)
-        self.time <=> other.time
-      end
+    def remove_task(task)
+      synchronize{ @queue.delete(task) }
     end
 
-    private_constant :Task
-
+    # `ExecutorServic` callback called during shutdown.
+    #
     # @!visibility private
     def shutdown_execution
       @queue.clear
@@ -124,11 +136,13 @@ module Concurrent
     # @!visibility private
     def process_tasks
       loop do
-        task = mutex.synchronize { @queue.peek }
+        task = synchronize { @condition.reset; @queue.peek }
         break unless task
-        interval = task.time - Time.now.to_f
 
-        if interval <= 0
+        now = Concurrent.monotonic_time
+        diff = task.schedule_time - now
+
+        if diff <= 0
           # We need to remove the task from the queue before passing
           # it to the executor, to avoid race conditions where we pass
           # the peek'ed task to the executor and then pop a different
@@ -141,12 +155,10 @@ module Concurrent
           # the only reader, so whatever timer is at the head of the
           # queue now must have the same pop time, or a closer one, as
           # when we peeked).
-          task = mutex.synchronize { @queue.pop }
-          @task_executor.post(*task.args, &task.op)
+          task = synchronize { @queue.pop }
+          task.executor.post{ task.process_task }
         else
-          mutex.synchronize do
-            @condition.wait(mutex, [interval, 60].min)
-          end
+          @condition.wait([diff, 60].min)
         end
       end
     end