concurrent-ruby 1.0.0.pre1-java → 1.0.0.pre2-java

data/lib/concurrent/executor/single_thread_executor.rb

@@ -16,15 +16,22 @@ module Concurrent
 
   # @!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.
+  #   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.
   #
-  #   The API and behavior of this class are based on Java's `SingleThreadExecutor`
+  #   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 thread_pool_options
   # @!macro abstract_executor_service_public_api
   class SingleThreadExecutor < SingleThreadExecutorImplementation
 
@@ -32,9 +39,12 @@ module Concurrent
     #
     #   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 after the executor has shut down
+    #   @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

data/lib/concurrent/executor/timer_set.rb

@@ -6,6 +6,8 @@ require 'concurrent/executor/single_thread_executor'
 
 module Concurrent
 
+  autoload :Options, 'concurrent/options'
+
   # 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.
@@ -73,7 +75,7 @@ module Concurrent
     # @!visibility private
     def ns_initialize(opts)
       @queue          = Collection::NonConcurrentPriorityQueue.new(order: :min)
-      @task_executor  = Executor.executor_from_options(opts) || Concurrent.global_io_executor
+      @task_executor  = Options.executor_from_options(opts) || Concurrent.global_io_executor
       @timer_executor = SingleThreadExecutor.new
       @condition      = Event.new
       self.auto_terminate = opts.fetch(:auto_terminate, true)
@@ -115,7 +117,7 @@ module Concurrent
       synchronize{ @queue.delete(task) }
     end
 
-    # `ExecutorServic` callback called during shutdown.
+    # `ExecutorService` callback called during shutdown.
     #
     # @!visibility private
     def ns_shutdown_execution

data/lib/concurrent/executors.rb

@@ -1,6 +1,5 @@
 require 'concurrent/executor/abstract_executor_service'
 require 'concurrent/executor/cached_thread_pool'
-require 'concurrent/executor/executor'
 require 'concurrent/executor/executor_service'
 require 'concurrent/executor/fixed_thread_pool'
 require 'concurrent/executor/immediate_executor'

data/lib/concurrent/future.rb

@@ -1,11 +1,12 @@
 require 'thread'
 require 'concurrent/errors'
 require 'concurrent/ivar'
-require 'concurrent/executor/executor'
 require 'concurrent/executor/safe_task_executor'
 
 module Concurrent
 
+  autoload :Options, 'concurrent/options'
+
   # {include:file:doc/future.md}
   #
   # @!macro copy_options
@@ -129,7 +130,7 @@ module Concurrent
       super
       @state = :unscheduled
       @task = opts[:__task_from_block__]
-      @executor = Executor.executor_from_options(opts) || Concurrent.global_io_executor
+      @executor = Options.executor_from_options(opts) || Concurrent.global_io_executor
       @args = get_arguments_from(opts)
     end
   end

data/lib/concurrent/hash.rb

@@ -24,12 +24,12 @@ module Concurrent
 
   elsif Concurrent.on_rbx?
     require 'monitor'
+    require 'concurrent/thread_safe/util/array_hash_rbx'
 
     # @!macro concurrent_hash
     class Hash < ::Hash
     end
 
     ThreadSafe::Util.make_synchronized_on_rbx Hash
-
   end
 end

data/lib/concurrent/immutable_struct.rb

@@ -9,6 +9,10 @@ module Concurrent
   module ImmutableStruct
     include Synchronization::AbstractStruct
 
+    def self.included(base)
+      base.safe_initialization!
+    end
+
     # @!macro struct_values
     def values
       ns_values
@@ -77,7 +81,7 @@ module Concurrent
       FACTORY.define_struct(clazz_name, args, &block)
     end
 
-    FACTORY = Class.new(Synchronization::Object) do
+    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)

data/lib/concurrent/ivar.rb

@@ -43,7 +43,7 @@ module Concurrent
   #    In Proceedings of Workshop on Graph Reduction, 1986.
   # 2. For recent application:
   #    [DataDrivenFuture in Habanero Java from Rice](http://www.cs.rice.edu/~vs3/hjlib/doc/edu/rice/hj/api/HjDataDrivenFuture.html).
