concurrent-ruby 0.6.0.pre.2 → 0.6.0

data/lib/concurrent/delay.rb

@@ -1,4 +1,5 @@
 require 'thread'
+require 'concurrent/obligation'
 
 module Concurrent
 
@@ -48,7 +49,7 @@ module Concurrent
 
       init_obligation
       @state = :pending
-      @task = block
+      @task  = block
       set_deref_options(opts)
     end
 
@@ -73,24 +74,39 @@ module Concurrent
     def value
       mutex.lock
       execute_task_once
-      result = apply_deref_options(@value)
+      apply_deref_options(@value)
+    ensure
       mutex.unlock
+    end
 
-      result
+    # reconfigures the block returning the value if still #incomplete?
+    # @yield the delayed operation to perform
+    # @return [true, false] if success
+    def reconfigure(&block)
+      mutex.lock
+      raise ArgumentError.new('no block given') unless block_given?
+      if @state == :pending
+        @task = block
+        true
+      else
+        false
+      end
+    ensure
+      mutex.unlock
     end
 
     private
 
-      def execute_task_once
-        if @state == :pending
-          begin
-            @value = @task.call
-            @state = :fulfilled
-          rescue => ex
-            @reason = ex
-            @state = :rejected
-          end
+    def execute_task_once
+      if @state == :pending
+        begin
+          @value = @task.call
+          @state = :fulfilled
+        rescue => ex
+          @reason = ex
+          @state  = :rejected
         end
       end
+    end
   end
 end

data/lib/concurrent/dereferenceable.rb

@@ -27,9 +27,9 @@ module Concurrent
     # @return [Object] the current value of the object
     def value
       mutex.lock
-      result = apply_deref_options(@value)
+      apply_deref_options(@value)
+    ensure
       mutex.unlock
-      result
     end
 
     alias_method :deref, :value
@@ -41,9 +41,9 @@ module Concurrent
     # @param [Object] val the new value
     def value=(val)
       mutex.lock
-      result = @value = val
+      @value = val
+    ensure
       mutex.unlock
-      result
     end
 
     # A mutex lock used for synchronizing thread-safe operations. Methods defined
@@ -83,15 +83,15 @@ module Concurrent
       @freeze_on_deref = opts[:freeze_on_deref] || opts[:freeze]
       @copy_on_deref = opts[:copy_on_deref] || opts[:copy]
       @do_nothing_on_deref = !(@dup_on_deref || @freeze_on_deref || @copy_on_deref)
-      mutex.unlock
       nil
+    ensure
+      mutex.unlock
     end
 
     # @!visibility private
     def apply_deref_options(value) # :nodoc:
       return nil if value.nil?
       return value if @do_nothing_on_deref
-      value = value
       value = @copy_on_deref.call(value) if @copy_on_deref
       value = value.dup if @dup_on_deref
       value = value.freeze if @freeze_on_deref

data/lib/concurrent/errors.rb

@@ -0,0 +1,30 @@
+module Concurrent
+
+  # Raised when errors occur during configuration.
+  ConfigurationError = Class.new(StandardError)
+
+  # Raised when a lifecycle method (such as `stop`) is called in an improper
+  # sequence or when the object is in an inappropriate state.
+  LifecycleError = Class.new(StandardError)
+
+  # Raised when an object's methods are called when it has not been
+  # properly initialized.
+  InitializationError = Class.new(StandardError)
+
+  # Raised when an object with a start/stop lifecycle has been started an
+  # excessive number of times. Often used in conjunction with a restart
+  # policy or strategy.
+  MaxRestartFrequencyError = Class.new(StandardError)
+
+  # Raised when an attempt is made to modify an immutable object
+  # (such as an `IVar`) after its final state has been set.
+  MultipleAssignmentError = Class.new(StandardError)
+
+  # Raised by an `Executor` when it is unable to process a given task,
+  # possibly because of a reject policy or other internal error.
+  RejectedExecutionError = Class.new(StandardError)
+
+  # Raised when an operation times out.
+  TimeoutError = Class.new(StandardError)
+
+end

data/lib/concurrent/executor/executor.rb

@@ -1,12 +1,18 @@
+require 'concurrent/errors'
+require 'concurrent/logging'
 require 'concurrent/atomic/event'
 
 module Concurrent
 
