concurrent-ruby 0.7.0.rc1-x86-linux → 0.7.0.rc2-x86-linux

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

@@ -1,13 +1,12 @@
 module Concurrent
-  module Actress
+  module Actor
     # Allows quick creation of actors with behaviour defined by blocks.
     # @example ping
     #   AdHoc.spawn :forward, an_actor do |where|
     #     # this block has to return proc defining #on_message behaviour
     #     -> message { where.tell message  }
     #   end
-    class AdHoc
-      include Context
+    class AdHoc < Context
       def initialize(*args, &initializer)
         @on_message = Type! initializer.call(*args), Proc
       end

data/lib/concurrent/actor/behaviour.rb

@@ -0,0 +1,70 @@
+module Concurrent
+  module Actor
+
+    # Actors have modular architecture, which is achieved by combining a light core with chain of
+    # behaviours. Each message or internal event propagates through the chain allowing the
+    # behaviours react based on their responsibility. listing few as an example:
+    #
+    # -   {Behaviour::Linking}:
+    #
+    #     > {include:Actor::Behaviour::Linking}
+    #
+    # -   {Behaviour::Awaits}:
+    #
+    #     > {include:Actor::Behaviour::Awaits}
+    #
+    # See {Behaviour}'s namespace fo other behaviours.
+    # If needed new behaviours can be added, or old one removed to get required behaviour.
+    module Behaviour
+      MESSAGE_PROCESSED = Object.new
+
+      require 'concurrent/actor/behaviour/abstract'
+      require 'concurrent/actor/behaviour/awaits'
+      require 'concurrent/actor/behaviour/buffer'
+      require 'concurrent/actor/behaviour/errors_on_unknown_message'
+      require 'concurrent/actor/behaviour/executes_context'
+      require 'concurrent/actor/behaviour/linking'
+      require 'concurrent/actor/behaviour/pausing'
+      require 'concurrent/actor/behaviour/removes_child'
+      require 'concurrent/actor/behaviour/sets_results'
+      require 'concurrent/actor/behaviour/supervised'
+      require 'concurrent/actor/behaviour/supervising'
+      require 'concurrent/actor/behaviour/termination'
+      require 'concurrent/actor/behaviour/terminates_children'
+
+      def self.basic_behaviour_definition
+        [*base,
+         *user_messages(:terminate!)]
+      end
+
+      def self.restarting_behaviour_definition
+        [*base,
+         *supervised,
+         [Behaviour::Supervising, [:reset!, :one_for_one]],
+         *user_messages(:pause!)]
+      end
+
+      def self.base
+        [[SetResults, [:terminate!]],
+         # has to be before Termination to be able to remove children form terminated actor
+         [RemovesChild, []],
+         [Termination, []],
+         [TerminatesChildren, []],
+         [Linking, []]]
+      end
+
+      def self.supervised
+        [[Supervised, []],
+         [Pausing, []]]
+      end
+
+      def self.user_messages(on_error)
+        [[Buffer, []],
+         [SetResults, [on_error]],
+         [Awaits, []],
+         [ExecutesContext, []],
+         [ErrorsOnUnknownMessage, []]]
+      end
+    end
+  end
+end

data/lib/concurrent/actor/behaviour/abstract.rb

@@ -0,0 +1,48 @@
+module Concurrent
+  module Actor
+    module Behaviour
+      class Abstract
+        include TypeCheck
+        include InternalDelegations
+
+        attr_reader :core, :subsequent
+
+        def initialize(core, subsequent)
+          @core       = Type! core, Core
+          @subsequent = Type! subsequent, Abstract, NilClass
+        end
+
+        # override to add extra behaviour
+        # @note super needs to be called not to break the chain
+        def on_envelope(envelope)
+          pass envelope
+        end
+
+        # @param [Envelope] envelope to pass to {#subsequent} behaviour
+        def pass(envelope)
+          subsequent.on_envelope envelope
+        end
+
+        # override to add extra behaviour
+        # @note super needs to be called not to break the chain
+        def on_event(event)
+          subsequent.on_event event if subsequent
+        end
+
+        # broadcasts event to all behaviours and context
+        # @see #on_event
+        # @see AbstractContext#on_event
+        def broadcast(event)
+          core.broadcast(event)
+        end
+
+        def reject_envelope(envelope)
+          envelope.reject! ActorTerminated.new(reference)
+          dead_letter_routing << envelope unless envelope.ivar
+          log Logging::DEBUG, "rejected #{envelope.message} from #{envelope.sender_path}"
+        end
+      end
+    end
+  end
+end
+

