celluloid 0.17.4 → 0.18.0

data/lib/celluloid/supervision/container/behavior/pool.rb

@@ -0,0 +1,71 @@
+require "set"
+
+module Celluloid
+  module ClassMethods
+    extend Forwardable
+    def_delegators :"Celluloid::Supervision::Container::Pool", :pooling_options
+    # Create a new pool of workers. Accepts the following options:
+    #
+    # * size: how many workers to create. Default is worker per CPU core
+    # * args: array of arguments to pass when creating a worker
+    #
+    def pool(config = {}, &block)
+      _ = Celluloid.supervise(pooling_options(config, block: block, actors: self))
+      _.actors.last
+    end
+
+    # Same as pool, but links to the pool manager
+    def pool_link(klass, config = {}, &block)
+      Supervision::Container::Pool.new_link(pooling_options(config, block: block, actors: klass))
+    end
+  end
+
+  module Supervision
+    class Container
+      extend Forwardable
+      def_delegators :"Celluloid::Supervision::Container::Pool", :pooling_options
+
+      def pool(klass, config = {}, &block)
+        _ = supervise(pooling_options(config, block: block, actors: klass))
+        _.actors.last
+      end
+
+      class Instance
+        attr_accessor :pool, :pool_size
+      end
+
+      class << self
+        # Register a pool of actors to be launched on group startup
+        def pool(klass, config, &block)
+          blocks << lambda do |container|
+            container.pool(klass, config, &block)
+          end
+        end
+      end
+
+      class Pool
+        include Behavior
+
+        class << self
+          def pooling_options(config = {}, mixins = {})
+            combined = { type: Celluloid::Supervision::Container::Pool }.merge(config).merge(mixins)
+            combined[:args] = [%i[block actors size args].each_with_object({}) do |p, e|
+              e[p] = combined.delete(p) if combined[p]
+            end]
+            combined
+          end
+        end
+
+        identifier! :size, :pool
+
+        configuration do
+          @supervisor = Container::Pool
+          @method = "pool_link"
+          @pool = true
+          @pool_size = @configuration[:size]
+          @configuration
+        end
+      end
+    end
+  end
+end

data/lib/celluloid/supervision/container/behavior/tree.rb

@@ -0,0 +1,23 @@
+module Celluloid
+  module Supervision
+    class Container
+      class Tree
+        include Behavior
+
+        identifier! :supervises, :supervise
+
+        configuration do
+          if @configuration[:supervise].is_a? Array
+            @supervisor = @configuration.dup
+            @branch = @configuration.fetch(:branch, @configuration[:as])
+            @configuration.delete(Behavior.parameter(:supervise, @configuration))
+          elsif @configuration[:supervise].is_a?(Celluloid::Supervision::Configuration)
+            @configuration
+          else
+            raise ArgumentError, "No actors given to Tree to supervise."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/celluloid/supervision/container/behavior.rb

@@ -0,0 +1,89 @@
+module Celluloid
+  module Supervision
+    class Container
+      module Behavior
+        @@injections = {}  # Hash of Class => Hash of Injections
+        @@behaviors = {}   # Hash of identifying symbol parameter => Class
+
+        module Error
+          class Mutant < Celluloid::Error; end
+        end
+
+        class << self
+          def included(klass)
+            klass.send :extend, ClassMethods
+          end
+
+          def injections
+            @@injections
+          end
+
+          def [](identifier)
+            @@behaviors[identifier]
+          end
+
+          def []=(identifier, behavior)
+            @@behaviors[identifier] = behavior
+          end
+
+          def parameter(identifier, options)
+            found = nil
+            p = Configuration.aliases.each_with_object([identifier]) { |(a, i), invoke| invoke << a if i == identifier; }
+            case p.count { |parameter| found = parameter; options.key?(parameter) }
+            when 1
+              found
+            when 0
+
+            else
+              raise Error::Mutant, "More than one kind of identifiable behavior parameter."
+            end
+          end
+
+          # Beware of order. There may be multiple behavior injections, but their order is not determined ( yet )
+          # Right now, something like a pool-coordinator-tree supervisor mutant are absolutely expected to crash.
+          # Therefore, sorry Professor X -- we kill every Mutant. On sight, no questions asked. Zero mutant love.
+          def configure(options)
+            behavior = nil
+            injection = nil
+            @@behaviors.map do |identifier, injector|
+              if identifier = parameter(identifier, options)
+                if behavior
+                  raise Error::Mutant, "More than one type of behavior expected."
+                else
+                  if @@injections[injector].include?(:configuration)
+                    injection = @@injections[behavior = injector][:configuration]
+                    options[:behavior] ||= behavior
+                  end
+                end
+              end
+            end
+
+            options[:type] ||= behavior
+            injection || proc { @configuration }
+          end
+
+          module ClassMethods
+            def identifier!(identifier, *aliases)
+              Behavior[identifier] = self
+              Configuration.parameter! :plugins, identifier
+              aliases.each do |aliased|
+                Configuration.alias! aliased, identifier
+              end
+              Configuration.save_defaults
+            end
+
+            def behavior_injections
+              Behavior.injections[self] ||= {}
+            end
+
+            Configuration::INJECTIONS.each do |point|
+              define_method(point) do |&injector|
+                behavior_injections[point] = injector
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/celluloid/supervision/container/injections.rb

