concurrent-ruby 0.7.0.rc1-java → 0.7.0.rc2-java

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

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

@@ -0,0 +1,34 @@
+module Concurrent
+  module Actor
+    module Behaviour
+      class Supervising < Abstract
+        def initialize(core, subsequent, handle, strategy)
+          super core, subsequent
+          @handle   = Match! handle, :terminate!, :resume!, :reset!, :restart!
+          @strategy = case @handle
+                      when :terminate!
+                        Match! strategy, nil
+                      when :resume!
+                        Match! strategy, :one_for_one
+                      when :reset!, :restart!
+                        Match! strategy, :one_for_one, :one_for_all
+                      end
+        end
+
+        def on_envelope(envelope)
+          case envelope.message
+          when Exception, :paused
+            receivers = if @strategy == :one_for_all
+                          children
+                        else
+                          [envelope.sender]
+                        end
+            receivers.each { |ch| ch << @handle }
+          else
+            pass envelope
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Concurrent
+  module Actor
+    module Behaviour
+      # Terminates all children when the actor terminates.
+      class TerminatesChildren < Abstract
+        def on_event(event)
+          children.each { |ch| ch << :terminate! } if event == :terminated
+          super event
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+module Concurrent
+  module Actor
+    module Behaviour
+
+      # Handles actor termination.
+      # @note Actor rejects envelopes when terminated.
+      class Termination < Abstract
+
+        # @!attribute [r] terminated
+        #   @return [Event] event which will become set when actor is terminated.
+        attr_reader :terminated
+
+        def initialize(core, subsequent)
+          super core, subsequent
+          @terminated = Event.new
+        end
+
+        # @note Actor rejects envelopes when terminated.
+        # @return [true, false] if actor is terminated
+        def terminated?
+          @terminated.set?
+        end
+
+        def on_envelope(envelope)
+          case envelope.message
+          when :terminated?
+            terminated?
+          when :terminate!
+            terminate!
+          when :terminated_event
+            terminated
+          else
+            if terminated?
+              reject_envelope envelope
+              MESSAGE_PROCESSED
+            else
+              pass envelope
+            end
+          end
+        end
+
+        # Terminates the actor. Any Envelope received after termination is rejected.
+        # Terminates all its children, does not wait until they are terminated.
+        def terminate!
+          return true if terminated?
+          terminated.set
+          broadcast(:terminated)
+          parent << :remove_child if parent
+          true
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/actor/context.rb

@@ -0,0 +1,153 @@
+module Concurrent
+  module Actor
+
+    # Abstract implementation of Actor context. Children has to implement
+    # {AbstractContext#on_message} and {AbstractContext#behaviour_definition} methods.
+    # There are two implementations:
+    #
+    # -   {Context}
+    #
+    #     > {include:Actor::Context}
+    #
+    # -   {RestartingContext}.
+    #
+    #     > {include:Actor::RestartingContext}
+    class AbstractContext
+      include TypeCheck
+      include InternalDelegations
+
+      attr_reader :core
+
+      # @abstract override to define Actor's behaviour
+      # @param [Object] message
+      # @return [Object] a result which will be used to set the IVar supplied to Reference#ask
+      # @note self should not be returned (or sent to other actors), {#reference} should be used
+      #   instead
+      def on_message(message)
+        raise NotImplementedError
+      end
+
+      # override to add custom code invocation on events like `:terminated`, `:resumed`, `anError`.
+      def on_event(event)
+      end
+
+      # @api private
+      def on_envelope(envelope)
+        @envelope = envelope
+        on_message envelope.message
+      ensure
+        @envelope = nil
+      end
+
+      # if you want to pass the message to next behaviour, usually {Behaviour::ErrorsOnUnknownMessage}
+      def pass
+        core.behaviour!(Behaviour::ExecutesContext).pass envelope
+      end
+
+      # Defines an actor responsible for dead letters. Any rejected message send with
+      # {Reference#tell} is sent there, a message with ivar is considered already monitored for
+      # failures. Default behaviour is to use {AbstractContext#dead_letter_routing} of the parent,
+      # so if no {AbstractContext#dead_letter_routing} method is overridden in parent-chain the message ends up in
+      # `Actor.root.dead_letter_routing` agent which will log warning.
+      # @return [Reference]
+      def dead_letter_routing
+        parent.dead_letter_routing
+      end
+
+      # @return [Array<Array(Behavior::Abstract, Array<Object>)>]
+      def behaviour_definition
+        raise NotImplementedError
+      end
+
+      # @return [Envelope] current envelope, accessible inside #on_message processing
+      def envelope
+        @envelope or raise 'envelope not set'
+      end
+
+      # override if different class for reference is needed
+      # @return [CLass] descendant of {Reference}
+      def default_reference_class
+        Reference
+      end
+
+      def tell(message)
+        reference.tell message
+      end
+
+      def ask(message)
+        raise 'actor cannot ask itself'
+      end
+
+      alias_method :<<, :tell
+      alias_method :ask!, :ask
+
+      private
+
+      def initialize_core(core)
+        @core = Type! core, Core
+      end
+
+      # behaves as {Concurrent::Actor.spawn} but :class is auto-inserted based on receiver
+      def self.spawn(name_or_opts, *args, &block)
+        Actor.spawn spawn_optionify(name_or_opts, *args), &block
+      end
+
+      # behaves as {Concurrent::Actor.spawn!} but :class is auto-inserted based on receiver
+      def self.spawn!(name_or_opts, *args, &block)
+        Actor.spawn! spawn_optionify(name_or_opts, *args), &block
+      end
+
+      private
+
+      def self.spawn_optionify(name_or_opts, *args)
+        if name_or_opts.is_a? Hash
+          if name_or_opts.key?(:class) && name_or_opts[:class] != self
+            raise ArgumentError,
+                  ':class option is ignored when calling on context class, use Actor.spawn instead'
+          end
+          name_or_opts.merge class: self
+        else
+          { class: self, name: name_or_opts, args: args }
+        end
+      end
+
+      # to avoid confusion with Kernel.spawn
+      undef_method :spawn
+    end
+
+    # Basic Context of an Actor.
+    #
+    # -   linking
+    # -   terminates on error
+    #
+    # TODO describe behaviour
+    # TODO usage
+    # @example ping
+    #   class Ping < Context
+    #     def on_message(message)
+    #       message
+    #     end
+    #   end
+    #
+    #   Ping.spawn(:ping1).ask(:m).value #=> :m
+    class Context < AbstractContext
+      def behaviour_definition
+        Behaviour.basic_behaviour_definition
+      end
+    end
+
+    # Context of an Actor for complex robust systems.
+    #
+    # -   linking
+    # -   supervising
+    # -   pauses on error
+    #
+    # TODO describe behaviour
+    # TODO usage
+    class RestartingContext < AbstractContext
+      def behaviour_definition
+        Behaviour.restarting_behaviour_definition
+      end
+    end
+  end
+end