-  class IVar < Synchronization::Object
+  class IVar < Synchronization::LockableObject
     include Concern::Obligation
     include Concern::Observable
 

data/lib/concurrent/mutable_struct.rb

@@ -75,7 +75,7 @@ module Concurrent
     alias_method :to_s, :inspect
 
     # @!macro [attach] struct_merge
-    # 
+    #
     #   Returns a new struct containing the contents of `other` and the contents
     #   of `self`. If no block is specified, the value for entries with duplicate
     #   keys will be that of `other`. Otherwise the value for each duplicate key
@@ -98,7 +98,7 @@ module Concurrent
     # @!macro [attach] struct_to_h
     #
     #   Returns a hash containing the names and values for the struct’s members.
-    #   
+    #
     #   @return [Hash] the names and values for the struct’s members
     def to_h
       synchronize { ns_to_h }
@@ -184,8 +184,9 @@ module Concurrent
     #   @raise [IndexError] if the index is out of range.
     def []=(member, value)
       if member.is_a? Integer
-        if member >= @values.length
-          raise IndexError.new("offset #{member} too large for struct(size:#{@values.length})")
+        length = synchronize { @values.length }
+        if member >= length
+          raise IndexError.new("offset #{member} too large for struct(size:#{length})")
         end
         synchronize { @values[member] = value }
       else
@@ -206,10 +207,10 @@ module Concurrent
       FACTORY.define_struct(clazz_name, args, &block)
     end
 
-    FACTORY = Class.new(Synchronization::Object) do
+    FACTORY = Class.new(Synchronization::LockableObject) do
       def define_struct(name, members, &block)
         synchronize do
-          clazz = Synchronization::AbstractStruct.define_struct_class(MutableStruct, Synchronization::Object, name, members, &block)
+          clazz = Synchronization::AbstractStruct.define_struct_class(MutableStruct, Synchronization::LockableObject, name, members, &block)
           members.each_with_index do |member, index|
             clazz.send(:define_method, member) do
               synchronize { @values[index] }

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

@@ -1,10 +1,11 @@
-# This file has circular require issues. For now we assume all
-# necessary dependencies have been required already.
+# This file has circular require issues. It must be autoloaded.
+
+require 'concurrent/configuration'
 
 module Concurrent
 
   # @!visibility private
-  module Executor
+  module Options
 
     # Get the requested `Executor` based on the values set in the options hash.
     #

data/lib/concurrent/promise.rb

@@ -1,10 +1,11 @@
 require 'thread'
 require 'concurrent/errors'
 require 'concurrent/ivar'
-require 'concurrent/executor/executor'
 
 module Concurrent
 
+  autoload :Options, 'concurrent/options'
+
   PromiseExecutionError = Class.new(StandardError)
 
   # Promises are inspired by the JavaScript [Promises/A](http://wiki.commonjs.org/wiki/Promises/A)
@@ -441,7 +442,7 @@ module Concurrent
     def ns_initialize(value, opts)
       super
 
-      @executor = Executor.executor_from_options(opts) || Concurrent.global_io_executor
+      @executor = Options.executor_from_options(opts) || Concurrent.global_io_executor
       @args = get_arguments_from(opts)
 
       @parent = opts.fetch(:parent) { nil }

data/lib/concurrent/scheduled_task.rb

@@ -2,11 +2,12 @@ require 'concurrent/errors'
 require 'concurrent/configuration'
 require 'concurrent/ivar'
 require 'concurrent/collection/copy_on_notify_observer_set'
-require 'concurrent/executor/executor'
 require 'concurrent/utility/monotonic_time'
 
 module Concurrent
 
+  autoload :Options, 'concurrent/options'
+
   # `ScheduledTask` is a close relative of `Concurrent::Future` but with one
   # important difference: A `Future` is set to execute as soon as possible
   # whereas a `ScheduledTask` is set to execute after a specified delay. This