@@ -0,0 +1,8 @@
+module Celluloid
+  module Supervision
+    class Container
+      class Injection
+      end
+    end
+  end
+end

data/lib/celluloid/supervision/container/instance.rb

@@ -0,0 +1,116 @@
+module Celluloid
+  # Supervise collections of actors as a group
+  module Supervision
+    class Container
+      class Instance
+        attr_reader :name, :actor
+
+        # @option options [#call, Object] :args ([]) arguments array for the
+        #   actor's constructor (lazy evaluation if it responds to #call)
+        def initialize(configuration = {})
+          @type = configuration.delete(:type)
+          @registry = configuration.delete(:registry)
+          @branch = configuration.delete(:branch) || :services
+          @configuration = configuration
+
+          # allows injections inside initialize, start, and restart
+          @injections = configuration.delete(:injections) || {}
+          invoke_injection(:before_initialize)
+
+          # Stringify keys :/
+          # de @configuration = configuration.each_with_object({}) { |(k,v), h| h[k.to_s] = v }
+
+          @name = @configuration[:as]
+          @block = @configuration[:block]
+          @args = prepare_args(@configuration[:args])
+          @method = @configuration[:method] || "new_link"
+          add_accessors
+          invoke_injection(:after_initialize)
+          start
+        end
+
+        def start
+          invoke_injection(:before_start)
+          @actor = @type.send(@method, *@args, &@block)
+          @registry.add(@name, @actor, @branch) if @name
+          invoke_injection(:after_start)
+        rescue Celluloid::TaskTimeout => ex
+          Internals::Logger.error("TaskTimeout at start of supervised instance of #{@type}")
+          raise ex
+          # TODO: Implement timeout/retry(?)
+        rescue => ex
+          Internals::Logger.error("Error ( #{ex.class} ) at start of supervised instance of #{@type}")
+          raise ex
+        end
+
+        def restart
+          # no need to reset @actor, as this is called in an `exclusive {}` block
+          # @actor = nil
+          # cleanup
+          invoke_injection(:before_restart)
+          start
+          invoke_injection(:after_restart)
+        end
+
+        def terminate
+          @actor.terminate if @actor
+          cleanup
+        rescue DeadActorError
+        end
+
+        def cleanup
+          @registry.delete(@name) if @name
+        end
+
+        private
+
+        def add_accessors
+          remove_accessors
+          if @configuration[:accessors].is_a? Array
+            # TODO: Decide which level to keep, and only keep that.
+            #       Do we provide access by Celluloid.accessor
+            #       Do we provide access by Celluloid.actor_system.accessor
+            @configuration[:accessors].each do |name|
+              Celluloid.instance_exec(@configuration[:as], name) do |actor, _where|
+                define_method(name) do
+                  Celluloid.actor_system[actor]
+                end
+              end
+              Celluloid::Actor::System.instance_exec(@configuration[:as], name) do |actor, _where|
+                define_method(name) do
+                  Celluloid.actor_system[actor]
+                end
+              end
+            end
+          end
+        end
+
+        def remove_accessors
+          if @configuration[:accessors].is_a? Array
+            @configuration[:accessors].each do |name|
+              Celluloid.instance_eval do
+                remove_method(name) rescue nil # avoid warnings in tests
+              end
+              Celluloid::Actor::System.instance_eval do
+                remove_method(name) rescue nil # avoid warnings in tests
+              end
+            end
+          end
+        end
+
+        def invoke_injection(name)
+          return unless @injections
+          block = @injections[name]
+          instance_eval(&block) if block.is_a? Proc
+        end
+
+        # Executes args if it has the method #call, and converts the return
+        # value to an Array. Otherwise, it just converts it to an Array.
+        def prepare_args(args)
+          args = args.call if args.respond_to?(:call)
+          Array(args)
+        end
+      end
+    end
+  end
+end

data/lib/celluloid/supervision/container/pool.rb

