concurrent-ruby 1.1.5

data/lib/concurrent/executor/serialized_execution_delegator.rb

@@ -0,0 +1,28 @@
+require 'delegate'
+require 'concurrent/executor/serial_executor_service'
+require 'concurrent/executor/serialized_execution'
+
+module Concurrent
+
+  # 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 SerialExecutorService
+
+    def initialize(executor)
+      @executor   = executor
+      @serializer = SerializedExecution.new
+      super(executor)
+    end
+
+    # @!macro executor_service_method_post
+    def post(*args, &task)
+      raise ArgumentError.new('no block given') unless block_given?
+      return false unless running?
+      @serializer.post(@executor, *args, &task)
+    end
+  end
+end

data/lib/concurrent/executor/simple_executor_service.rb

@@ -0,0 +1,100 @@
+require 'concurrent/atomics'
+require 'concurrent/executor/executor_service'
+
+module Concurrent
+
+  # An executor service in which every operation spawns a new,
+  # independently operating thread.
+  #
+  # This is perhaps the most inefficient executor service in this
+  # library. It exists mainly for testing an debugging. Thread creation
+  # and management is expensive in Ruby and this executor performs no
+  # resource pooling. This can be very beneficial during testing and
+  # debugging because it decouples the using code from the underlying
+  # executor implementation. In production this executor will likely
+  # lead to suboptimal performance.
+  #
+  # @note Intended for use primarily in testing and debugging.
+  class SimpleExecutorService < RubyExecutorService
+
+    # @!macro executor_service_method_post
+    def self.post(*args)
+      raise ArgumentError.new('no block given') unless block_given?
+      Thread.new(*args) do
+        Thread.current.abort_on_exception = false
+        yield(*args)
+      end
+      true
+    end
+
+    # @!macro executor_service_method_left_shift
+    def self.<<(task)
+      post(&task)
+      self
+    end
+
+    # @!macro executor_service_method_post
+    def post(*args, &task)
+      raise ArgumentError.new('no block given') unless block_given?
+      return false unless running?
+      @count.increment
+      Thread.new(*args) do
+        Thread.current.abort_on_exception = false
+        begin
+          yield(*args)
+        ensure
+          @count.decrement
+          @stopped.set if @running.false? && @count.value == 0
+        end
+      end
+    end
+
+    # @!macro executor_service_method_left_shift
+    def <<(task)
+      post(&task)
+      self
+    end
+
+    # @!macro executor_service_method_running_question
+    def running?
+      @running.true?
+    end
+
+    # @!macro executor_service_method_shuttingdown_question
+    def shuttingdown?
+      @running.false? && ! @stopped.set?
+    end
+
+    # @!macro executor_service_method_shutdown_question
+    def shutdown?
+      @stopped.set?
+    end
+
+    # @!macro executor_service_method_shutdown
+    def shutdown
+      @running.make_false
+      @stopped.set if @count.value == 0
+      true
+    end
+
+    # @!macro executor_service_method_kill
+    def kill
+      @running.make_false
+      @stopped.set
+      true
+    end
+
+    # @!macro executor_service_method_wait_for_termination
+    def wait_for_termination(timeout = nil)
+      @stopped.wait(timeout)
+    end
+
+    private
+
+    def ns_initialize
+      @running = Concurrent::AtomicBoolean.new(true)
+      @stopped = Concurrent::Event.new
+      @count = Concurrent::AtomicFixnum.new(0)
+    end
+  end
+end

data/lib/concurrent/executor/single_thread_executor.rb

@@ -0,0 +1,56 @@
+require 'concurrent/executor/ruby_single_thread_executor'
+
+module Concurrent
+
+  if Concurrent.on_jruby?
+    require 'concurrent/executor/java_single_thread_executor'
+  end
+
+  SingleThreadExecutorImplementation = case
+                                       when Concurrent.on_jruby?
+                                         JavaSingleThreadExecutor
+                                       else
+                                         RubySingleThreadExecutor
+                                       end
+  private_constant :SingleThreadExecutorImplementation
+
+  # @!macro single_thread_executor
+  #
+  #   A thread pool with a single thread an unlimited queue. Should the thread
+  #   die for any reason it will be removed and replaced, thus ensuring that
+  #   the executor will always remain viable and available to process jobs.
+  #
+  #   A common pattern for background processing is to create a single thread
+  #   on which an infinite loop is run. The thread's loop blocks on an input
+  #   source (perhaps blocking I/O or a queue) and processes each input as it
+  #   is received. This pattern has several issues. The thread itself is highly
+  #   susceptible to errors during processing. Also, the thread itself must be
+  #   constantly monitored and restarted should it die. `SingleThreadExecutor`
+  #   encapsulates all these bahaviors. The task processor is highly resilient
+  #   to errors from within tasks. Also, should the thread die it will
+  #   automatically be restarted.
+  #
+  #   The API and behavior of this class are based on Java's `SingleThreadExecutor`.
+  #
+  # @!macro abstract_executor_service_public_api
+  class SingleThreadExecutor < SingleThreadExecutorImplementation
+
+    # @!macro single_thread_executor_method_initialize
+    #
+    #   Create a new thread pool.
+    #
+    #   @option opts [Symbol] :fallback_policy (:discard) 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 `:fallback_policy` is not one of the values specified
+    #     in `FALLBACK_POLICIES`
+    #
+    #   @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
+
+    # @!method initialize(opts = {})
+    #   @!macro single_thread_executor_method_initialize
+  end
+end

data/lib/concurrent/executor/thread_pool_executor.rb

