concurrent-ruby 0.6.0.pre.1 → 0.6.0.pre.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8e4a4e756232abaffd4ca55c37e049af25f9884a
-  data.tar.gz: 9345ebbf4f1a05e1c5b0eccd8df0d111407c293e
+  metadata.gz: 873e9e671b06398c80e8c918e5e2ba7c0d75564e
+  data.tar.gz: 69963957bf5e06a7a5b7ca21a678039496874c35
 SHA512:
-  metadata.gz: 1e5b34f7f631e3cb76248674f8cae5b1bee56c8485c71f32cff53d2625fb5475d84e7ff0b1f07272efbfe860652f391ea5f1078652e0c47edc2117a5099152e1
-  data.tar.gz: 5c736c6a669fd952268275f9b1e802f32eac4dc78386df90b871f1bb6dc66985b9b5e7e2046ce5bf81235608c1bc3340a1dcbd49573fb65d8cacf8b6b53f3d06
+  metadata.gz: 92bb87ece26412064c4d9697b1d92ce1cc4963d74b6f9c32b32db091d216ff8655bbd1961322db8618666a571f4f9559cf7823aa9db1fa33687b2c45db1bb57a
+  data.tar.gz: 0d2645e119b50b88748b6131bcc984e127399bb9f5988fdfaa095fe915149ad03e60ab530523736006d3eb71a1b86821b6a889c032e9bd3c5d6a04a821d8ca2d

data/README.md

@@ -33,6 +33,20 @@ The design goals of this gem are:
 </tr>
 </table>
 