data/lib/concurrent/actor/behaviour/awaits.rb

@@ -0,0 +1,21 @@
+module Concurrent
+  module Actor
+    module Behaviour
+
+      # Handles `:await` messages. Which allows to wait on Actor to process all previously send
+      # messages.
+      # @example
+      #   actor << :a << :b
+      #   actor.ask(:await).wait # blocks until :a and :b are processed
+      class Awaits < Abstract
+        def on_envelope(envelope)
+          if envelope.message == :await
+            true
+          else
+            pass envelope
+          end
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/actor/behaviour/buffer.rb

@@ -0,0 +1,54 @@
+module Concurrent
+  module Actor
+    module Behaviour
+
+      # Any message reaching this behaviour is buffered. Only one message is is scheduled
+      # at any given time. Others are kept in buffer until another one can be scheduled.
+      # This effective means that messages handled by behaviours before buffer have higher priority
+      # and they can be processed before messages arriving into buffer. This allows to
+      # process internal actor messages like (`:link`, `:supervise`) processed first.
+      class Buffer < Abstract
+        def initialize(core, subsequent)
+          super core, subsequent
+          @buffer                     = []
+          @receive_envelope_scheduled = false
+        end
+
+        def on_envelope(envelope)
+          @buffer.push envelope
+          process_envelopes?
+          MESSAGE_PROCESSED
+        end
+
+        # Ensures that only one envelope processing is scheduled with #schedule_execution,
+        # this allows other scheduled blocks to be executed before next envelope processing.
+        # Simply put this ensures that Core is still responsive to internal calls (like add_child)
+        # even though the Actor is flooded with messages.
+        def process_envelopes?
+          unless @buffer.empty? || @receive_envelope_scheduled
+            @receive_envelope_scheduled = true
+            process_envelope
+          end
+        end
+
+        def process_envelope
+          envelope = @buffer.shift
+          return nil unless envelope
+          pass envelope
+        ensure
+          @receive_envelope_scheduled = false
+          core.schedule_execution { process_envelopes? }
+        end
+
+        def on_event(event)
+          case event
+          when :terminated, :restarted
+            @buffer.each { |envelope| reject_envelope envelope }
+            @buffer.clear
+          end
+          super event
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/actor/behaviour/errors_on_unknown_message.rb

@@ -0,0 +1,12 @@
+module Concurrent
+  module Actor
+    module Behaviour
+      # Simply fails when message arrives here.
+      class ErrorsOnUnknownMessage < Abstract
+        def on_envelope(envelope)
+          raise UnknownMessage, envelope
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/actor/behaviour/executes_context.rb

@@ -0,0 +1,18 @@
+module Concurrent
+  module Actor
+    module Behaviour
+      # Delegates messages nad events to {AbstractContext} instance
+      class ExecutesContext < Abstract
+        def on_envelope(envelope)
+          context.on_envelope envelope
+        end
+
+        def on_event(event)
+          context.on_event(event)
+          core.log Logging::DEBUG, "event: #{event.inspect}"
+          super event
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/actor/behaviour/linking.rb

@@ -0,0 +1,42 @@
+module Concurrent
+  module Actor
+    module Behaviour
+
+      # Links the actor to other actors and sends events to them,
+      # like: `:terminated`, `:paused`, errors, etc
+      class Linking < Abstract
+        def initialize(core, subsequent)
+          super core, subsequent
+          @linked = Set.new
+        end
+
+        def on_envelope(envelope)
+          case envelope.message
+          when :link
+            link envelope.sender
+          when :unlink
+            unlink envelope.sender
+          else
+            pass envelope
+          end
+        end
+
+        def link(ref)
+          @linked.add(ref)
+          true
+        end
+
+        def unlink(ref)
+          @linked.delete(ref)
+          true
+        end
+
+        def on_event(event)
+          @linked.each { |a| a << event }
+          @linked.clear if event == :terminated
+          super event
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/actor/behaviour/pausing.rb

