concurrent-ruby 0.6.0.pre.2 → 0.6.0

data/lib/concurrent/actress/core_delegations.rb

@@ -0,0 +1,37 @@
+module Concurrent
+  module Actress
+
+    # Provides publicly expose-able methods from {Core}.
+    module CoreDelegations
+      def name
+        core.name
+      end
+
+      def path
+        core.path
+      end
+
+      def parent
+        core.parent
+      end
+
+      def terminated?
+        core.terminated?
+      end
+
+      def terminated
+        core.terminated
+      end
+
+      def reference
+        core.reference
+      end
+
+      def executor
+        core.executor
+      end
+
+      alias_method :ref, :reference
+    end
+  end
+end

data/lib/concurrent/actress/doc.md

@@ -0,0 +1,53 @@
+# Light-weighted implement of Actors. Inspired by Akka and Erlang.
+
+Actors are using a thread-pool by default which makes them very cheap to create and discard.
+Thousands of actors can be created allowing to brake the program to small maintainable pieces
+without breaking single responsibility principles.
+
+## Quick example
+    
+    class Counter
+      include Context
+    
+      def initialize(initial_value)
+        @count = initial_value
+      end
+    
+      def on_message(message)
+        case message
+        when Integer
+          @count += message
+        when :terminate
+          terminate!
+        else
+          raise 'unknown'
+        end
+      end
+    end
+    
+    # create new actor
+    counter = Counter.spawn(:test_counter, 5) # => a Reference
+    
+    # send messages
+    counter.tell(1) # => counter
+    counter << 1 # => counter
+    
+    # send messages getting an IVar back for synchronization
+    counter.ask(0) # => an ivar
+    counter.ask(0).value # => 7
+    
+    # terminate the actor
+    counter.ask(:terminate).wait
+    counter.terminated? # => true
+    counter.ask(5).wait.rejected? # => true
+    
+    # failure on message processing will terminate the actor
+    counter = Counter.spawn(:test_counter, 0)
+    counter.ask('boom').wait.rejected? # => true
+    counter.terminated? # => true
+
+
+    
+
+
+

data/lib/concurrent/actress/envelope.rb

@@ -0,0 +1,25 @@
+module Concurrent
+  module Actress
+    Envelope = Struct.new :message, :ivar, :sender do
+      include TypeCheck
+
+      def initialize(message, ivar, sender)
+        super message,
+              (Type! ivar, IVar, NilClass),
+              (Type! sender, Reference, Thread)
+      end
+
+      def sender_path
+        if sender.is_a? Reference
+          sender.path
+        else
+          sender.to_s
+        end
+      end
+
+      def reject!(error)
+        ivar.fail error unless ivar.nil?
+      end
+    end
+  end
+end

data/lib/concurrent/actress/errors.rb

@@ -0,0 +1,14 @@
+module Concurrent
+  module Actress
+    Error = Class.new(StandardError)
+
+    class ActressTerminated < Error
+      include TypeCheck
+
+      def initialize(reference)
+        Type! reference, Reference
+        super reference.path
+      end
+    end
+  end
+end

data/lib/concurrent/actress/reference.rb

@@ -0,0 +1,64 @@
+module Concurrent
+  module Actress
+
+    # Reference is public interface of Actor instances. It is used for sending messages and can
+    # be freely passed around the program. It also provides some basic information about the actor
+    # see {CoreDelegations}
+    class Reference
+      include TypeCheck
+      include CoreDelegations
+
+      attr_reader :core
+      private :core
+
+      # @!visibility private
+      def initialize(core)
+        @core = Type! core, Core
+      end
+
+      # tells message to the actor
+      # @param [Object] message
+      # @return [Reference] self
+      def tell(message)
+        message message, nil
+      end
+
+      alias_method :<<, :tell
+
+      # tells message to the actor
+      # @param [Object] message
+      # @param [Ivar] ivar to be fulfilled be message's processing result
+      # @return [IVar] supplied ivar
+      def ask(message, ivar = IVar.new)
+        message message, ivar
+      end
+
+      # @note can lead to deadlocks, use only in tests or when you are sure it won't deadlock
+      # tells message to the actor
+      # @param [Object] message
+      # @param [Ivar] ivar to be fulfilled be message's processing result
+      # @return [Object] message's processing result
+      # @raise [Exception] ivar.reason if ivar is #rejected?
+      def ask!(message, ivar = IVar.new)
+        ask(message, ivar).value!
+      end
+
+      # behaves as #tell when no ivar and as #ask when ivar
+      def message(message, ivar = nil)
+        core.on_envelope Envelope.new(message, ivar, Actress.current || Thread.current)
+        return ivar || self
+      end
+
+      def to_s
+        "#<#{self.class} #{path}>"
+      end
+
+      alias_method :inspect, :to_s
+
+      def ==(other)
+        Type? other, self.class and other.send(:core) == core
+      end
+    end
+
+  end
+end