-  # An exception class raised when the maximum queue size is reached and the
-  # `overflow_policy` is set to `:abort`.
-  RejectedExecutionError = Class.new(StandardError)
-
   module Executor
+    def can_overflow?
+      false
+    end
+  end
+
+  module RubyExecutor
+    include Executor
+    include Logging
 
     # Submit a task to the executor for asynchronous processing.
     #
@@ -123,6 +129,7 @@ module Concurrent
   if RUBY_PLATFORM == 'java'
 
     module JavaExecutor
+      include Executor
 
       # Submit a task to the executor for asynchronous processing.
       #

data/lib/concurrent/executor/immediate_executor.rb

@@ -1,5 +1,6 @@
 module Concurrent
   class ImmediateExecutor
+    include Executor
 
     def post(*args, &task)
       raise ArgumentError.new('no block given') unless block_given?

data/lib/concurrent/executor/java_thread_pool_executor.rb

@@ -89,6 +89,10 @@ if RUBY_PLATFORM == 'java'
         set_shutdown_hook
       end
 
+      def can_overflow?
+        @max_queue != 0
+      end
+
       # The minimum number of threads that may be retained in the pool.
       #
       # @return [Integer] the min_length

data/lib/concurrent/executor/one_by_one.rb

@@ -1,6 +1,6 @@
 module Concurrent
 
-  # Ensures that jobs are passed to the underlying executor one by one,
+  # Ensures that jobs are passed to the given executors one by one,
   # never running at the same time.
   class OneByOne
 
@@ -30,16 +30,24 @@ module Concurrent
     # @raise [ArgumentError] if no task is given
     def post(executor, *args, &task)
       return nil if task.nil?
+      # FIXME Agent#send-off will blow up here
+      # if executor.can_overflow?
+      #   raise ArgumentError, 'OneByOne cannot be used in conjunction with executor which may overflow'
+      # end
+
       job = Job.new executor, args, task
 
-      @mutex.lock
-      post = if @being_executed
-               @stash << job
-               false
-             else
-               @being_executed = true
-             end
-      @mutex.unlock
+      begin
+        @mutex.lock
+        post = if @being_executed
+                 @stash << job
+                 false
+               else
+                 @being_executed = true
+               end
+      ensure
+        @mutex.unlock
+      end
 
       call_job job if post
       true
@@ -55,9 +63,13 @@ module Concurrent
     def work(job)
       job.call
     ensure
-      @mutex.lock
-      job = @stash.shift || (@being_executed = false)
-      @mutex.unlock
+      begin
+        @mutex.lock
+        job = @stash.shift || (@being_executed = false)
+      ensure
+        @mutex.unlock
+      end
+
       call_job job if job
     end
 

data/lib/concurrent/executor/per_thread_executor.rb

@@ -1,6 +1,7 @@
 module Concurrent
 
   class PerThreadExecutor
+    include Executor
 
     def self.post(*args)
       raise ArgumentError.new('no block given') unless block_given?

data/lib/concurrent/executor/ruby_single_thread_executor.rb

@@ -4,7 +4,7 @@ module Concurrent
 
   # @!macro single_thread_executor
   class RubySingleThreadExecutor
-    include Executor
+    include RubyExecutor
 
     # Create a new thread pool.
     #
@@ -64,6 +64,7 @@ module Concurrent
           task.last.call(*task.first)
         rescue => ex
           # let it fail
+          log DEBUG, ex
         end
       end
       stopped_event.set

data/lib/concurrent/executor/ruby_thread_pool_executor.rb

@@ -8,7 +8,7 @@ module Concurrent
 
   # @!macro thread_pool_executor
   class RubyThreadPoolExecutor
-    include Executor
+    include RubyExecutor
 
     # Default maximum number of threads that will be created in the pool.
     DEFAULT_MAX_POOL_SIZE = 2**15 # 32768
@@ -99,6 +99,10 @@ module Concurrent
       @last_gc_time = Time.now.to_f - [1.0, (@gc_interval * 2.0)].max
     end
 
+    def can_overflow?
+      @max_queue != 0
+    end
+
     # The number of threads currently in the pool.
     #
     # @return [Integer] the length
@@ -233,8 +237,9 @@ module Concurrent
       when :caller_runs
         begin
           yield(*args)
