concurrent-ruby 1.0.0.pre1 → 1.0.0.pre2

data/lib/concurrent/collection/map/atomic_reference_map_backend.rb

@@ -1,4 +1,9 @@
 require 'concurrent/thread_safe/util'
+require 'concurrent/thread_safe/util/adder'
+require 'concurrent/thread_safe/util/cheap_lockable'
+require 'concurrent/thread_safe/util/power_of_two_tuple'
+require 'concurrent/thread_safe/util/volatile'
+require 'concurrent/thread_safe/util/xor_shift_random'
 
 module Concurrent
 

data/lib/concurrent/concern/observable.rb

@@ -21,8 +21,8 @@ module Concurrent
     #
     # In a multi threaded environment things are more complex. The `subject` must
     # synchronize the access to its data structure and to do so currently we're
-    # using two specialized ObserverSet: CopyOnWriteObserverSet and
-    # CopyOnNotifyObserverSet.
+    # using two specialized ObserverSet: {Concurrent::Concern::CopyOnWriteObserverSet}
+    # and {Concurrent::Concern::CopyOnNotifyObserverSet}.
     #
     # When implementing and `observer` there's a very important rule to remember:
     # **there are no guarantees about the thread that will execute the callback**
@@ -49,30 +49,55 @@ module Concurrent
     # or an AtomicFixum)
     module Observable
 
-      # @return [Object] the added observer
-      def add_observer(*args, &block)
-        observers.add_observer(*args, &block)
+      # @!macro [attach] observable_add_observer
+      #
+      #   Adds an observer to this set. If a block is passed, the observer will be
+      #   created by this method and no other params should be passed.
+      #
+      #   @param [Object] observer the observer to add
+      #   @param [Symbol] func the function to call on the observer during notification.
+      #     Default is :update
+      #   @return [Object] the added observer
+      def add_observer(observer = nil, func = :update, &block)
+        observers.add_observer(observer, func, &block)
       end
 
-      # as #add_observer but it can be used for chaining
+      # As `#add_observer` but can be used for chaining.
+      #
+      # @param [Object] observer the observer to add
+      # @param [Symbol] func the function to call on the observer during notification.
       # @return [Observable] self
-      def with_observer(*args, &block)
-        add_observer(*args, &block)
+      def with_observer(observer = nil, func = :update, &block)
+        add_observer(observer, func, &block)
         self
       end
 
-      # @return [Object] the deleted observer
-      def delete_observer(*args)
-        observers.delete_observer(*args)
+      # @!macro [attach] observable_delete_observer
+      # 
+      #   Remove `observer` as an observer on this object so that it will no
+      #   longer receive notifications.
+      #
+      #   @param [Object] observer the observer to remove
+      #   @return [Object] the deleted observer
+      def delete_observer(observer)
+        observers.delete_observer(observer)
       end
 
-      # @return [Observable] self
+      # @!macro [attach] observable_delete_observers
+      # 
+      #   Remove all observers associated with this object.
+      #   
+      #   @return [Observable] self
       def delete_observers
         observers.delete_observers
         self
       end
 
-      # @return [Integer] the observers count
+      # @!macro [attach] observable_count_observers
+      #
+      #   Return the number of observers associated with this object.
+      #
+      #   @return [Integer] the observers count
       def count_observers
         observers.count_observers
       end

data/lib/concurrent/configuration.rb

@@ -3,16 +3,17 @@ require 'concurrent/delay'
 require 'concurrent/errors'
 require 'concurrent/atomic/atomic_reference'
 require 'concurrent/concern/logging'
-require 'concurrent/executor/timer_set'
 require 'concurrent/executor/immediate_executor'
-require 'concurrent/executor/fixed_thread_pool'
-require 'concurrent/executor/thread_pool_executor'
 require 'concurrent/utility/at_exit'
 require 'concurrent/utility/processor_counter'
 
 module Concurrent
   extend Concern::Logging
 
+  autoload :Options,            'concurrent/options'
+  autoload :TimerSet,           'concurrent/executor/timer_set'
+  autoload :ThreadPoolExecutor, 'concurrent/executor/thread_pool_executor'
+
   # @return [Logger] Logger with provided level and output.
   def self.create_stdlib_logger(level = Logger::FATAL, output = $stderr)
     logger           = Logger.new(output)
@@ -125,7 +126,7 @@ module Concurrent
   #   - :immediate - {Concurrent.global_immediate_executor}
   # @return [Executor]
   def self.executor(executor_identifier)
-    Executor.executor(executor_identifier)
+    Options.executor(executor_identifier)
   end
 
   def self.new_fast_executor(opts = {})