@@ -173,7 +174,7 @@ module Concurrent
         @delay = delay.to_f
         @task = task
         @time = nil
-        @executor = Executor.executor_from_options(opts) || Concurrent.global_io_executor
+        @executor = Options.executor_from_options(opts) || Concurrent.global_io_executor
         self.observers = Collection::CopyOnNotifyObserverSet.new
       end
     end

data/lib/concurrent/settable_struct.rb

@@ -74,8 +74,9 @@ module Concurrent
     # @raise [Concurrent::ImmutabilityError] if the given member has already been set
     def []=(member, value)
       if member.is_a? Integer
-        if member >= @values.length
-          raise IndexError.new("offset #{member} too large for struct(size:#{@values.length})")
+        length = synchronize { @values.length }
+        if member >= length
+          raise IndexError.new("offset #{member} too large for struct(size:#{length})")
         end
         synchronize do
           unless @values[member].nil?
@@ -101,10 +102,10 @@ module Concurrent
       FACTORY.define_struct(clazz_name, args, &block)
     end
 
-    FACTORY = Class.new(Synchronization::Object) do
+    FACTORY = Class.new(Synchronization::LockableObject) do
       def define_struct(name, members, &block)
         synchronize do
-          clazz = Synchronization::AbstractStruct.define_struct_class(SettableStruct, Synchronization::Object, name, members, &block)
+          clazz = Synchronization::AbstractStruct.define_struct_class(SettableStruct, Synchronization::LockableObject, name, members, &block)
           members.each_with_index do |member, index|
             clazz.send(:define_method, member) do
               synchronize { @values[index] }

data/lib/concurrent/synchronization.rb

@@ -1,11 +1,19 @@
 require 'concurrent/utility/engine'
+
 require 'concurrent/synchronization/abstract_object'
-require 'concurrent/synchronization/java_object'
-require 'concurrent/synchronization/mutex_object'
-require 'concurrent/synchronization/monitor_object'
+require 'concurrent/synchronization/mri_object'
+require 'concurrent/synchronization/jruby_object'
 require 'concurrent/synchronization/rbx_object'
 require 'concurrent/synchronization/object'
 
+require 'concurrent/synchronization/abstract_lockable_object'
+require 'concurrent/synchronization/mri_lockable_object'
+require 'concurrent/synchronization/jruby_lockable_object'
+require 'concurrent/synchronization/rbx_lockable_object'
+
+require 'concurrent/utility/native_extension_loader' # load native part first
+require 'concurrent/synchronization/lockable_object'
+
 require 'concurrent/synchronization/condition'
 require 'concurrent/synchronization/lock'
 

data/lib/concurrent/synchronization/abstract_lockable_object.rb