@@ -0,0 +1,77 @@
+module Concurrent
+  module Actor
+    module Behaviour
+
+      # Allows to pause actors on errors.
+      # When paused all arriving messages are collected and processed after the actor
+      # is resumed or reset. Resume will simply continue with next message.
+      # Reset also reinitialized context. `:reset!` and `:resume!` messages are only accepted
+      # form supervisor, see Supervised behaviour.
+      class Pausing < Abstract
+        def initialize(core, subsequent)
+          super core, subsequent
+          @paused = false
+          @buffer = []
+        end
+
+        def on_envelope(envelope)
+          case envelope.message
+          when :pause!
+            pause!
+          when :resume!
+            resume!
+          when :reset!
+            reset!
+          when :restart!
+            restart!
+          else
+            if @paused
+              @buffer << envelope
+              MESSAGE_PROCESSED
+            else
+              pass envelope
+            end
+          end
+        end
+
+        def pause!(error = nil)
+          @paused = true
+          broadcast(error || :paused)
+          true
+        end
+
+        def resume!(broadcast = true)
+          @paused = false
+          broadcast(:resumed) if broadcast
+          true
+        end
+
+        def reset!(broadcast = true)
+          core.allocate_context
+          core.build_context
+          resume!(false)
+          broadcast(:reset) if broadcast
+          true
+        end
+
+        def restart!
+          reset! false
+          broadcast(:restarted)
+          true
+        end
+
+        def on_event(event)
+          case event
+          when :terminated, :restarted
+            @buffer.each { |envelope| reject_envelope envelope }
+            @buffer.clear
+          when :resumed, :reset
+            @buffer.each { |envelope| core.schedule_execution { pass envelope } }
+            @buffer.clear
+          end
+          super event
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/actor/behaviour/removes_child.rb

@@ -0,0 +1,16 @@
+module Concurrent
+  module Actor
+    module Behaviour
+      # Removes terminated children.
+      class RemovesChild < Abstract
+        def on_envelope(envelope)
+          if envelope.message == :remove_child
+            core.remove_child envelope.sender
+          else
+            pass envelope
+          end
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/actor/behaviour/sets_results.rb

@@ -0,0 +1,36 @@
+module Concurrent
+  module Actor
+    module Behaviour
+      # Collects returning value and sets the IVar in the {Envelope} or error on failure.
+      class SetResults < Abstract
+        attr_reader :error_strategy
+
+        def initialize(core, subsequent, error_strategy)
+          super core, subsequent
+          @error_strategy = Match! error_strategy, :just_log, :terminate!, :pause!
+        end
+
+        def on_envelope(envelope)
+          result = pass envelope
+          if result != MESSAGE_PROCESSED && !envelope.ivar.nil?
+            envelope.ivar.set result
+          end
+          nil
+        rescue => error
+          log Logging::ERROR, error
+          case error_strategy
+          when :terminate!
+            terminate!
+          when :pause!
+            behaviour!(Pausing).pause!(error)
+          when :just_log
+            # nothing
+          else
+            raise
+          end
+          envelope.ivar.fail error unless envelope.ivar.nil?
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/actor/behaviour/supervised.rb

@@ -0,0 +1,58 @@
+module Concurrent
+  module Actor
+    module Behaviour
+
+      # Sets nad holds the supervisor of the actor if any. There is only one or none supervisor
+      # for each actor. Each supervisor is automatically linked.
+      class Supervised < Abstract
+        attr_reader :supervisor
+
+        def initialize(core, subsequent)
+          super core, subsequent
+          @supervisor = nil
+        end
+
+        def on_envelope(envelope)
+          case envelope.message
+          when :supervise
+            supervise envelope.sender
+          when :supervisor
+            supervisor
+          when :un_supervise
+            un_supervise envelope.sender
+          when :pause!, :resume!, :reset!, :restart!
+            # allow only supervisor to control the actor
+            if @supervisor == envelope.sender
+              pass envelope
+            else
+              false
+            end
+          else
+            pass envelope
+          end
+        end
+
+        def supervise(ref)
+          @supervisor = ref
+          behaviour!(Linking).link ref
+          true
+        end
+
+        def un_supervise(ref)
+          if @supervisor == ref
+            behaviour!(Linking).unlink ref
+            @supervisor = nil
+            true
+          else
+            false
+          end
+        end
+
+        def on_event(event)
+          @supervisor = nil if event == :terminated
+          super event
+        end
+      end
+    end
+  end
+end