-        rescue
+        rescue => ex
           # let it fail
+          log DEBUG, ex
         end
         true
       end

data/lib/concurrent/executor/ruby_thread_pool_worker.rb

@@ -1,9 +1,11 @@
 require 'thread'
+require 'concurrent/logging'
 
 module Concurrent
 
   # @!visibility private
   class RubyThreadPoolWorker
+    include Logging
 
     # @!visibility private
     def initialize(queue, parent)
@@ -59,6 +61,7 @@ module Concurrent
           task.last.call(*task.first)
         rescue => ex
           # let it fail
+          log DEBUG, ex
         ensure
           @last_activity = Time.now.to_f
           @parent.on_end_task

data/lib/concurrent/executor/timer_set.rb

@@ -11,7 +11,7 @@ module Concurrent
   # 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 Executor
+    include RubyExecutor
 
     # Create a new set of timed tasks.
     #

data/lib/concurrent/future.rb

@@ -1,6 +1,5 @@
 require 'thread'
 
-require 'concurrent/obligation'
 require 'concurrent/options_parser'
 require 'concurrent/executor/safe_task_executor'
 
@@ -40,7 +39,6 @@ module Concurrent
   # @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
-    include Obligation
 
     # Create a new `Future` in the `:unscheduled` state.
     #

data/lib/concurrent/ivar.rb

@@ -1,19 +1,35 @@
 require 'thread'
 
+require 'concurrent/errors'
 require 'concurrent/obligation'
 require 'concurrent/observable'
 
 module Concurrent
 
-  MultipleAssignmentError = Class.new(StandardError)
-
+  # An `IVar` is a single-element container that is normally created empty, and
+  # can only be set once. The I in `IVar` stands for immutable. Reading an `IVar`
+  # normally blocks until it is set. It is safe to set and read an `IVar` from
+  # different threads.
+  #
+  # If you want to have some parallel task set the value in an `IVar`, you want
+  # a `Future`. If you want to create a graph of parallel tasks all executed when
+  # the values they depend on are ready you want `dataflow`. `IVar` is generally
+  # a low-level primitive.
+  #
+  # @example Create, set and get an `IVar`
+  #   ivar = Concurrent::IVar.new
+  #   ivar.set 14
+  #   ivar.get #=> 14
+  #   ivar.set 2 # would now be an error
   class IVar
+
     include Obligation
-    include Concurrent::Observable
+    include Observable
 
-    NO_VALUE = Object.new
+    # @!visibility private
+    NO_VALUE = Object.new # :nodoc:
 
-    # Create a new `Ivar` in the `:pending` state with the (optional) initial value.
+    # Create a new `IVar` in the `:pending` state with the (optional) initial value.
     #
     # @param [Object] value the initial value
     # @param [Hash] opts the options to create a message with
@@ -63,15 +79,24 @@ module Concurrent
       observer
     end
 
+    # Set the `IVar` to a value and wake or notify all threads waiting on it.
+    #
+    # @param [Object] value the value to store in the `IVar`
+    # @raise [Concurrent::MultipleAssignmentError] if the `IVar` has already been set or otherwise completed
     def set(value)
       complete(true, value, nil)
     end
 
+    # Set the `IVar` to failed due to some error and wake or notify all threads waiting on it.
+    #
+    # @param [Object] reason for the failure
+    # @raise [Concurrent::MultipleAssignmentError] if the `IVar` has already been set or otherwise completed
     def fail(reason = StandardError.new)
       complete(false, nil, reason)
     end
 
-    def complete(success, value, reason)
+    # @!visibility private
+    def complete(success, value, reason) # :nodoc:
       mutex.synchronize do
         raise MultipleAssignmentError.new('multiple assignment') if [:fulfilled, :rejected].include? @state
         set_state(success, value, reason)

data/lib/concurrent/logging.rb

@@ -0,0 +1,17 @@
+require 'logger'
+
+module Concurrent
+  # Include where logging is needed
+  module Logging
+    include Logger::Severity
+
+    # Logs through {Configuration#logger}, it can be overridden by setting @logger
+    # @param [Integer] level one of Logger::Severity constants
+    # @param [String] progname e.g. a path of an Actor
+    # @param [String, nil] message when nil block is used to generate the message
+    # @yields_return [String] a message
+    def log(level, progname, message = nil, &block)
+      (@logger || Concurrent.configuration.logger).call level, progname, message, &block
+    end
+  end
+end

