carnivore 0.2.0 → 0.2.2

data/lib/carnivore/source.rb

@@ -3,20 +3,24 @@ require 'celluloid'
 require 'carnivore'
 
 module Carnivore
+  # Message source
+  # @abstract
   class Source
 
     autoload :SourceContainer, 'carnivore/source_container'
 
     class << self
 
-      # args:: Hash
-      #  :type -> Source type
-      #  :args -> arguments for `Source` instance
-      # Builds a source container of `:type`
+      # Builds a source container
+      #
+      # @param args [Hash] source configuration
+      # @option args [String, Symbol] :type type of source to build
+      # @option args [Hash] :args configuration hash for source initialization
+      # @return [SourceContainer]
       def build(args={})
         [:args, :type].each do |key|
           unless(args.has_key?(key))
-            raise ArgumentError.new "Missing required parameter `:#{key}`"
+            abort ArgumentError.new "Missing required parameter `:#{key}`"
           end
         end
         require Source.require_path(args[:type]) || "carnivore/source/#{args[:type]}"
@@ -28,46 +32,56 @@ module Carnivore
         inst
       end
 
-      # type:: Symbol of type of source
-      # require_path:: Path to feed to `require`
-      # Registers a source
+      # Register a new source type
+      #
+      # @param type [Symbol] name of source type
+      # @param require_path [String] path to require when requested
+      # @return [TrueClass]
       def provide(type, require_path)
-        @source_klass ||= {}
-        @source_klass[type.to_sym] = require_path
+        @source_klass ||= Smash.new
+        @source_klass[type] = require_path
         true
       end
 
-      # type: Symbol of source type
-      # Returns register path for given type of source
+      # Registered path for given source type
+      #
+      # @param type [String, Symbol] name of source type
+      # @return [String, NilClass]
       def require_path(type)
-        @source_klass ||= {}
-        @source_klass[type.to_sym]
+        @source_klass ||= Smash.new
+        @source_klass[type]
       end
 
-      # name:: Name of source
-      # inst:: SourceContainer
       # Register the container
+      #
+      # @param name [String, Symbol] name of source
+      # @param inst [SourceContainer]
+      # @return [TrueClass]
       def register(name, inst)
-        @sources ||= {}
-        @sources[name.to_sym] = inst
+        @sources ||= Smash.new
+        @sources[name] = inst
         true
       end
 
-      # name:: Name of registered source
-      # Return source container
+      # Source container with given name
+      #
+      # @param name [String, Symbol] name of source
+      # @return [SourceContainer]
       def source(name)
         if(@sources && @sources[name.to_sym])
           @sources[name.to_sym]
         else
-          raise KeyError.new("Requested named source is not registered: #{name}")
+          Celluloid.logger.error "Source lookup failed (name: #{name})"
+          abort KeyError.new("Requested named source is not registered: #{name}")
         end
       end
 
-      # Registered containers
+      # @return [Array<SourceContainer>] registered source containers
       def sources
         @sources ? @sources.values : []
       end
 
+      # Reset communication methods within class
       def reset_comms!
         self.class_eval do
           unless(method_defined?(:reset_communications?))
@@ -84,25 +98,56 @@ module Carnivore
 
     include Celluloid
     include Utils::Logging
+    # @!parse include Carnivore::Utils::Logging
 
+    finalizer :teardown_cleanup
+
+    # @return [String, Symbol] name of source
     attr_reader :name
+    # @return [Array<Callback>] registered callbacks
     attr_reader :callbacks
+    # @return [TrueClass, FalseClass] auto confirm received messages
     attr_reader :auto_confirm
+    # @return [TrueClass, FalseClass] start source processing on initialization
     attr_reader :auto_process
+    # @return [TrueClass, FalseClass] message processing control switch
     attr_reader :run_process
+    # @return [Carnivore::Supervisor] supervisor maintaining callback instances
     attr_reader :callback_supervisor
+    # @return [Hash] registry of processed messages
     attr_reader :message_registry
+    # @return [Queue] local loop message queue
     attr_reader :message_loop
+    # @return [Queue] remote message queue
+    attr_reader :message_remote
+    # @return [TrueClass, FalseClass] currently processing a message
     attr_reader :processing
 