data/lib/concurrent/actress/type_check.rb

@@ -0,0 +1,48 @@
+module Concurrent
+  module Actress
+
+    # taken from Algebrick
+    # supplies type-checking helpers whenever included
+    module TypeCheck
+
+      def Type?(value, *types)
+        types.any? { |t| value.is_a? t }
+      end
+
+      def Type!(value, *types)
+        Type?(value, *types) or
+            TypeCheck.error(value, 'is not', types)
+        value
+      end
+
+      def Match?(value, *types)
+        types.any? { |t| t === value }
+      end
+
+      def Match!(value, *types)
+        Match?(value, *types) or
+            TypeCheck.error(value, 'is not matching', types)
+        value
+      end
+
+      def Child?(value, *types)
+        Type?(value, Class) &&
+            types.any? { |t| value <= t }
+      end
+
+      def Child!(value, *types)
+        Child?(value, *types) or
+            TypeCheck.error(value, 'is not child', types)
+        value
+      end
+
+      private
+
+      def self.error(value, message, types)
+        raise TypeError,
+              "Value (#{value.class}) '#{value}' #{message} any of: #{types.join('; ')}."
+      end
+    end
+  end
+end
+

data/lib/concurrent/agent.rb

@@ -4,6 +4,7 @@ require 'concurrent/dereferenceable'
 require 'concurrent/observable'
 require 'concurrent/options_parser'
 require 'concurrent/utility/timeout'
+require 'concurrent/logging'
 
 module Concurrent
 
@@ -35,6 +36,7 @@ module Concurrent
   class Agent
     include Dereferenceable
     include Concurrent::Observable
+    include Logging
 
     # The default timeout value (in seconds); used when no timeout option
     # is given at initialization
@@ -113,10 +115,14 @@ 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)
+
       unless block.nil?
-        mutex.lock
-        @validator = block
-        mutex.unlock
+        begin
+          mutex.lock
+          @validator = block
+        ensure
+          mutex.unlock
+        end
       end
       self
     end
@@ -188,7 +194,8 @@ module Concurrent
       end
       rescuer.block.call(ex) if rescuer
     rescue Exception => ex
-      # supress
+      # suppress
+      log DEBUG, ex
     end
 
     # @!visibility private
@@ -196,7 +203,6 @@ module Concurrent
       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)]
@@ -205,12 +211,15 @@ module Concurrent
         exception = ex
       end
 
-      mutex.lock
-      should_notify = if !exception && valid
-                        @value = result
-                        true
-                      end
-      mutex.unlock
+      begin
+        mutex.lock
+        should_notify = if !exception && valid
+                          @value = result
+                          true
+                        end
+      ensure
+        mutex.unlock
+      end
 
       if should_notify
         time = Time.now

data/lib/concurrent/async.rb

@@ -1,5 +1,7 @@
 require 'thread'
 require 'concurrent/configuration'
+require 'concurrent/delay'
+require 'concurrent/errors'
 require 'concurrent/ivar'
 require 'concurrent/future'
 require 'concurrent/executor/thread_pool_executor'
@@ -36,6 +38,10 @@ module Concurrent
   #   class Echo
   #     include Concurrent::Async
   #
+  #     def initialize
+  #       init_mutex # initialize the internal synchronization objects
+  #     end
+  #
   #     def echo(msg)
   #       sleep(rand)
   #       print "#{msg}\n"
@@ -52,6 +58,7 @@ module Concurrent
   # @example Monkey-patching an existing object
   #   numbers = 1_000_000.times.collect{ rand }
   #   numbers.extend(Concurrent::Async)
+  #   numbers.init_mutex # initialize the internal synchronization objects
   #   
   #   future = numbers.async.max
   #   future.state #=> :pending
@@ -61,6 +68,16 @@ module Concurrent
   #   future.state #=> :fulfilled
   #   future.value #=> 0.999999138918843
   #
+  # @note This module depends on several internal synchronization objects that
+  #       must be initialized prior to calling any of the async/await/executor methods.
+  #       The best practice is to call `init_mutex` from within the constructor
+  #       of the including class. A less ideal but acceptable practice is for the
+  #       thread creating the asynchronous object to explicitly call the `init_mutex`
+  #       method prior to calling any of the async/await/executor methods. If
+  #       `init_mutex` is *not* called explicitly the async/await/executor methods
+  #       will raize a `Concurrent::InitializationError`. This is the only way 
+  #       thread-safe initialization can be guaranteed.
+  #
   # @note Thread safe guarantees can only be made when asynchronous method calls
   #       are not mixed with synchronous method calls. Use only synchronous calls
   #       when the object is used exclusively on a single thread. Use only
@@ -142,7 +159,7 @@ module Concurrent
           ivar = Concurrent::IVar.new
           value, reason = nil, nil
           begin