@@ -0,0 +1,117 @@
+module Concurrent
+  module Synchronization
+    # @!macro synchronization_object
+    # @!visibility private
+    class AbstractLockableObject < Object
+
+      protected
+
+      # @!macro [attach] synchronization_object_method_synchronize
+      #
+      #   @yield runs the block synchronized against this object,
+      #     equivalent of java's `synchronize(this) {}`
+      #   @note can by made public in descendants if required by `public :synchronize`
+      def synchronize
+        raise NotImplementedError
+      end
+
+      # @!macro [attach] synchronization_object_method_ns_initialize
+      #
+      #   initialization of the object called inside synchronize block
+      #   @note has to be called manually when required in children of this class
+      #   @example
+      #     class Child < Concurrent::Synchornization::Object
+      #       def initialize(*args, &block)
+      #         super(&nil)
+      #         synchronize { ns_initialize(*args, &block) }
+      #       end
+      #
+      #       def ns_initialize(*args, &block)
+      #         @args = args
+      #       end
+      #     end
+      # TODO (pitr 12-Sep-2015): remove
+      def ns_initialize(*args, &block)
+      end
+
+      # @!macro [attach] synchronization_object_method_ns_wait_until
+      #
+      #   Wait until condition is met or timeout passes,
+      #   protects against spurious wake-ups.
+      #   @param [Numeric, nil] timeout in seconds, `nil` means no timeout
+      #   @yield condition to be met
+      #   @yieldreturn [true, false]
+      #   @return [true, false] if condition met
+      #   @note only to be used inside synchronized block
+      #   @note to provide direct access to this method in a descendant add method
+      #     ```
+      #     def wait_until(timeout = nil, &condition)
+      #       synchronize { ns_wait_until(timeout, &condition) }
+      #     end
+      #     ```
+      def ns_wait_until(timeout = nil, &condition)
+        if timeout
+          wait_until = Concurrent.monotonic_time + timeout
+          loop do
+            now              = Concurrent.monotonic_time
+            condition_result = condition.call
+            return condition_result if now >= wait_until || condition_result
+            ns_wait wait_until - now
+          end
+        else
+          ns_wait timeout until condition.call
+          true
+        end
+      end
+
+      # @!macro [attach] synchronization_object_method_ns_wait
+      #
+      #   Wait until another thread calls #signal or #broadcast,
+      #   spurious wake-ups can happen.
+      #
+      #   @param [Numeric, nil] timeout in seconds, `nil` means no timeout
+      #   @return [self]
+      #   @note only to be used inside synchronized block
+      #   @note to provide direct access to this method in a descendant add method
+      #     ```
+      #     def wait(timeout = nil)
+      #       synchronize { ns_wait(timeout) }
+      #     end
+      #     ```
+      def ns_wait(timeout = nil)
+        raise NotImplementedError
+      end
+
+      # @!macro [attach] synchronization_object_method_ns_signal
+      #
+      #   Signal one waiting thread.
+      #   @return [self]
+      #   @note only to be used inside synchronized block
+      #   @note to provide direct access to this method in a descendant add method
+      #     ```
+      #     def signal
+      #       synchronize { ns_signal }
+      #     end
+      #     ```
+      def ns_signal
+        raise NotImplementedError
+      end
+
+      # @!macro [attach] synchronization_object_method_ns_broadcast
+      #
+      #   Broadcast to all waiting threads.
+      #   @return [self]
+      #   @note only to be used inside synchronized block
+      #   @note to provide direct access to this method in a descendant add method
+      #     ```
+      #     def broadcast
+      #       synchronize { ns_broadcast }
+      #     end
+      #     ```
+      def ns_broadcast
+        raise NotImplementedError
+      end
+
+    end
+  end
+end

data/lib/concurrent/synchronization/abstract_object.rb

@@ -5,125 +5,13 @@ module Concurrent
     # @!visibility private
     class AbstractObject
 