+    # Create new Source
+    #
+    # @param args [Hash]
+    # @option args [String, Symbol] :name name of source
+    # @option args [TrueClass, FalseClass] :auto_process start processing on initialization
+    # @option args [TrueClass, FalseClass] :auto_confirm confirm messages automatically on receive
+    # @option args [Proc] :orphan_callback execute block when no callbacks are valid for message
+    # @option args [TrueClass, FalseClass] :prevent_duplicates setup and use message registry
+    # @option args [Array<Callback>] :callbacks callbacks to register on this source
     def initialize(args={})
+      @args = Smash.new(args)
       @callbacks = []
-      @message_loop = []
+      @message_loop = Queue.new
+      @message_remote = Queue.new
       @callback_names = {}
-      @auto_process = args.fetch(:auto_process, true)
+      @auto_process = !!args.fetch(:auto_process, true)
       @run_process = true
       @auto_confirm = !!args[:auto_confirm]
       @callback_supervisor = Carnivore::Supervisor.create!.last
+      if(args[:orphan_callback])
+        unless(args[:orphan_callback].is_a?(Proc))
+          raise TypeError.new("Expected `Proc` type for `orphan_callback` but received `#{args[:orphan_callback].class}`")
+        end
+        define_singleton_method(:orphan_callback, &args[:orphan_callback])
+      end
       if(args[:prevent_duplicates])
         init_registry
       end
@@ -124,61 +169,70 @@ module Carnivore
     end
 
     # Ensure we cleanup our internal supervisor before bailing out
-    def terminate
+    def teardown_cleanup
+      warn 'Termination request received. Tearing down!'
       callback_supervisor.terminate
-      super
     end
 
-    # Automatically confirm messages after dispatch
+    # @return [TrueClass, FalseClass] automatic message confirmation enabled
     def auto_confirm?
       @auto_confirm
     end
 
-    # Return string for inspection
+    # @return [String] inspection formatted string
     def inspect
       "<#{self.class.name}:#{object_id} @name=#{name} @callbacks=#{Hash[*callbacks.map{|k,v| [k,v.object_id]}.flatten]}>"
     end
 
-    # Return string of instance
+    # @return [String] stringified instance
     def to_s
       "<#{self.class.name}:#{object_id} @name=#{name}>"
     end
 
-    # args:: Argument hash used to initialize instance
-    # Setup called during initialization for child sources to override
+    # Setup hook for source requiring customized setup
+    #
+    # @param args [Hash] initialization hash
     def setup(args={})
       debug 'No custom setup declared'
     end
 
-    # args:: Argument hash
-    # Connection method to be overridden in child sources
-    def connect(args={})
+    # Connection hook for sources requiring customized connect
+    #
+    # @param args [Hash] initialization hash
+    def connect
       debug 'No custom connect declared'
     end
 
-    # args:: number of messages to read
-    # Returns messages from source
+    # Receive messages from source
+    # @abstract
+    #
+    # @param n [Integer] number of messages
+    # @return [Object, Array<Object>] payload or array of payloads
     def receive(n=1)
-      raise NoMethodError.new('Abstract method not valid for runtime')
+      raise NotImplementedError.new('Abstract method not valid for runtime')
     end
 
-    # message:: Payload to transmit
-    # original_message:: Original `Carnivore::Message`
-    # args:: Custom arguments
-    # Transmit message on source
+    # Send payload to source
+    #
+    # @param message [Object] payload
+    # @param original_message [Carnviore::Message] original message if reply to extract optional metadata
+    # @param args [Hash] optional extra arguments
     def transmit(message, original_message=nil, args={})
-      raise NoMethodError.new('Abstract method not valid for runtime')
+      raise NotImplemented.new('Abstract method not valid for runtime')
     end
 
-    # message:: Carnivore::Message
     # Confirm receipt of the message on source
+    #
+    # @param message [Carnivore::Message]
     def confirm(message)
       debug 'No custom confirm declared'
     end
 
-    # callback_name:: Name of callback
-    # block_or_class:: Carnivore::Callback class or a block
     # Adds the given callback to the source for message processing
+    #
+    # @param callback_name [String, Symbol] name of callback
+    # @param block_or_class [Carnivore::Callback, Proc]
+    # @return [self]
     def add_callback(callback_name, block_or_class)
       name = "#{self.name}:#{callback_name}"
       if(block_or_class.is_a?(Class))