-            mutex.synchronize do
+            @mutex.synchronize do
               value = @delegate.send(method, *args, &block)
             end
           rescue => reason
@@ -154,11 +171,6 @@ module Concurrent
 
         self.send(method, *args)
       end
-
-      # The lock used when delegating methods to the wrapped object.
-      #
-      # @!visibility private
-      attr_reader :mutex # :nodoc:
     end
 
     # Delegates asynchronous, thread-safe method calls to the wrapped object.
@@ -194,8 +206,8 @@ module Concurrent
 
         self.define_singleton_method(method) do |*args|
           Async::validate_argc(@delegate, method, *args)
-          Concurrent::Future.execute(executor: @executor) do
-            mutex.synchronize do
+          Concurrent::Future.execute(executor: @executor.value) do
+            @mutex.synchronize do
               @delegate.send(method, *args, &block)
             end
           end
@@ -203,13 +215,6 @@ module Concurrent
 
         self.send(method, *args)
       end
-
-      private
-
-      # The lock used when delegating methods to the wrapped object.
-      #
-      # @!visibility private
-      attr_reader :mutex # :nodoc:
     end
 
     # Causes the chained method call to be performed asynchronously on the
@@ -230,17 +235,19 @@ module Concurrent
     #   either `async` or `await`. The mutable nature of Ruby references
     #   (and object orientation in general) prevent any other thread safety
     #   guarantees. Do NOT mix non-protected method calls with protected
-    #   method call. Use ONLY protected method calls when sharing the object
+    #   method call. Use *only* protected method calls when sharing the object
     #   between threads.
     #
     # @return [Concurrent::Future] the pending result of the asynchronous operation
     #
+    # @raise [Concurrent::InitializationError] `#init_mutex` has not been called
     # @raise [NameError] the object does not respond to `method` method
     # @raise [ArgumentError] the given `args` do not match the arity of `method`
     #
     # @see Concurrent::Future
     def async
-      @__async_delegator__ ||= AsyncDelegator.new(self, executor, await.mutex)
+      raise InitializationError.new('#init_mutex was never called') unless @__async__mutex__
+      @__async_delegator__.value
     end
     alias_method :future, :async
 
@@ -262,29 +269,51 @@ module Concurrent
     #   either `async` or `await`. The mutable nature of Ruby references
     #   (and object orientation in general) prevent any other thread safety
     #   guarantees. Do NOT mix non-protected method calls with protected
-    #   method call. Use ONLY protected method calls when sharing the object
+    #   method call. Use *only* protected method calls when sharing the object
     #   between threads.
     #
     # @return [Concurrent::IVar] the completed result of the synchronous operation
     #
+    # @raise [Concurrent::InitializationError] `#init_mutex` has not been called
     # @raise [NameError] the object does not respond to `method` method
     # @raise [ArgumentError] the given `args` do not match the arity of `method`
     #
     # @see Concurrent::IVar
     def await
-      @__await_delegator__ ||= AwaitDelegator.new(self, Mutex.new)
+      raise InitializationError.new('#init_mutex was never called') unless @__async__mutex__
+      @__await_delegator__.value
     end
     alias_method :delay, :await
 
+    # Set a new executor
+    #
+    # @raise [Concurrent::InitializationError] `#init_mutex` has not been called
+    # @raise [ArgumentError] executor has already been set
     def executor=(executor)
-      raise ArgumentError.new('executor has already been set') unless @__async__executor__.nil?
-      @__async__executor__ = executor
+      raise InitializationError.new('#init_mutex was never called') unless @__async__mutex__
+      @__async__executor__.reconfigure { executor } or
+        raise ArgumentError.new('executor has already been set')
     end
 
-    private
-
-    def executor
-      @__async__executor__ ||= Concurrent.configuration.global_task_pool
+    # Initialize the internal mutex and other synchronization objects. This method
+    # *must* be called from the constructor of the including class or explicitly
+    # by the caller prior to calling any other methods. If `init_mutex` is *not*
+    # called explicitly the async/await/executor methods will raize a
+    # `Concurrent::InitializationError`. This is the only way thread-safe
+    # initialization can be guaranteed.
+    #
+    # @note This method *must* be called from the constructor of the including
+    #       class or explicitly by the caller prior to calling any other methods.
+    #       This is the only way thread-safe initialization can be guaranteed.
+    #
+    # @raise [Concurrent::InitializationError] when called more than once
+    def init_mutex
+      raise InitializationError.new('#init_mutex was already called') if @__async__mutex__
+      (@__async__mutex__ = Mutex.new).lock
+      @__async__executor__ = Delay.new{ Concurrent.configuration.global_operation_pool }
+      @__await_delegator__ = Delay.new{ AwaitDelegator.new(self, @__async__mutex__) }
+      @__async_delegator__ = Delay.new{ AsyncDelegator.new(self, @__async__executor__, @__async__mutex__) }
+      @__async__mutex__.unlock
     end
   end
 end