-      # @!macro [attach] synchronization_object_method_initialize
-      #  
-      #   @abstract for helper ivar initialization if needed,
-      #     otherwise it can be left empty. It has to call ns_initialize.
-      def initialize(*args, &block)
-        raise NotImplementedError
-      end
-
-      protected
-
-      # @!macro [attach] synchronization_object_method_synchronize
-      #  
-      #   @yield runs the block synchronized against this object,
-      #     equivalent of java's `synchronize(this) {}`
-      #   @note can by made public in descendants if required by `public :synchronize`
-      def synchronize
-        raise NotImplementedError
-      end
-
-      # @!macro [attach] synchronization_object_method_ns_initialize
-      #  
-      #   initialization of the object called inside synchronize block
-      #   @note has to be called manually when required in children of this class
-      #   @example
-      #     class Child < Concurrent::Synchornization::Object
-      #       def initialize(*args, &block)
-      #         super(&nil)
-      #         synchronize { ns_initialize(*args, &block) }
-      #       end
-      #     
-      #       def ns_initialize(*args, &block)
-      #         @args = args          
-      #       end
-      #     end
-      def ns_initialize(*args, &block)
-      end
-
-      # @!macro [attach] synchronization_object_method_ns_wait_until
-      #  
-      #   Wait until condition is met or timeout passes,
-      #   protects against spurious wake-ups.
-      #   @param [Numeric, nil] timeout in seconds, `nil` means no timeout
-      #   @yield condition to be met
-      #   @yieldreturn [true, false]
-      #   @return [true, false] if condition met
-      #   @note only to be used inside synchronized block
-      #   @note to provide direct access to this method in a descendant add method
-      #     ```
-      #     def wait_until(timeout = nil, &condition)
-      #       synchronize { ns_wait_until(timeout, &condition) }
-      #     end
-      #     ```
-      def ns_wait_until(timeout = nil, &condition)
-        if timeout
-          wait_until = Concurrent.monotonic_time + timeout
-          loop do
-            now              = Concurrent.monotonic_time
-            condition_result = condition.call
-            # 0.001 correction to avoid error when `wait_until - now` is smaller than 0.0005 and rounded to 0
-            # when passed to java #wait(long timeout)
-            return condition_result if (now + 0.001) >= wait_until || condition_result
-            ns_wait wait_until - now
-          end
-        else
-          ns_wait timeout until condition.call
-          true
-        end
-      end
-
-      # @!macro [attach] synchronization_object_method_ns_wait
-      #  
-      #   Wait until another thread calls #signal or #broadcast,
-      #   spurious wake-ups can happen.
-      #  
-      #   @param [Numeric, nil] timeout in seconds, `nil` means no timeout
-      #   @return [self]
-      #   @note only to be used inside synchronized block
-      #   @note to provide direct access to this method in a descendant add method
-      #     ```
-      #     def wait(timeout = nil)
-      #       synchronize { ns_wait(timeout) }
-      #     end
-      #     ```
-      def ns_wait(timeout = nil)
-        raise NotImplementedError
-      end
-
-      # @!macro [attach] synchronization_object_method_ns_signal
-      #    
-      #   Signal one waiting thread.
-      #   @return [self]
-      #   @note only to be used inside synchronized block
-      #   @note to provide direct access to this method in a descendant add method
-      #     ```
-      #     def signal
-      #       synchronize { ns_signal }
-      #     end
-      #     ```
-      def ns_signal
-        raise NotImplementedError
-      end
-
-      # @!macro [attach] synchronization_object_method_ns_broadcast
-      #  
-      #   Broadcast to all waiting threads.
-      #   @return [self]
-      #   @note only to be used inside synchronized block
-      #   @note to provide direct access to this method in a descendant add method
-      #     ```
-      #     def broadcast
-      #       synchronize { ns_broadcast }
-      #     end
-      #     ```
-      def ns_broadcast
+      # @abstract has to be implemented based on Ruby runtime
+      def initialize
         raise NotImplementedError
       end
 
       # @!macro [attach] synchronization_object_method_ensure_ivar_visibility
-      #  
+      #
       #   Allows to construct immutable objects where all fields are visible after initialization, not requiring
       #   further synchronization on access.
       #   @example
@@ -135,28 +23,27 @@ module Concurrent
       #         # now it can be shared as Java's final field
       #       end
       #     end
+      # @!visibility private
       def ensure_ivar_visibility!
+        # We have to prevent ivar writes to reordered with storing of the final instance reference
+        # Therefore wee need a fullFence to prevent reordering in both directions.
+        full_memory_barrier
+      end
+
+      protected
+
+      # @!visibility private
+      # @abstract
+      def full_memory_barrier
         raise NotImplementedError
       end
 
       # @!macro [attach] synchronization_object_method_self_attr_volatile
-      #    
+      #
       #   creates methods for reading and writing to a instance variable with volatile (Java semantic) instance variable
       #   return [Array<Symbol>] names of defined method names
       def self.attr_volatile(*names)
-        names.each do |name|
-          ivar = :"@volatile_#{name}"
-          class_eval <<-RUBY, __FILE__, __LINE__ + 1
-            def #{name}
-              #{ivar}
-            end
-
-            def #{name}=(value)
-              #{ivar} = value
-            end
-          RUBY
-        end
-        names.map { |n| [n, :"#{n}="] }.flatten
+        raise NotImplementedError
       end
     end
   end