+### Install
+
+```shell
+gem install concurrent-ruby
+```
+or add the following line to Gemfile:
+
+```ruby
+gem 'concurrent-ruby'
+```
+and run `bundle install` from your shell.
+
+*NOTE: There is an old gem from 2007 called "concurrent" that does not appear to be under active development. That isn't us. Please do not run* `gem install concurrent`*. It is not the droid you are looking for.*
+
 ## Features & Documentation
 
 Please see the [Concurrent Ruby Wiki](https://github.com/jdantonio/concurrent-ruby/wiki)
@@ -128,6 +142,8 @@ ibm.value #=> 187.57
 * [Michele Della Torre](https://github.com/mighe)
 * [Chris Seaton](https://github.com/chrisseaton)
 * [Lucas Allan](https://github.com/lucasallan)
+* [Petr Chalupa](https://github.com/pitr-ch)
+* [Ravil Bayramgalin](https://github.com/brainopia)
 * [Giuseppe Capizzi](https://github.com/gcapizzi)
 * [Brian Shirai](https://github.com/brixen)
 * [Chip Miller](https://github.com/chip-miller)

data/lib/concurrent.rb

@@ -1,52 +1,32 @@
 require 'concurrent/version'
 require 'concurrent/configuration'
 
-require 'concurrent/atomic'
-require 'concurrent/count_down_latch'
-require 'concurrent/condition'
-require 'concurrent/copy_on_notify_observer_set'
-require 'concurrent/copy_on_write_observer_set'
-require 'concurrent/safe_task_executor'
-require 'concurrent/ivar'
+require 'concurrent/atomics'
+require 'concurrent/actors'
+require 'concurrent/channels'
+require 'concurrent/collections'
+require 'concurrent/executors'
+require 'concurrent/utilities'
 
-require 'concurrent/actor'
 require 'concurrent/agent'
 require 'concurrent/async'
 require 'concurrent/dataflow'
 require 'concurrent/delay'
 require 'concurrent/dereferenceable'
-require 'concurrent/event'
 require 'concurrent/exchanger'
 require 'concurrent/future'
+require 'concurrent/ivar'
 require 'concurrent/mvar'
 require 'concurrent/obligation'
-require 'concurrent/postable'
-require 'concurrent/processor_count'
+require 'concurrent/observable'
+require 'concurrent/options_parser'
 require 'concurrent/promise'
 require 'concurrent/runnable'
 require 'concurrent/scheduled_task'
 require 'concurrent/stoppable'
 require 'concurrent/supervisor'
-require 'concurrent/thread_local_var'
 require 'concurrent/timer_task'
 require 'concurrent/tvar'
-require 'concurrent/utilities'
-
-require 'concurrent/channel/probe'
-require 'concurrent/channel/channel'
-require 'concurrent/channel/unbuffered_channel'
-require 'concurrent/channel/buffered_channel'
-require 'concurrent/channel/ring_buffer'
-require 'concurrent/channel/blocking_ring_buffer'
-
-require 'concurrent/actor_context'
-require 'concurrent/simple_actor_ref'
-
-require 'concurrent/cached_thread_pool'
-require 'concurrent/fixed_thread_pool'
-require 'concurrent/immediate_executor'
-require 'concurrent/per_thread_executor'
-require 'concurrent/thread_pool_executor'
 
 # Modern concurrency tools for Ruby. Inspired by Erlang, Clojure, Scala, Haskell,
 # F#, C#, Java, and classic concurrency patterns.

data/lib/concurrent/{actor.rb → actor/actor.rb}

@@ -1,9 +1,9 @@
 require 'thread'
 require 'observer'
 
-require 'concurrent/event'
+require 'concurrent/actor/postable'
+require 'concurrent/atomic/event'
 require 'concurrent/obligation'
-require 'concurrent/postable'
 require 'concurrent/runnable'
 
 module Concurrent
@@ -123,7 +123,7 @@ module Concurrent
   #
   # @see http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html
   class Actor
-    include Observable
+    include ::Observable
     include Postable
     include Runnable
 

data/lib/concurrent/actor/actor_context.rb

@@ -0,0 +1,77 @@
+require 'concurrent/actor/simple_actor_ref'
+
+module Concurrent
+
+  # Actor-based concurrency is all the rage in some circles. Originally described in
+  # 1973, the actor model is a paradigm for creating asynchronous, concurrent objects
+  # that is becoming increasingly popular. Much has changed since actors were first
+  # written about four decades ago, which has led to a serious fragmentation within
+  # the actor community. There is *no* universally accepted, strict definition of
+  # "actor" and actor implementations differ widely between languages and libraries.
+  # 
+  # A good definition of "actor" is:
+  # 
+  #   An independent, concurrent, single-purpose, computational entity that communicates exclusively via message passing.
+  #
+  # The actor framework in this library is heavily influenced by the Akka toolkit,
+  # with additional inspiration from Erlang and Scala. Unlike many of the abstractions
+  # in this library, `ActorContext` takes an *object-oriented* approach to asynchronous
+  # concurrency, rather than a *functional programming* approach.
+  #
+  # Creating an actor class is achieved by including the `ActorContext` module
+  # within a standard Ruby class. One `ActorContext` is mixed in, however, everything
+  # changes. Objects of the class can no longer be instanced with the `#new` method.
+  # Instead, the various factor methods, such as `#spawn`, must be used. These factory
+  # methods do not return direct references to the actor object. Instead they return
+  # objects of one of the `ActorRef` subclasses. The `ActorRef` objects encapsulate
+  # actor objects. This encapsulation is necessary to prevent synchronous method calls
+  # froom being made against the actors. It also allows the messaging and lifecycle
+  # behavior to be implemented within the `ActorRef` subclasses, allowing for better
+  # separation of responsibility.
+  #
+  # @see Concurrent::ActorRef
+  #
+  # @see http://akka.io/
+  # @see http://www.erlang.org/doc/getting_started/conc_prog.html
+  # @see http://www.scala-lang.org/api/current/index.html#scala.actors.Actor
+  #
+  # @see http://doc.akka.io/docs/akka/snapshot/general/supervision.html#What_Restarting_Means What Restarting Means
+  # @see http://doc.akka.io/docs/akka/snapshot/general/supervision.html#What_Lifecycle_Monitoring_Means What Lifecycle Monitoring Means
+  module ActorContext
+
+    # Callback method called by the `ActorRef` which encapsulates the actor instance.
+    def on_start
+    end
+
+    # Callback method called by the `ActorRef` which encapsulates the actor instance.
+    def on_shutdown
+    end
+
+    # Callback method called by the `ActorRef` which encapsulates the actor instance.
+    #
+    # @param [Time] time the date/time at which the error occurred
+    # @param [Array] message the message that caused the error
+    # @param [Exception] exception the exception object that was raised
+    def on_error(time, message, exception)
+    end
+
+    def self.included(base)
+
+      class << base
+
+        # Create a single, unregistered actor. The actor will run on its own, dedicated
+        # thread. The thread will be started the first time a message is post to the actor.
+        # Should the thread ever die it will be restarted the next time a message is post.
+        #
+        # @param [Hash] opts the options defining actor behavior
+        # @option opts [Array] :args (`nil`) arguments to be passed to the actor constructor
+        #
+        # @return [SimpleActorRef] the `ActorRef` encapsulating the actor
+        def spawn(opts = {})
+          args = opts.fetch(:args, [])
+          Concurrent::SimpleActorRef.new(self.new(*args), opts)
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/actor/actor_ref.rb

@@ -0,0 +1,67 @@
+module Concurrent
+
+  # Base class for classes that encapsulate `ActorContext` objects.
+  #
+  # @see Concurrent::ActorContext
+  module ActorRef
+
+    # @!method post(*msg, &block)
+    #
+    #   Send a message and return a future which will eventually be updated
+    #   with the result of the operation. An optional callback block can be
+    #   given which will be called once the operation is complete. Although
+    #   it is possible to use a callback block and also interrogate the
+    #   returned future it is a good practice to do one or the other.
+    #
+    #   @param [Array] msg One or more elements of the message
+    #
+    #   @yield a callback operation to be performed when the operation is complete.
+    #   @yieldparam [Time] time the date/time at which the error occurred
+    #   @yieldparam [Object] result the result of message processing or `nil` on error
+    #   @yieldparam [Exception] exception the exception object that was raised or `nil` on success
+    #
+    #   @return [IVar] a future that will eventually contain the result of message processing
+
+    # @!method post!(timeout, *msg)
+    #   Send a message synchronously and block awaiting the response.
+    #
+    #   @param [Integer] timeout the maximum number of seconds to block waiting
+    #     for a response
+    #   @param [Array] msg One or more elements of the message
+    #
+    #   @return [Object] the result of successful message processing
+    #
+    #   @raise [Concurrent::TimeoutError] if a timeout occurs
+    #   @raise [Exception] an exception which occurred during message processing
+
+    # @!method running?()
+    #   Is the actor running and processing messages?
+    #   @return [Boolean] `true` if running else `false`
+
+    # @!method shutdown?()
+    #   Is the actor shutdown and no longer processing messages?
+    #   @return [Boolean] `true` if shutdown else `false`
+
+    # @!method shutdown()
+    #   Shutdown the actor, gracefully exit all threads, and stop processing messages.
+    #   @return [Boolean] `true` if shutdown is successful else `false`
+
+    # @!method join(limit = nil)
+    #   Suspend the current thread until the actor has been shutdown
+    #   @param [Integer] limit the maximum number of seconds to block waiting for the
+    #     actor to shutdown. Block indefinitely when `nil` or not given
+    #   @return [Boolean] `true` if the actor shutdown before the limit expired else `false`
+    #   @see http://www.ruby-doc.org/core-2.1.1/Thread.html#method-i-join
+
+    # Send a message and return. It's a fire-and-forget interaction.
+    #
+    # @param [Object] message a single value representing the message to be sent
+    #   to the actor or an array of multiple message components
+    #
+    # @return [ActorRef] self
+    def <<(message)
+      post(*message)
+      self
+    end
+  end
+end

data/lib/concurrent/{postable.rb → actor/postable.rb}

@@ -1,4 +1,4 @@
-require 'concurrent/event'
+require 'concurrent/atomic/event'
 
 module Concurrent
 

data/lib/concurrent/actor/simple_actor_ref.rb

@@ -0,0 +1,94 @@
+require 'concurrent/actor/actor_ref'
+require 'concurrent/atomic/event'
+require 'concurrent/executor/single_thread_executor'
+require 'concurrent/ivar'
+
+module Concurrent
+
+  class SimpleActorRef
+    include ActorRef
+
+    def initialize(actor, opts = {})
+      @actor           = actor
+      @mutex           = Mutex.new
+      @one_by_one      = OneByOne.new
+      @executor        = OptionsParser::get_executor_from(opts)
+      @stop_event      = Event.new
+      @reset_on_error  = opts.fetch(:reset_on_error, true)
+      @exception_class = opts.fetch(:rescue_exception, false) ? Exception : StandardError
+      @args            = opts.fetch(:args, []) if @reset_on_error
+
+      @actor.define_singleton_method(:shutdown, &method(:set_stop_event))
+      @actor.on_start
+    end
+
+    def running?
+      not @stop_event.set?
+    end
+
+    def shutdown?
+      @stop_event.set?
+    end
+
+    def post(*msg, &block)
+      raise ArgumentError.new('message cannot be empty') if msg.empty?
+      ivar = IVar.new
+      @one_by_one.post(@executor, Message.new(msg, ivar, block), &method(:process_message))
+      ivar
+    end
+
+    def post!(timeout, *msg)
+      raise Concurrent::TimeoutError unless timeout.nil? || timeout >= 0
+      ivar = self.post(*msg)
+      ivar.value(timeout)
+      if ivar.incomplete?
+        raise Concurrent::TimeoutError
+      elsif ivar.reason
+        raise ivar.reason
+      end
+      ivar.value
+    end
+
+    def shutdown
+      @mutex.synchronize do
+        return if shutdown?
+        @actor.on_shutdown
+        @stop_event.set
+      end
+    end
+
+    def join(limit = nil)
+      @stop_event.wait(limit)
+    end
+
+    private
+
+    Message = Struct.new(:payload, :ivar, :callback)
+
+    def set_stop_event
+      @stop_event.set
+    end
+
+    def process_message(message)
+      result = ex = nil
+
+      begin
+        result = @actor.receive(*message.payload)
+      rescue @exception_class => ex
+        @actor.on_error(Time.now, message.payload, ex)
+        if @reset_on_error
+          @mutex.synchronize{ @actor = @actor.class.new(*@args) }
+        end
+      ensure
+        now = Time.now
+        message.ivar.complete(ex.nil?, result, ex)
+
+        begin
+          message.callback.call(now, result, ex) if message.callback
+        rescue @exception_class => ex
+          # suppress
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/actors.rb

@@ -0,0 +1,5 @@
+require 'concurrent/actor/actor'
+require 'concurrent/actor/actor_context'
+require 'concurrent/actor/actor_ref'
+require 'concurrent/actor/postable'
+require 'concurrent/actor/simple_actor_ref'

data/lib/concurrent/agent.rb

@@ -1,15 +1,15 @@
 require 'thread'
-require 'observer'
 
-require 'concurrent/configuration'
 require 'concurrent/dereferenceable'
-require 'concurrent/utilities'
+require 'concurrent/observable'
+require 'concurrent/options_parser'
+require 'concurrent/utility/timeout'
 
 module Concurrent
 
   # An agent is a single atomic value that represents an identity. The current value
-  # of the agent can be requested at any time (#deref). Each agent has a work queue and operates on
-  # the global thread pool. Consumers can #post code blocks to the agent. The code block (function)
+  # of the agent can be requested at any time (`#deref`). Each agent has a work queue and operates on
+  # the global thread pool. Consumers can `#post` code blocks to the agent. The code block (function)
   # will receive the current value of the agent as its sole parameter. The return value of the block
   # will become the new value of the agent. Agents support two error handling modes: fail and continue.
   # A good example of an agent is a shared incrementing counter, such as the score in a video game.
@@ -34,13 +34,13 @@ module Concurrent
   #   @return [Fixnum] the maximum number of seconds before an update is cancelled
   class Agent
     include Dereferenceable
-    include OptionsParser
+    include Concurrent::Observable
 
     # The default timeout value (in seconds); used when no timeout option
     # is given at initialization
     TIMEOUT = 5
 
-    attr_reader :timeout
+    attr_reader :timeout, :task_executor, :operation_executor
 
     # Initialize a new Agent with the given initial value and provided options.
     #
@@ -49,32 +49,34 @@ module Concurrent
     #
     # @option opts [Fixnum] :timeout (TIMEOUT) maximum number of seconds before an update is cancelled
     #
-    # @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
+    # @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
+    # @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(initial, opts = {})
-      @value = initial
-      @rescuers = []
-      @validator = Proc.new { |result| true }
-      @timeout = opts.fetch(:timeout, TIMEOUT).freeze
-      @observers = CopyOnWriteObserverSet.new
-      @executor = get_executor_from(opts)
+      @value              = initial
+      @rescuers           = []
+      @validator          = Proc.new { |result| true }
+      @timeout            = opts.fetch(:timeout, TIMEOUT).freeze
+      self.observers      = CopyOnWriteObserverSet.new
+      @one_by_one         = OneByOne.new
+      @task_executor      = OptionsParser.get_task_executor_from(opts)
+      @operation_executor = OptionsParser.get_operation_executor_from(opts)
       init_mutex
       set_deref_options(opts)
     end
 
     # Specifies a block operation to be performed when an update operation raises
     # an exception. Rescue blocks will be checked in order they were added. The first
-    # block for which the raised exception "is-a" subclass of the given +clazz+ will
-    # be called. If no +clazz+ is given the block will match any caught exception.
-    # This behavior is intended to be identical to Ruby's +begin/rescue/end+ behavior.
+    # block for which the raised exception "is-a" subclass of the given `clazz` will
+    # be called. If no `clazz` is given the block will match any caught exception.
+    # This behavior is intended to be identical to Ruby's `begin/rescue/end` behavior.
     # Any number of rescue handlers can be added. If no rescue handlers are added then
     # caught exceptions will be suppressed.
     #
@@ -111,53 +113,78 @@ module Concurrent
     # @yieldparam [Object] value the result of the last update operation
     # @yieldreturn [Boolean] true if the value is valid else false
     def validate(&block)
-      @validator = block unless block.nil?
+      unless block.nil?
+        mutex.lock
+        @validator = block
+        mutex.unlock
+      end
       self
     end
     alias_method :validates, :validate
     alias_method :validate_with, :validate
     alias_method :validates_with, :validate
 
-    # Update the current value with the result of the given block operation
+    # Update the current value with the result of the given block operation,
+    # block should not do blocking calls, use #post_off for blocking calls
     #
     # @yield the operation to be performed with the current value in order to calculate
     #   the new value
     # @yieldparam [Object] value the current value
     # @yieldreturn [Object] the new value
+    # @return [true, nil] nil when no block is given
     def post(&block)
-      @executor.post{ work(&block) } unless block.nil?
+      post_on(@task_executor, &block)
     end
 
-    # Update the current value with the result of the given block operation
+    # Update the current value with the result of the given block operation,
+    # block can do blocking calls
+    #
+    # @yield the operation to be performed with the current value in order to calculate
+    #   the new value
+    # @yieldparam [Object] value the current value
+    # @yieldreturn [Object] the new value
+    # @return [true, nil] nil when no block is given
+    def post_off(&block)
+      post_on(@operation_executor, &block)
+    end
+
+    # Update the current value with the result of the given block operation,
+    # block should not do blocking calls, use #post_off for blocking calls
     #
     # @yield the operation to be performed with the current value in order to calculate
     #   the new value
     # @yieldparam [Object] value the current value
     # @yieldreturn [Object] the new value
     def <<(block)
-      self.post(&block)
+      post(&block)
       self
     end
 
-    def add_observer(observer, func=:update)
-      @observers.add_observer(observer, func)
+    # Waits/blocks until all the updates sent before this call are done.
+    #
+    # @param [Numeric] timeout the maximum time in second to wait.
+    # @return [Boolean] false on timeout, true otherwise
+    def await(timeout = nil)
+      done = Event.new
+      post { |val| done.set; val }
+      done.wait timeout
     end
 
-    alias_method :add_watch, :add_observer
+    private
 
-    def delete_observer(observer)
-      @observers.delete_observer(observer)
+    def post_on(executor, &block)
+      return nil if block.nil?
+      @one_by_one.post(executor) { work(&block) }
+      true
     end
 
-    private
-
     # @!visibility private
     Rescuer = Struct.new(:clazz, :block) # :nodoc:
 
     # @!visibility private
     def try_rescue(ex) # :nodoc:
       rescuer = mutex.synchronize do
-        @rescuers.find{|r| ex.is_a?(r.clazz) }
+        @rescuers.find { |r| ex.is_a?(r.clazz) }
       end
       rescuer.block.call(ex) if rescuer
     rescue Exception => ex
@@ -166,24 +193,31 @@ module Concurrent
 
     # @!visibility private
     def work(&handler) # :nodoc:
+      validator, value = mutex.synchronize { [@validator, @value] }
+
       begin
+        # FIXME creates second thread
+        result, valid = Concurrent::timeout(@timeout) do
+          result = handler.call(value)
+          [result, validator.call(result)]
+        end
+      rescue Exception => ex
+        exception = ex
+      end
 
-        should_notify = false
+      mutex.lock
+      should_notify = if !exception && valid
+                        @value = result
+                        true
+                      end
+      mutex.unlock
 
-        mutex.synchronize do
-          result = Concurrent::timeout(@timeout) do
-            handler.call(@value)
-          end
-          if @validator.call(result)
-            @value = result
-            should_notify = true
-          end
-        end
+      if should_notify
         time = Time.now
-        @observers.notify_observers{ [time, self.value] } if should_notify
-      rescue Exception => ex
-        try_rescue(ex)
+        observers.notify_observers { [time, self.value] }
       end
+
+      try_rescue(exception)
     end
   end
 end