@@ -0,0 +1,87 @@
+require 'concurrent/utility/engine'
+require 'concurrent/executor/ruby_thread_pool_executor'
+
+module Concurrent
+
+  if Concurrent.on_jruby?
+    require 'concurrent/executor/java_thread_pool_executor'
+  end
+
+  ThreadPoolExecutorImplementation = case
+                                     when Concurrent.on_jruby?
+                                       JavaThreadPoolExecutor
+                                     else
+                                       RubyThreadPoolExecutor
+                                     end
+  private_constant :ThreadPoolExecutorImplementation
+
+  # @!macro thread_pool_executor
+  #
+  #   An abstraction composed of one or more threads and a task queue. Tasks
+  #   (blocks or `proc` objects) are submitted 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.
+  #
+  #   A `ThreadPoolExecutor` will automatically adjust the pool size according
+  #   to the bounds set by `min-threads` and `max-threads`. When a new task is
+  #   submitted and fewer than `min-threads` threads are running, a new thread
+  #   is created to handle the request, even if other worker threads are idle.
+  #   If there are more than `min-threads` but less than `max-threads` threads
+  #   running, a new thread will be created only if the queue is full.
+  #
+  #   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 documentation;
+  #
+  #   > 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 thread_pool_executor_method_initialize
+    #
+    #   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) When a new task is submitted
+    #      and fewer than `min_threads` are running, a new thread is created
+    #   @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

@@ -0,0 +1,173 @@
+require 'concurrent/scheduled_task'
+require 'concurrent/atomic/event'
+require 'concurrent/collection/non_concurrent_priority_queue'
+require 'concurrent/executor/executor_service'
+require 'concurrent/executor/single_thread_executor'
+
+require 'concurrent/options'
+
+module Concurrent
+
+  # 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 thread pool or on the supplied executor.
+  # Each task is represented as a `ScheduledTask`.
+  #
+  # @see Concurrent::ScheduledTask
+  #
+  # @!macro monotonic_clock_warning
+  class TimerSet < RubyExecutorService
+
+    # Create a new set of timed tasks.
+    #
+    # @!macro 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 = {})
+      super(opts)
+    end
+
+    # 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.
+    #
+    # @yield the task to be performed.
+    #
+    # @return [Concurrent::ScheduledTask, false] IVar representing the task if the post
+    #   is successful; false after shutdown.
+    #
+    # @raise [ArgumentError] if the intended execution time is not in the future.
+    # @raise [ArgumentError] if no block is given.
+    def post(delay, *args, &task)
+      raise ArgumentError.new('no block given') unless block_given?
+      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
+
+    # 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
+      shutdown
+    end
+
+    private :<<
+
+    private
+
+    # Initialize the object.
+    #
+    # @param [Hash] opts the options to create the object with.
+    # @!visibility private
+    def ns_initialize(opts)
+      @queue              = Collection::NonConcurrentPriorityQueue.new(order: :min)
+      @task_executor      = Options.executor_from_options(opts) || Concurrent.global_io_executor
+      @timer_executor     = SingleThreadExecutor.new
+      @condition          = Event.new
+      @ruby_pid           = $$ # detects if Ruby has forked
+      self.auto_terminate = opts.fetch(:auto_terminate, true)
+    end
+
+    # Post the task to the internal queue.
+    #
+    # @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.
+    #
+    # @!visibility private
+    def post_task(task)
+      synchronize { ns_post_task(task) }
+    end
+
+    # @!visibility private
+    def ns_post_task(task)
+      return false unless ns_running?
+      ns_reset_if_forked
+      if (task.initial_delay) <= 0.01
+        task.executor.post { task.process_task }
+      else
+        @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
+
+    # 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
+    def remove_task(task)
+      synchronize { @queue.delete(task) }
+    end
+
+    # `ExecutorService` callback called during shutdown.
+    #
+    # @!visibility private
+    def ns_shutdown_execution
+      ns_reset_if_forked
+      @queue.clear
+      @timer_executor.kill
+      stopped_event.set
+    end
+
+    def ns_reset_if_forked
+      if $$ != @ruby_pid
+        @queue.clear
+        @condition.reset
+        @ruby_pid = $$
+      end
+    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
+        task = synchronize { @condition.reset; @queue.peek }
+        break unless task
+
+        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
+          # one that's been added in the meantime.
+          #
+          # Note that there's no race condition between the peek and
+          # this pop - this pop could retrieve a different task from
+          # the peek, but that task would be due to fire now anyway
+          # (because @queue is a priority queue, and this thread is
+          # 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 = synchronize { @queue.pop }
+          task.executor.post { task.process_task }
+        else
+          @condition.wait([diff, 60].min)
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/executors.rb

@@ -0,0 +1,20 @@
+require 'concurrent/executor/abstract_executor_service'
+require 'concurrent/executor/cached_thread_pool'
+require 'concurrent/executor/executor_service'
+require 'concurrent/executor/fixed_thread_pool'
+require 'concurrent/executor/immediate_executor'
+require 'concurrent/executor/indirect_immediate_executor'
+require 'concurrent/executor/java_executor_service'
+require 'concurrent/executor/java_single_thread_executor'
+require 'concurrent/executor/java_thread_pool_executor'
+require 'concurrent/executor/ruby_executor_service'
+require 'concurrent/executor/ruby_single_thread_executor'
+require 'concurrent/executor/ruby_thread_pool_executor'
+require 'concurrent/executor/cached_thread_pool'
+require 'concurrent/executor/safe_task_executor'
+require 'concurrent/executor/serial_executor_service'
+require 'concurrent/executor/serialized_execution'
+require 'concurrent/executor/serialized_execution_delegator'
+require 'concurrent/executor/single_thread_executor'
+require 'concurrent/executor/thread_pool_executor'
+require 'concurrent/executor/timer_set'