data/lib/concurrent/mvar.rb

@@ -4,13 +4,39 @@ require 'concurrent/atomic/event'
 
 module Concurrent
 
+  # An `MVar` is a single-element container that blocks on `get` if it is empty,
+  # and blocks on `put` if it is full. It is safe to use an `MVar` from
+  # multiple threads. `MVar` can be seen as a single-element blocking queue, or
+  # a rendezvous variable.
+  #
+  # An `MVar` is typically used to transfer objects between threads, where the
+  # sending thread will block if the previous message hasn't been taken yet by the
+  # receiving thread. It can also be used to control access to some global shared
+  # state, where threads `take` the value, perform some operation, and then
+  # `put` it back.
   class MVar
 
     include Dereferenceable
 
+    # Unique value that represents that an `MVar` was empty
     EMPTY = Object.new
+
+    # Unique value that represents that an `MVar` timed out before it was able
+    # to produce a value.
     TIMEOUT = Object.new
 
+    # Create a new `MVar`, either empty or with an initial value.
+    #
+    # @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)
+    # @option opts [String] :dup_on_deref (false) call `#dup` before returning the data
+    # @option opts [String] :freeze_on_deref (false) call `#freeze` before returning the data
+    # @option opts [String] :copy_on_deref (nil) call the given `Proc` passing the internal value and
+    #   returning the value returned from the proc
     def initialize(value = EMPTY, opts = {})
       @value = value
       @mutex = Mutex.new
@@ -19,6 +45,10 @@ module Concurrent
       set_deref_options(opts)
     end
 
+    # Remove the value from an `MVar`, leaving it empty, and blocking if there
+    # isn't a value. A timeout can be set to limit the time spent blocked, in
+    # which case it returns `TIMEOUT` if the time is exceeded.
+    # @return [Object] the value that was taken, or `TIMEOUT`
     def take(timeout = nil)
       @mutex.synchronize do
         wait_for_full(timeout)
@@ -35,6 +65,10 @@ module Concurrent
       end
     end
 
+    # Put a value into an `MVar`, blocking if there is already a value until
+    # it is empty. A timeout can be set to limit the time spent blocked, in
+    # which case it returns `TIMEOUT` if the time is exceeded.
+    # @return [Object] the value that was put, or `TIMEOUT`
     def put(value, timeout = nil)
       @mutex.synchronize do
         wait_for_empty(timeout)
@@ -50,6 +84,11 @@ module Concurrent
       end
     end
 
+    # Atomically `take`, yield the value to a block for transformation, and then
+    # `put` the transformed value. Returns the transformed value. A timeout can
+    # be set to limit the time spent blocked, in which case it returns `TIMEOUT`
+    # if the time is exceeded.
+    # @return [Object] the transformed value, or `TIMEOUT`
     def modify(timeout = nil)
       raise ArgumentError.new('no block given') unless block_given?
 
@@ -68,6 +107,7 @@ module Concurrent
       end
     end
 
+    # Non-blocking version of `take`, that returns `EMPTY` instead of blocking.
     def try_take!
       @mutex.synchronize do
         if unlocked_full?
@@ -81,6 +121,7 @@ module Concurrent
       end
     end
 
+    # Non-blocking version of `put`, that returns whether or not it was successful.
     def try_put!(value)
       @mutex.synchronize do
         if unlocked_empty?
@@ -93,6 +134,7 @@ module Concurrent
       end
     end
 
+    # Non-blocking version of `put` that will overwrite an existing value.
     def set!(value)
       @mutex.synchronize do
         old_value = @value
@@ -102,6 +144,7 @@ module Concurrent
       end
     end
 
+    # Non-blocking version of `modify` that will yield with `EMPTY` if there is no value yet.
     def modify!
       raise ArgumentError.new('no block given') unless block_given?
 
@@ -117,10 +160,12 @@ module Concurrent
       end
     end
 
+    # Returns if the `MVar` is currently empty.
     def empty?
       @mutex.synchronize { @value == EMPTY }
     end
 
+    # Returns if the `MVar` currently contains a value.
     def full?
       not empty?
     end