@@ -0,0 +1,210 @@
+module Celluloid
+  module Supervision
+    class Container
+      # Manages a fixed-size pool of actors
+      # Delegates work (i.e. methods) and supervises actors
+      # Don't use this class directly. Instead use MyKlass.pool
+      class Pool
+        include Celluloid
+
+        trap_exit :__crash_handler__
+        finalizer :__shutdown__
+
+        attr_reader :size, :actors
+
+        def initialize(options = {})
+          @idle = []
+          @busy = []
+          @klass = options[:actors]
+          @actors = Set.new
+          @mutex = Mutex.new
+
+          @size = options[:size] || [Celluloid.cores || 2, 2].max
+          @args = options[:args] ? Array(options[:args]) : []
+
+          # Do this last since it can suspend and/or crash
+          @idle = @size.times.map { __spawn_actor__ }
+        end
+
+        def __shutdown__
+          return unless defined?(@actors) && @actors
+          # TODO: these can be nil if initializer crashes
+          terminators = @actors.map do |actor|
+            begin
+              actor.future(:terminate)
+            rescue DeadActorError
+            end
+          end
+
+          terminators.compact.each { |terminator| terminator.value rescue nil }
+        end
+
+        def _send_(method, *args, &block)
+          actor = __provision_actor__
+          begin
+            actor._send_ method, *args, &block
+          rescue DeadActorError # if we get a dead actor out of the pool
+            wait :respawn_complete
+            actor = __provision_actor__
+            retry
+          rescue ::Exception => ex
+            abort ex
+          ensure
+            if actor.alive?
+              @idle << actor
+              @busy.delete actor
+
+              # Broadcast that actor is done processing and
+              # waiting idle
+              signal :actor_idle
+            end
+          end
+        end
+
+        def name
+          _send_ @mailbox, :name
+        end
+
+        def is_a?(klass)
+          _send_ :is_a?, klass
+        end
+
+        def kind_of?(klass)
+          _send_ :kind_of?, klass
+        end
+
+        def methods(include_ancestors = true)
+          _send_ :methods, include_ancestors
+        end
+
+        def to_s
+          _send_ :to_s
+        end
+
+        def inspect
+          _send_ :inspect
+        end
+
+        def size=(new_size)
+          new_size = [0, new_size].max
+          if new_size > size
+            delta = new_size - size
+            delta.times { @idle << __spawn_actor__ }
+          else
+            (size - new_size).times do
+              actor = __provision_actor__
+              unlink actor
+              @busy.delete actor
+              @actors.delete actor
+              actor.terminate
+            end
+          end
+          @size = new_size
+        end
+
+        def busy_size
+          @mutex.synchronize { @busy.length }
+        end
+
+        def idle_size
+          @mutex.synchronize { @idle.length }
+        end
+
+        def __idle?(actor)
+          @mutex.synchronize { @idle.include? actor }
+        end
+
+        def __busy?(actor)
+          @mutex.synchronize { @busy.include? actor }
+        end
+
+        def __busy
+          @mutex.synchronize { @busy }
+        end
+
+        def __idle
+          @mutex.synchronize { @idle }
+        end
+
+        def __state(actor)
+          return :busy if __busy?(actor)
+          return :idle if __idle?(actor)
+          :missing
+        end
+
+        # Instantiate an actor, add it to the actor Set, and return it
+        def __spawn_actor__
+          actor = @klass.new_link(*@args)
+          @mutex.synchronize { @actors.add(actor) }
+          @actors.add(actor)
+          actor
+        end
+
+        # Provision a new actor ( take it out of idle, move it into busy, and avail it )
+        def __provision_actor__
+          Task.current.guard_warnings = true
+          @mutex.synchronize do
+            while @idle.empty?
+              # Wait for responses from one of the busy actors
+              response = exclusive { receive { |msg| msg.is_a?(Internals::Response) } }
+              Thread.current[:celluloid_actor].handle_message(response)
+            end
+
+            actor = @idle.shift
+            @busy << actor
+            actor
+          end
+        end
+
+        # Spawn a new worker for every crashed one
+        def __crash_handler__(actor, reason)
+          @busy.delete actor
+          @idle.delete actor
+          @actors.delete actor
+          return unless reason
+          @idle << __spawn_actor__
+          signal :respawn_complete
+        end
+
+        def respond_to?(meth, include_private = false)
+          # NOTE: use method() here since this class
+          # shouldn't be used directly, and method() is less
+          # likely to be "reimplemented" inconsistently
+          # with other Object.*method* methods.
+
+          found = method(meth)
+          if include_private
+            found ? true : false
+          else
+            if found.is_a?(UnboundMethod)
+              found.owner.public_instance_methods.include?(meth) ||
+                found.owner.protected_instance_methods.include?(meth)
+            else
+              found.receiver.public_methods.include?(meth) ||
+                found.receiver.protected_methods.include?(meth)
+            end
+          end
+        rescue NameError
+          false
+        end
+
+        def method_missing(method, *args, &block)
+          if respond_to?(method)
+            _send_ method, *args, &block
+          else
+            super
+          end
+        end
+
+        # Since Pool allocates worker objects only just before calling them,
+        # we can still help Celluloid::Call detect passing invalid parameters to
+        # async methods by checking for those methods on the worker class
+        def method(meth)
+          super
+        rescue NameError
+          @klass.instance_method(meth.to_sym)
+        end
+      end
+    end
+  end
+end