@@ -188,32 +242,36 @@ module Carnivore
           return self
         elsif(size == 1)
           debug "Adding callback class (#{block_or_class}) under supervision. Name: #{callback_name(name)}"
-          callback_supervisor.supervise_as callback_name(name), block_or_class, name
+          callback_supervisor.supervise_as callback_name(name), block_or_class, name, current_actor
         else
           debug "Adding callback class (#{block_or_class}) under supervision pool (#{size} workers). Name: #{callback_name(name)}"
-          callback_supervisor.pool block_or_class, as: callback_name(name), size: size, args: [name]
+          callback_supervisor.pool block_or_class, as: callback_name(name), size: size, args: [name, current_actor]
         end
       else
         debug "Adding custom callback class  from block (#{block_or_class}) under supervision. Name: #{callback_name(name)}"
-        callback_supervisor.supervise_as callback_name(name), Callback, name, block_or_class
+        callback_supervisor.supervise_as callback_name(name), Callback, name, current_actor, block_or_class
       end
       callbacks.push(name).uniq!
       self
     end
 
-    # name:: Name of callback
     # Remove the named callback from the source
+    #
+    # @param name [String, Symbol]
+    # @return [self]
     def remove_callback(name)
       unless(@callbacks.include?(callback_name(name)))
-        raise NameError.new("Failed to locate callback named: #{name}")
+        abort NameError.new("Failed to locate callback named: #{name}")
       end
       actors[callback_name(name)].terminate
       @callbacks.delete(name)
       self
     end
 
-    # name:: Name of callback
     # Returns namespaced name (prefixed with source name and instance id)
+    #
+    # @param name [String, Symbol] name of callback
+    # @return [Carnivore::Callback, NilClass]
     def callback_name(name)
       unless(@callback_names[name])
         @callback_names[name] = [@name, self.object_id, name].join(':').to_sym
@@ -221,22 +279,28 @@ module Carnivore
       @callback_names[name]
     end
 
-    # msg:: New message received from source
-    # Returns formatted Carnivore::Message
+    # Create new Message from received payload
+    #
+    # @param msg [Object] received payload
+    # @return [Carnivore::Message]
     def format(msg)
       actor = Carnivore::Supervisor.supervisor[name]
       if(actor)
         Message.new(
           :message => msg,
-          :source => actor
+          :source => actor.current_actor
         )
       else
         abort "Failed to locate self in registry (#{name})"
       end
     end
 
-    # m:: Carnivore::Message
-    # Returns true if message is valid to be processed
+    # Validate message is allowed before processing. This is currently
+    # only used when the message registry is enabled to prevent
+    # duplicate message processing.
+    #
+    # @param m [Carnivore::Message]
+    # @return [TrueClass, FalseClass]
     def valid_message?(m)
       if(message_registry)
         if(message_registry.valid?(m))
@@ -250,66 +314,104 @@ module Carnivore
       end
     end
 
-    # args:: Arguments
-    # Start processing messages from source
+    # Process incoming messages from this source
+    #
+    # @param args [Object] list of arguments
+    # @return [TrueClass]
     def process(*args)
       begin
         while(run_process && !callbacks.empty?)
           @processing = true
-          loop_msgs = future.loop_receive unless loop_msgs
-          remote_msgs = future.receive unless remote_msgs
-          if(loop_msgs.ready?)
-            msgs = loop_msgs.value
-            loop_msgs = nil
-          elsif(remote_msgs.ready?)
-            msgs = remote_msgs.value
-            remote_msgs = nil
-          else
-            msgs = []
+          async.receive_messages
+          if(message_loop.empty? && message_remote.empty?)
+            wait(:messages_available)
           end
+          msgs = []
+          msgs.push message_loop.pop unless message_loop.empty?
+          msgs.push message_remote.pop unless message_remote.empty?
           msgs = [msgs].flatten.compact.map do |m|
             if(valid_message?(m))
               format(m)
             end
           end.compact
           msgs.each do |msg|
-            @callbacks.each do |name|
+            if(respond_to?(:orphan_callback))
+              valid_callbacks = callbacks.find_all do |name|
+                callback_supervisor[callback_name(name)].valid?(msg)
+              end
+            else
+              valid_callbacks = callbacks
+            end
+            valid_callbacks.each do |name|
               debug "Dispatching message<#{msg[:message].object_id}> to callback<#{name} (#{callback_name(name)})>"
               callback_supervisor[callback_name(name)].async.call(msg)
             end