data/lib/concurrent/actor/core.rb

@@ -0,0 +1,213 @@
+module Concurrent
+  module Actor
+
+    require 'set'
+
+    # Core of the actor
+    # @note Whole class should be considered private. An user should use {Context}s and {Reference}s only.
+    # @note devel: core should not block on anything, e.g. it cannot wait on children to terminate
+    #   that would eat up all threads in task pool and deadlock
+    class Core
+      include TypeCheck
+      include Concurrent::Logging
+      include Synchronization
+
+      # @!attribute [r] reference
+      #   @return [Reference] reference to this actor which can be safely passed around
+      # @!attribute [r] name
+      #   @return [String] the name of this instance, it should be uniq (not enforced right now)
+      # @!attribute [r] path
+      #   @return [String] a path of this actor. It is used for easier orientation and logging.
+      #     Path is constructed recursively with: `parent.path + self.name` up to a {Actor.root},
+      #     e.g. `/an_actor/its_child`.
+      #     (It will also probably form a supervision path (failures will be reported up to parents)
+      #     in future versions.)
+      # @!attribute [r] executor
+      #   @return [Executor] which is used to process messages
+      # @!attribute [r] actor_class
+      #   @return [Context] a class including {Context} representing Actor's behaviour
+      attr_reader :reference, :name, :path, :executor, :context_class, :context, :behaviour_definition
+
+      # @option opts [String] name
+      # @option opts [Reference, nil] parent of an actor spawning this one
+      # @option opts [Class] reference a custom descendant of {Reference} to use
+      # @option opts [Context] actor_class a class to be instantiated defining Actor's behaviour
+      # @option opts [Array<Object>] args arguments for actor_class instantiation
+      # @option opts [Executor] executor, default is `Concurrent.configuration.global_task_pool`
+      # @option opts [true, false] link, atomically link the actor to its parent
+      # @option opts [true, false] supervise, atomically supervise the actor by its parent
+      # @option opts [Array<Array(Behavior::Abstract, Array<Object>)>] behaviour_definition, array of pairs
+      #   where each pair is behaviour class and its args, see {Behaviour.basic_behaviour}
+      # @option opts [IVar, nil] initialized, if present it'll be set or failed after {Context} initialization
+      # @option opts [Proc, nil] logger a proc accepting (level, progname, message = nil, &block) params,
+      #   can be used to hook actor instance to any logging system
+      # @param [Proc] block for class instantiation
+      def initialize(opts = {}, &block)
+        synchronize do
+          @mailbox              = Array.new
+          @serialized_execution = SerializedExecution.new
+          @executor             = Type! opts.fetch(:executor, Concurrent.configuration.global_task_pool), Executor
+          @children             = Set.new
+          @context_class        = Child! opts.fetch(:class), AbstractContext
+          allocate_context
+          @reference = (Child! opts[:reference_class] || @context.default_reference_class, Reference).new self
+          @name      = (Type! opts.fetch(:name), String, Symbol).to_s
+
+          parent       = opts[:parent]
+          @parent_core = (Type! parent, Reference, NilClass) && parent.send(:core)
+          if @parent_core.nil? && @name != '/'
+            raise 'only root has no parent'
+          end
+
+          @path   = @parent_core ? File.join(@parent_core.path, @name) : @name
+          @logger = opts[:logger]
+
+          @parent_core.add_child reference if @parent_core
+
+          initialize_behaviours opts
+
+          @args       = opts.fetch(:args, [])
+          @block      = block
+          initialized = Type! opts[:initialized], IVar, NilClass
+
+          messages = []
+          messages << :link if opts[:link]
+          messages << :supervise if opts[:supervise]
+
+          schedule_execution do
+            begin
+              build_context
+
+              messages.each do |message|
+                handle_envelope Envelope.new(message, nil, parent, reference)
+              end
+
+              initialized.set true if initialized
+            rescue => ex
+              log ERROR, ex
+              @first_behaviour.terminate!
+              initialized.fail ex if initialized
+            end
+          end
+        end
+      end
+
+      # @return [Reference, nil] of parent actor
+      def parent
+        @parent_core && @parent_core.reference
+      end
+
+      # @see AbstractContext#dead_letter_routing
+      def dead_letter_routing
+        @context.dead_letter_routing
+      end
+
+      # @return [Array<Reference>] of children actors
+      def children
+        guard!
+        @children.to_a
+      end
+
+      # @api private
+      def add_child(child)
+        guard!
+        Type! child, Reference
+        @children.add child
+        nil
+      end
+
+      # @api private
+      def remove_child(child)
+        guard!
+        Type! child, Reference
+        @children.delete child
+        nil
+      end
+
+      # is executed by Reference scheduling processing of new messages
+      # can be called from other alternative Reference implementations
+      # @param [Envelope] envelope
+      def on_envelope(envelope)
+        schedule_execution { handle_envelope envelope }
+        nil
+      end
+
+      # ensures that we are inside of the executor
+      def guard!
+        unless Actor.current == reference
+          raise "can be called only inside actor #{reference} but was #{Actor.current}"
+        end
+      end
+
+      def log(level, message = nil, &block)
+        super level, @path, message, &block
+      end
+
+      # Schedules blocks to be executed on executor sequentially,
+      # sets Actress.current
+      def schedule_execution
+        @serialized_execution.post(@executor) do
+          synchronize do
+            begin
+              Thread.current[:__current_actor__] = reference
+              yield
+            rescue => e
+              log FATAL, e
+            ensure
+              Thread.current[:__current_actor__] = nil
+            end
+          end
+        end
+
+        nil
+      end
+
+      def broadcast(event)
+        @first_behaviour.on_event(event)
+      end
+
+      # @param [Class] behaviour_class
+      # @return [Behaviour::Abstract, nil] based on behaviour_class
+      def behaviour(behaviour_class)
+        @behaviours[behaviour_class]
+      end
+
+      # @param [Class] behaviour_class
+      # @return [Behaviour::Abstract] based on behaviour_class
+      # @raise [KeyError] when no behaviour
+      def behaviour!(behaviour_class)
+        @behaviours.fetch behaviour_class
+      end
+
+      # @api private
+      def allocate_context
+        @context = @context_class.allocate
+      end
+
+      # @api private
+      def build_context
+        @context.send :initialize_core, self
+        @context.send :initialize, *@args, &@block
+      end
+
+      private
+
+      def handle_envelope(envelope)
+        log DEBUG, "received #{envelope.message.inspect} from #{envelope.sender}"
+        @first_behaviour.on_envelope envelope
+      end
+
+      def initialize_behaviours(opts)
+        @behaviour_definition = (Type! opts[:behaviour_definition] || @context.behaviour_definition, Array).each do |v|
+          Type! v, Array
+          Match! v.size, 2
+          Child! v[0], Behaviour::Abstract
+          Type! v[1], Array
+        end
+        @behaviours           = {}
+        @first_behaviour      = @behaviour_definition.reverse.
+            reduce(nil) { |last, (behaviour, args)| @behaviours[behaviour] = behaviour.new(self, last, *args) }
+      end
+    end
+  end
+end