data/lib/celluloid/supervision/container.rb

@@ -0,0 +1,144 @@
+module Celluloid
+  # Supervise actor instances in a container.
+  module Supervision
+    class Container
+      include Celluloid
+
+      trap_exit :restart_actor
+
+      class << self
+        def define(options)
+          Configuration.define(top(options))
+        end
+
+        def deploy(options)
+          Configuration.deploy(top(options))
+        end
+
+        def top(options)
+          {
+            as: options.delete(:as),
+            type: (options.delete(:type) || self),
+            branch: (options.delete(:branch) || :services),
+            supervise: options.delete(:supervise) || []
+          }
+        end
+
+        # Actors or sub-applications to be supervised
+        def blocks
+          @blocks ||= []
+        end
+
+        # Start this application (and watch it with a supervisor)
+        def run!(options = {})
+          container = new(options) do |g|
+            blocks.each do |block|
+              block.call(g)
+            end
+          end
+          container
+        end
+
+        # Run the application in the foreground with a simple watchdog
+        def run(options = {})
+          loop do
+            supervisor = run!(options)
+
+            # Take five, toplevel supervisor
+            sleep 5 while supervisor.alive? # Why 5?
+
+            Internals::Logger.error "!!! Celluloid::Supervision::Container #{self} crashed. Restarting..."
+          end
+        end
+      end
+
+      finalizer :finalize
+
+      attr_accessor :registry
+
+      # Start the container.
+      def initialize(options = {})
+        options = { registry: options } if options.is_a? Internals::Registry
+        @state = :initializing
+        @actors = [] # instances in the container
+        @registry = options.delete(:registry) || Celluloid.actor_system.registry
+        @branch = options.delete(:branch) || :services
+        yield current_actor if block_given?
+      end
+
+      execute_block_on_receiver :initialize, :supervise, :supervise_as
+
+      def add(configuration)
+        Configuration.valid?(configuration, true)
+        @actors << Instance.new(configuration.merge(registry: @registry, branch: @branch))
+        @state = :running
+        add_accessors configuration
+        Actor.current
+      end
+
+      def add_accessors(configuration)
+        if configuration[:as]
+          unless methods.include? configuration[:as]
+            self.class.instance_eval do
+              define_method(configuration[:as]) do
+                @registry[configuration[:as]]
+              end
+            end
+          end
+        end
+      end
+
+      def remove_accessors; end
+
+      def remove(actor)
+        actor = Celluloid::Actor[actor] if actor.is_a? Symbol
+        instance = find(actor)
+        instance.terminate if instance
+      end
+
+      def actors
+        @actors.map(&:actor)
+      end
+
+      def find(actor)
+        @actors.find do |instance|
+          instance.actor == actor
+        end
+      end
+
+      def [](actor_name)
+        @registry[actor_name]
+      end
+
+      # Restart a crashed actor
+      def restart_actor(actor, reason)
+        return if @state == :shutdown
+        instance = find(actor)
+        raise "a container instance went missing. This shouldn't be!" unless instance
+
+        if reason
+          exclusive { instance.restart }
+        else
+          instance.cleanup
+          @actors.delete(instance)
+        end
+      end
+
+      def shutdown
+        @state = :shutdown
+        finalize
+      end
+
+      private
+
+      def finalize
+        if @actors
+          @actors.reverse_each do |instance|
+            instance.terminate
+            @actors.delete(instance)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/celluloid/supervision/service.rb

@@ -0,0 +1,27 @@
+module Celluloid
+  module Supervision
+    module Service
+      class Root < Container
+        class << self
+          def define
+            super({
+              supervise: Celluloid.actor_system.root_configuration,
+              as: :root_supervisor,
+              accessors: [:root],
+              branch: :root,
+              type: self
+            })
+          end
+
+          def deploy(instances)
+            super(supervise: instances, branch: :root, as: :root, type: self)
+          end
+        end
+        def provider
+          Celluloid.root_services
+        end
+      end
+      class Public < Container; end
+    end
+  end
+end