+            if(valid_callbacks.empty?)
+              warn "Received message was not processed through any callbacks on this source: #{msg}"
+              orphan_callback(current_actor, msg) if respond_to?(:orphan_callback)
+            end
           end
-          sleep(1) if msgs.empty?
         end
       ensure
         @processing = false
       end
+      true
     end
 
-    # args:: unused
-    # Return queued message from internal loop
+    # Receive messages from source
+    # @return [TrueClass]
+    def receive_messages
+      loop do
+        message_remote.push receive
+        signal(:messages_available)
+      end
+      true
+    end
+
+    # Get received message on local loopback
+    #
+    # @param args [Object] argument list (unused)
+    # @return [Carnivore::Message, NilClass]
     def loop_receive(*args)
-      @message_loop.shift
+      message_loop.shift
     end
 
-    # message:: Message for delivery
-    # original_message:: unused
-    # args:: unused
     # Push message onto internal loop queue
+    #
+    # @param message [Carnivore::Message]
+    # @param original_message [Object] unused
+    # @param args [Hash] unused
+    # @return [TrueClass]
     def loop_transmit(message, original_message=nil, args={})
-      @message_loop.push message
+      message_loop.push message
+      signal(:messages_available)
+      true
     end
 
-    # args:: transmit args
     # Send to local loop if processing otherwise use regular transmit
+    #
+    # @param args [Object] argument list
+    # @return [TrueClass]
     def _transmit(*args)
-      if(processing)
+      if(loop_enabled? && processing)
         loop_transmit(*args)
       else
         custom_transmit(*args)
       end
+      true
+    end
+
+    # Local message loopback is enabled. Custom sources should
+    # override this method to allow loopback delivery if desired
+    #
+    # @return [TrueClass, FalseClass]
+    def loop_enabled?
+      false
     end
 
     # Load and initialize the message registry
+    #
+    # @return [MessageRegistry] new registry
     def init_registry
       require 'carnivore/message_registry'
       @message_registry = MessageRegistry.new

data/lib/carnivore/source_container.rb

@@ -7,20 +7,30 @@ module Carnivore
     # occur prior to the supervisor actually starting the sources
     class SourceContainer
 
+      # @return [Class] class of Source
       attr_reader :klass
+      # @return [Hash] configuration hash for Source
       attr_reader :source_hash
 
-      # class_name:: Name of source class
-      # args:: argument hash to pass to source instance
+      # Create a new source container
+      #
+      # @param class_name [Class] class of Source
+      # @param args [Hash] configuration hash for source
       def initialize(class_name, args={})
         @klass = class_name
-        @source_hash = args || {}
-        @source_hash[:callbacks] = {}
+        @source_hash = Smash.new(args || {})
+        @source_hash[:callbacks] = Smash.new
       end
 
       # name:: Name of callback
       # klass:: Class of callback (optional)
       # Add a callback to a source via Class or block
+      #
+      # @param name [String, Symbol] name of callback
+      # @param klass [Class] class of callback
+      # @yield callback block
+      # @yieldparam message [Carnivore::Message] message to process
+      # @return [Class, Proc] callback registered
       def add_callback(name, klass=nil, &block)
         @source_hash[:callbacks][name] = klass || block
       end

data/lib/carnivore/spec_helper.rb

@@ -19,18 +19,36 @@ MiniTest::Spec.before do
 end
 
 # Simple waiter method to stall testing
+#
+# @param name [String, Symbol] fetch wait time from environment variable
+# @return [Numeric] seconds sleeping
 def source_wait(name='wait')
-  sleep(ENV.fetch("CARNIVORE_SOURCE_#{name.to_s.upcase}", 0.2).to_f)
+  total = ENV.fetch("CARNIVORE_SOURCE_#{name.to_s.upcase}", 1.0).to_f
+  if(block_given?)
+    elapsed = 0.0
+    until(yield || elapsed >= total)
+      sleep(0.1)
+      elapsed += 0.1
+    end
+    elapsed
+  else
+    sleep(total)
+    total
+  end
 end
 