data/lib/concurrent/delay.rb

@@ -1,12 +1,12 @@
 require 'thread'
-require 'concurrent/configuration'
 require 'concurrent/concern/obligation'
-require 'concurrent/executor/executor'
 require 'concurrent/executor/immediate_executor'
 require 'concurrent/synchronization'
 
 module Concurrent
 
+  autoload :Options, 'concurrent/options'
+
   # Lazy evaluation of a block yielding an immutable result. Useful for
   # expensive operations that may never be needed. It may be non-blocking,
   # supports the `Concern::Obligation` interface, and accepts the injection of
@@ -40,7 +40,7 @@ module Concurrent
   #     execute on the given executor, allowing the call to timeout.
   #
   # @see Concurrent::Concern::Dereferenceable
-  class Delay < Synchronization::Object
+  class Delay < Synchronization::LockableObject
     include Concern::Obligation
 
     # NOTE: Because the global thread pools are lazy-loaded with these objects
@@ -74,7 +74,7 @@ module Concurrent
     #
     # @!macro delay_note_regarding_blocking
     def value(timeout = nil)
-      if @task_executor
+      if @executor # TODO (pitr 12-Sep-2015): broken unsafe read?
         super
       else
         # this function has been optimized for performance and
@@ -108,7 +108,7 @@ module Concurrent
     #
     # @!macro delay_note_regarding_blocking
     def value!(timeout = nil)
-      if @task_executor
+      if @executor
         super
       else
         result = value
@@ -127,7 +127,7 @@ module Concurrent
     #
     # @!macro delay_note_regarding_blocking
     def wait(timeout = nil)
-      if @task_executor
+      if @executor
         execute_task_once
         super(timeout)
       else
@@ -157,7 +157,7 @@ module Concurrent
     def ns_initialize(opts, &block)
       init_obligation(self)
       set_deref_options(opts)
-      @task_executor = Executor.executor_from_options(opts)
+      @executor = opts[:executor]
 
       @task      = block
       @state     = :pending
@@ -177,7 +177,8 @@ module Concurrent
       end
 
       if execute
-        @task_executor.post do
+        executor = Options.executor_from_options(executor: @executor)
+        executor.post do
           begin
             result  = task.call
             success = true

data/lib/concurrent/exchanger.rb

@@ -13,6 +13,8 @@ module Concurrent
   #   pairs. Each thread presents some object on entry to the exchange method,
   #   matches with a partner thread, and receives its partner's object on return.
   #
+  #   @!macro thread_safe_variable_comparison
+  #
   #   This implementation is very simple, using only a single slot for each
   #   exchanger (unlike more advanced implementations which use an "arena").
   #   This approach will work perfectly fine when there are only a few threads

data/lib/concurrent/executor/abstract_executor_service.rb

@@ -1,13 +1,13 @@
 require 'concurrent/errors'
 require 'concurrent/executor/executor_service'
-require 'concurrent/synchronization/object'
+require 'concurrent/synchronization'
 require 'concurrent/utility/at_exit'
 
 module Concurrent
 
   # @!macro abstract_executor_service_public_api
   # @!visibility private
-  class AbstractExecutorService < Synchronization::Object
+  class AbstractExecutorService < Synchronization::LockableObject
     include ExecutorService
 
     # The set of possible fallback policies that may be set at thread pool creation.

data/lib/concurrent/executor/java_single_thread_executor.rb

@@ -6,7 +6,6 @@ if Concurrent.on_jruby?
   module Concurrent
 
     # @!macro single_thread_executor
-    # @!macro thread_pool_options
     # @!macro abstract_executor_service_public_api
     # @!visibility private
     class JavaSingleThreadExecutor < JavaExecutorService

data/lib/concurrent/executor/ruby_executor_service.rb

@@ -6,12 +6,12 @@ module Concurrent
   # @!macro abstract_executor_service_public_api
   # @!visibility private
   class RubyExecutorService < AbstractExecutorService
+    safe_initialization!
 
     def initialize(*args, &block)
       super
-      @stop_event    = Event.new
-      @stopped_event = Event.new
-      ensure_ivar_visibility!
+      @StopEvent    = Event.new
+      @StoppedEvent = Event.new
     end
 
     def post(*args, &task)
@@ -51,7 +51,13 @@ module Concurrent
 
     private
 
-    attr_reader :stop_event, :stopped_event
+    def stop_event
+      @StopEvent
+    end
+
+    def stopped_event
+      @StoppedEvent
+    end
 
     def ns_shutdown_execution
       stopped_event.set

data/lib/concurrent/executor/ruby_single_thread_executor.rb

