o-concurrent-ruby 1.1.11

data/lib/concurrent-ruby/concurrent/executor/single_thread_executor.rb

@@ -0,0 +1,57 @@
+require 'concurrent/utility/engine'
+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-ruby/concurrent/executor/thread_pool_executor.rb

@@ -0,0 +1,88 @@
+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
+    #   @option opts [Boolean] :synchronous (DEFAULT_SYNCHRONOUS) whether or not a value of 0
+    #     for :max_queue means the queue must perform direct hand-off rather than unbounded.
+    #   @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-ruby/concurrent/executor/timer_set.rb

@@ -0,0 +1,172 @@
+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
+    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-ruby/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'

data/lib/concurrent-ruby/concurrent/future.rb

@@ -0,0 +1,141 @@
+require 'thread'
+require 'concurrent/constants'
+require 'concurrent/errors'
+require 'concurrent/ivar'
+require 'concurrent/executor/safe_task_executor'
+
+require 'concurrent/options'
+
+# TODO (pitr-ch 14-Mar-2017): deprecate, Future, Promise, etc.
+
+
+module Concurrent
+
+  # {include:file:docs-source/future.md}
+  #
+  # @!macro copy_options
+  #
+  # @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
+
+    # Create a new `Future` in the `:unscheduled` state.
+    #
+    # @yield the asynchronous operation to perform
+    #
+    # @!macro executor_and_deref_options
+    #
+    # @option opts [object, Array] :args zero or more arguments to be passed the task
+    #   block on execution
+    #
+    # @raise [ArgumentError] if no block is given
+    def initialize(opts = {}, &block)
+      raise ArgumentError.new('no block given') unless block_given?
+      super(NULL, opts.merge(__task_from_block__: block), &nil)
+    end
+
+    # 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`.
+    #
+    # @return [Future] a reference to `self`
+    #
+    # @example Instance and execute in separate steps
+    #   future = Concurrent::Future.new{ sleep(1); 42 }
+    #   future.state #=> :unscheduled
+    #   future.execute
+    #   future.state #=> :pending
+    #
+    # @example Instance and execute in one line
+    #   future = Concurrent::Future.new{ sleep(1); 42 }.execute
+    #   future.state #=> :pending
+    def execute
+      if compare_and_set_state(:pending, :unscheduled)
+        @executor.post{ safe_execute(@task, @args) }
+        self
+      end
+    end
+
+    # Create a new `Future` object with the given block, execute it, and return the
+    # `:pending` object.
+    #
+    # @yield the asynchronous operation to perform
+    #
+    # @!macro executor_and_deref_options
+    #
+    # @option opts [object, Array] :args zero or more arguments to be passed the task
+    #   block on execution
+    #
+    # @raise [ArgumentError] if no block is given
+    #
+    # @return [Future] the newly created `Future` in the `:pending` state
+    #
+    # @example
+    #   future = Concurrent::Future.execute{ sleep(1); 42 }
+    #   future.state #=> :pending
+    def self.execute(opts = {}, &block)
+      Future.new(opts, &block).execute
+    end
+
+    # @!macro ivar_set_method
+    def set(value = NULL, &block)
+      check_for_block_or_value!(block_given?, value)
+      synchronize do
+        if @state != :unscheduled
+          raise MultipleAssignmentError
+        else
+          @task = block || Proc.new { value }
+        end
+      end
+      execute
+    end
+
+    # Attempt to cancel the operation if it has not already processed.
+    # The operation can only be cancelled while still `pending`. It cannot
+    # be cancelled once it has begun processing or has completed.
+    #
+    # @return [Boolean] was the operation successfully cancelled.
+    def cancel
+      if compare_and_set_state(:cancelled, :pending)
+        complete(false, nil, CancelledOperationError.new)
+        true
+      else
+        false
+      end
+    end
+
+    # Has the operation been successfully cancelled?
+    #
+    # @return [Boolean]
+    def cancelled?
+      state == :cancelled
+    end
+
+    # Wait the given number of seconds for the operation to complete.
+    # On timeout attempt to cancel the operation.
+    #
+    # @param [Numeric] timeout the maximum time in seconds to wait.
+    # @return [Boolean] true if the operation completed before the timeout
+    #   else false
+    def wait_or_cancel(timeout)
+      wait(timeout)
+      if complete?
+        true
+      else
+        cancel
+        false
+      end
+    end
+
+    protected
+
+    def ns_initialize(value, opts)
+      super
+      @state = :unscheduled
+      @task = opts[:__task_from_block__]
+      @executor = Options.executor_from_options(opts) || Concurrent.global_io_executor
+      @args = get_arguments_from(opts)
+    end
+  end
+end