-# dummy store that should never be used for anything real
+# Dummy message store used for testing
 class MessageStore
   class << self
 
+    # Initialize message storage
+    #
+    # @return [Array]
     def init
       @messages = []
     end
 
+    # @return [Array] messages
     def messages
       @messages
     end
@@ -38,21 +56,65 @@ class MessageStore
   end
 end
 
-# dummy source to hold final tranmission and stuff payload in store
 module Carnivore
   class Source
+    # Dummy source for testing used to capture payloads for inspection
     class Spec < Source
+
+      # @return [Array] messages confirmed
+      attr_reader :confirmed
+
+      # Creates new spec source
+      #
+      # @param args [Object] argument list (passed to Source)
+      # @yield source block (passed to Source)
+      def initialize(*args, &block)
+        super
+        @confirmed = []
+      end
+
+      # Setup the message store for payload storage
+      #
+      # @return [Array] message storage
       def setup(*args)
         MessageStore.init
       end
 
+      # Dummy receiver
       def receive(*args)
         wait(:forever)
       end
 
+      # Capture messages transmitted
+      #
+      # @param args [Object] argument list
+      # @return [TrueClass]
       def transmit(*args)
         MessageStore.messages << args.first
+        true
       end
+
+      # Format the message
+      #
+      # @param msg [Object] message payload
+      # @return [Carnivore::Message]
+      def format(msg)
+        Message.new(
+          :message => msg,
+          :source => self
+        )
+      end
+
+      # Capture confirmed messages
+      #
+      # @param payload [Object] payload of message
+      # @param args [Object] argument list (unused)
+      # @return [TrueClass]
+      def confirm(payload, *args)
+        confirmed << payload
+        true
+      end
+
     end
   end
 end

data/lib/carnivore/supervisor.rb

@@ -6,27 +6,51 @@ module Carnivore
 
     class << self
 
-      attr_reader :registry, :supervisor
-
       # Build a new supervisor
+      #
+      # @return [Carinvore::Supervisor]
       def build!
-        @registry, @supervisor = create!
-        @supervisor
+        _, s = create!
+        supervisor(s)
       end
 
       # Create a new supervisor
-      # Returns [registry,supervisor]
+      #
+      # @return [Array<[Celluloid::Registry, Carnivore::Supervisor]>]
       def create!
         registry = Celluloid::Registry.new
         [registry, run!(registry)]
       end
 
-      # Destroy the registered supervisor
+      # Get/set the default supervisor
+      #
+      # @param sup [Carnivore::Supervisor]
+      # @return [Carnivore::Supervisor]
+      def supervisor(sup=nil)
+        if(sup)
+          Celluloid::Actor[:carnivore_supervisor] = sup
+        end
+        Celluloid::Actor[:carnivore_supervisor]
+      end
+
+      # Get the registry of the default supervisor
+      #
+      # @return [Celluloid::Registry, NilClass]
+      def registry
+        if(supervisor)
+          supervisor.registry
+        end
+      end
+
+      # Destroy the registered default supervisor
+      #
+      # @return [TrueClass]
       def terminate!
         if(supervisor)
           begin
             supervisor.terminate
-          rescue Celluloid::DeadActorError
+          rescue Celluloid::DeadActorError => e
+            Celluloid::Logger.warn "Default supervisor is already in dead state (#{e.class}: #{e})"
           end
           @supervisor = nil
           @registry = nil
@@ -36,21 +60,15 @@ module Carnivore
 
     end
 
-    # name:: Name of source
-    # Return source
-    def [](name)
-      instance = @registry[name]
-      unless(instance)
-        if(member = @members.detect{|m| m && m.name.to_s == name.to_s})
-          Celluloid::Logger.warn "Found missing actor in member list. Attempting to restart manually."
-          restart_actor(member.actor, true)
-          instance = @registry[name]
-          unless(instance)
-            Celluloid::Logger.error "Actor restart failed to make it available in the registry! (#{name})"
-          end
-        end
-      end
-      instance
+    # @return [Celluloid::Registry]
+    attr_reader :registry
+
+    # Fetch actor from registry
+    #
+    # @param k [String, Symbol] identifier
+    # @return [Celluloid::Actor, NilClass]
+    def [](k)
+      registry[k]
     end
 
   end