@@ -1,80 +1,22 @@
-require 'thread'
-require 'concurrent/executor/ruby_executor_service'
-require 'concurrent/executor/serial_executor_service'
+require 'concurrent/executor/ruby_thread_pool_executor'
 
 module Concurrent
 
   # @!macro single_thread_executor
-  # @!macro thread_pool_options
   # @!macro abstract_executor_service_public_api
   # @!visibility private
-  class RubySingleThreadExecutor < RubyExecutorService
-    include SerialExecutorService
+  class RubySingleThreadExecutor < RubyThreadPoolExecutor
 
     # @!macro single_thread_executor_method_initialize
     def initialize(opts = {})
-      super
-    end
-
-    private
-
-    def ns_initialize(opts)
-      @queue = Queue.new
-      @thread = nil
-      @fallback_policy = opts.fetch(:fallback_policy, :discard)
-      raise ArgumentError.new("#{@fallback_policy} is not a valid fallback policy") unless FALLBACK_POLICIES.include?(@fallback_policy)
-      self.auto_terminate = opts.fetch(:auto_terminate, true)
-    end
-
-    # @!visibility private
-    def ns_execute(*args, &task)
-      supervise
-      @queue << [args, task]
-    end
-
-    # @!visibility private
-    def ns_shutdown_execution
-      @queue << :stop
-      stopped_event.set unless alive?
-    end
-
-    # @!visibility private
-    def ns_kill_execution
-      @queue.clear
-      @thread.kill if alive?
-    end
-
-    # @!visibility private
-    def alive?
-      @thread && @thread.alive?
-    end
-
-    # @!visibility private
-    def supervise
-      @thread = new_worker_thread unless alive?
-    end
-
-    # @!visibility private
-    def new_worker_thread
-      Thread.new do
-        Thread.current.abort_on_exception = false
-        work
-      end
-    end
-
-    # @!visibility private
-    def work
-      loop do
-        task = @queue.pop
-        break if task == :stop
-        begin
-          task.last.call(*task.first)
-        rescue => ex
-          # let it fail
-          log DEBUG, ex
-        end
-      end
-      stopped_event.set
+      super(
+        min_threads: 1,
+        max_threads: 1,
+        max_queue: 0,
+        idletime: DEFAULT_THREAD_IDLETIMEOUT,
+        fallback_policy: opts.fetch(:fallback_policy, :discard),
+        auto_terminate: opts.fetch(:auto_terminate, true)
+      )
     end
   end
 end

data/lib/concurrent/executor/safe_task_executor.rb

@@ -1,4 +1,4 @@
-require 'concurrent/synchronization/object'
+require 'concurrent/synchronization'
 
 module Concurrent
 
@@ -6,26 +6,25 @@ 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 < Synchronization::Object
+  class SafeTaskExecutor < Synchronization::LockableObject
 
     def initialize(task, opts = {})
-      super()
-      @task = task
+      @task            = task
       @exception_class = opts.fetch(:rescue_exception, false) ? Exception : StandardError
-      ensure_ivar_visibility!
+      super() # ensures visibility
     end
 
     # @return [Array]
     def execute(*args)
       synchronize do
         success = false
-        value = reason = nil
+        value   = reason = nil
 
         begin
-          value = @task.call(*args)
+          value   = @task.call(*args)
           success = true
         rescue @exception_class => ex
-          reason = ex
+          reason  = ex
           success = false
         end
 

data/lib/concurrent/executor/serialized_execution.rb

@@ -1,11 +1,11 @@
 require 'concurrent/errors'
 require 'concurrent/concern/logging'
-require 'concurrent/synchronization/object'
+require 'concurrent/synchronization'
 
 module Concurrent
 
   # Ensures passed jobs in a serialized order never running at the same time.
-  class SerializedExecution < Synchronization::Object
+  class SerializedExecution < Synchronization::LockableObject
     include Concern::Logging
 
     def initialize()
@@ -39,8 +39,8 @@ module Concurrent
     # As {#post} but allows to submit multiple tasks at once, it's guaranteed that they will not
     # be interleaved by other tasks.
     #
-    # @param [Array<Array(Executor, Array<Object>, Proc)>] posts array of triplets where
-    #   first is a {Executor}, second is array of args for task, third is a task (Proc)
+    # @param [Array<Array(ExecutorService, Array<Object>, Proc)>] posts array of triplets where
+    #   first is a {ExecutorService}, second is array of args for task, third is a task (Proc)
     def posts(posts)
       # if can_overflow?
       #   raise ArgumentError, 'SerializedExecution does not support thread-pools which can overflow'

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