data/lib/concurrent-ruby/concurrent/hash.rb

@@ -0,0 +1,59 @@
+require 'concurrent/utility/engine'
+require 'concurrent/thread_safe/util'
+
+module Concurrent
+
+  # @!macro concurrent_hash
+  #
+  #   A thread-safe subclass of Hash. This version locks against the object
+  #   itself for every method call, ensuring only one thread can be reading
+  #   or writing at a time. This includes iteration methods like `#each`,
+  #   which takes the lock repeatedly when reading an item.
+  #
+  #   @see http://ruby-doc.org/core/Hash.html Ruby standard library `Hash`
+
+  # @!macro internal_implementation_note
+  HashImplementation = case
+                       when Concurrent.on_cruby?
+                         # Hash is thread-safe in practice because CRuby runs
+                         # threads one at a time and does not do context
+                         # switching during the execution of C functions.
+                         ::Hash
+
+                       when Concurrent.on_jruby?
+                         require 'jruby/synchronized'
+
+                         class JRubyHash < ::Hash
+                           include JRuby::Synchronized
+                         end
+                         JRubyHash
+
+                       when Concurrent.on_rbx?
+                         require 'monitor'
+                         require 'concurrent/thread_safe/util/data_structures'
+
+                         class RbxHash < ::Hash
+                         end
+                         ThreadSafe::Util.make_synchronized_on_rbx RbxHash
+                         RbxHash
+
+                       when Concurrent.on_truffleruby?
+                         require 'concurrent/thread_safe/util/data_structures'
+
+                         class TruffleRubyHash < ::Hash
+                         end
+
+                         ThreadSafe::Util.make_synchronized_on_truffleruby TruffleRubyHash
+                         TruffleRubyHash
+
+                       else
+                         warn 'Possibly unsupported Ruby implementation'
+                         ::Hash
+                       end
+  private_constant :HashImplementation
+
+  # @!macro concurrent_hash
+  class Hash < HashImplementation
+  end
+
+end

data/lib/concurrent-ruby/concurrent/immutable_struct.rb

@@ -0,0 +1,101 @@
+require 'concurrent/synchronization/abstract_struct'
+require 'concurrent/synchronization'
+
+module Concurrent
+
+  # A thread-safe, immutable variation of Ruby's standard `Struct`.
+  #
+  # @see http://ruby-doc.org/core/Struct.html Ruby standard library `Struct`
+  module ImmutableStruct
+    include Synchronization::AbstractStruct
+
+    def self.included(base)
+      base.safe_initialization!
+    end
+
+    # @!macro struct_values
+    def values
+      ns_values
+    end
+
+    alias_method :to_a, :values
+
+    # @!macro struct_values_at
+    def values_at(*indexes)
+      ns_values_at(indexes)
+    end
+
+    # @!macro struct_inspect
+    def inspect
+      ns_inspect
+    end
+
+    alias_method :to_s, :inspect
+
+    # @!macro struct_merge
+    def merge(other, &block)
+      ns_merge(other, &block)
+    end
+
+    # @!macro struct_to_h
+    def to_h
+      ns_to_h
+    end
+
+    # @!macro struct_get
+    def [](member)
+      ns_get(member)
+    end
+
+    # @!macro struct_equality
+    def ==(other)
+      ns_equality(other)
+    end
+
+    # @!macro struct_each
+    def each(&block)
+      return enum_for(:each) unless block_given?
+      ns_each(&block)
+    end
+
+    # @!macro struct_each_pair
+    def each_pair(&block)
+      return enum_for(:each_pair) unless block_given?
+      ns_each_pair(&block)
+    end
+
+    # @!macro struct_select
+    def select(&block)
+      return enum_for(:select) unless block_given?
+      ns_select(&block)
+    end
+
+    private
+
+    # @!visibility private
+    def initialize_copy(original)
+      super(original)
+      ns_initialize_copy
+    end
+
+    # @!macro struct_new
+    def self.new(*args, &block)
+      clazz_name = nil
+      if args.length == 0
+        raise ArgumentError.new('wrong number of arguments (0 for 1+)')
+      elsif args.length > 0 && args.first.is_a?(String)
+        clazz_name = args.shift
+      end
+      FACTORY.define_struct(clazz_name, args, &block)
+    end
+
+    FACTORY = Class.new(Synchronization::LockableObject) do
+      def define_struct(name, members, &block)
+        synchronize do
+          Synchronization::AbstractStruct.define_struct_class(ImmutableStruct, Synchronization::Object, name, members, &block)
+        end
+      end
+    end.new
+    private_constant :FACTORY
+  end
+end