rflow 1.3.0 → 1.3.1

data/lib/rflow/configuration/component.rb

@@ -3,14 +3,29 @@ require 'rflow/configuration/uuid_keyed'
 
 class RFlow
   class Configuration
+    # Represents a component definition in the SQLite database.
     class Component < ConfigurationItem
       include UUIDKeyed
       include ActiveModel::Validations
 
+      # @!attribute options
+      #   Open-ended Hash of component options, serialized via YAML to a single column.
+      #   @return [Hash]
       serialize :options, Hash
 
+      # @!attribute shard
+      #   The {Shard} in which this {Component} is to run.
+      #   @return [Shard]
       belongs_to :shard, :primary_key => 'uuid', :foreign_key => 'shard_uuid'
+
+      # @!attribute input_ports
+      #   The {InputPort}s of this component.
+      #   @return [Array<InputPort>]
       has_many :input_ports,  :primary_key => 'uuid', :foreign_key => 'component_uuid'
+
+      # @!attribute output_ports
+      #   The {OutputPort}s of this component.
+      #   @return [Array<OutputPort>]
       has_many :output_ports, :primary_key => 'uuid', :foreign_key => 'component_uuid'
 
       #TODO: Get this to work

data/lib/rflow/configuration/connection.rb

@@ -3,15 +3,27 @@ require 'rflow/configuration/uuid_keyed'
 
 class RFlow
   class Configuration
+    # Represents a component-to-component connection in the SQLite database.
     class Connection < ConfigurationItem
+      # Exception for when the connection is invalid.
       class ConnectionInvalid < StandardError; end
 
       include UUIDKeyed
       include ActiveModel::Validations
 
+      # @!attribute options
+      #   Open-ended Hash of component options, serialized via YAML to a single column.
+      #   @return [Hash]
       serialize :options, Hash
 
+      # @!attribute input_port
+      #   The {InputPort} to which this {Connection} delivers messages.
+      #   @return [InputPort]
       belongs_to :input_port, :primary_key => 'uuid', :foreign_key => 'input_port_uuid'
+
+      # @!attribute output_port
+      #   The {OutputPort} from which this {Connection} receives messages.
+      #   @return [OutputPort]
       belongs_to :output_port,:primary_key => 'uuid', :foreign_key => 'output_port_uuid'
 
       before_create :merge_default_options!
@@ -21,6 +33,7 @@ class RFlow
 
       validate :all_required_options_present?
 
+      # @!visibility private
       def all_required_options_present?
         self.class.required_options.each do |option_name|
           unless self.options.include? option_name.to_s
@@ -29,6 +42,7 @@ class RFlow
         end
       end
 
+      # @!visibility private
       def merge_default_options!
         self.options ||= {}
         self.class.default_options.each do |name, default_value_or_proc|
@@ -37,22 +51,29 @@ class RFlow
       end
 
       # Should return a list of require option names which will be
-      # used in validations.  To be overridden.
+      # used in validations. To be overridden by subclasses.
+      # @return [Array<String>]
       def self.required_options; []; end
 
       # Should return a hash of default options, where the keys are
       # the option names and the values are either default option
       # values or Procs that take a single connection argument.  This
       # allow defaults to use other parameters in the connection to
-      # construct the appropriate default value.
+      # construct the appropriate default value. To be overridden
+      # by subclasses.
+      # @return [Hash]
       def self.default_options; {}; end
 
       # By default, no broker processes are required to manage a connection.
+      # To be overridden by subclasses.
+      # @return [Array<Broker>]
       def brokers; []; end
     end
 
-    # STI Subclass for ZMQ connections and their required options
+    # Subclass of {Connection} for ZMQ connections and their required options.
     class ZMQConnection < Connection
+      # Default options required for ZeroMQ connection.
+      # @return [Hash]
       def self.default_options
         {
           'output_socket_type'    => 'PUSH',
@@ -65,15 +86,16 @@ class RFlow
       end
     end
 
-    # STI Subclass for brokered ZMQ connections and their required options
+    # Subclass of {Connection} for brokered ZMQ connections and their required options.
     #
     # We name the IPCs to resemble a quasi-component. Outputting to this
-    # connection goes to the 'in' of the IPC pair. Reading input from this
-    # connection comes from the 'out' of the IPC pair.
+    # connection goes to the +in+ of the IPC pair. Reading input from this
+    # connection comes from the +out+ of the IPC pair.
     #
     # The broker shuttles messages between the two to support the many-to-many
     # delivery pattern.
     class BrokeredZMQConnection < Connection
+      # Default ZeroMQ options required for broker connection.
       def self.default_options
         {
           'output_socket_type'    => 'PUSH',
@@ -86,6 +108,7 @@ class RFlow
       end
 
       # A brokered ZMQ connection requires one broker process.
+      # @return [Array<Broker>]
       def brokers
         @brokers ||= [ZMQStreamer.new(self)]
       end
@@ -95,6 +118,8 @@ class RFlow
     # that can't be derived from the connection. Not persisted in the database -
     # it's encapsulated in the nature of the connection.
     class ZMQStreamer
+      # Backreference to the {Connection}.
+      # @return [Connection]
       attr_reader :connection
 
       def initialize(connection)
@@ -102,9 +127,15 @@ class RFlow
       end
     end
 
-    # for testing purposes
+    # For testing purposes only.
+    # @!visibility private
     class NullConnectionConfiguration
-      attr_accessor :name, :uuid, :options, :input_port_key, :output_port_key, :delivery
+      attr_accessor :name
+      attr_accessor :uuid
+      attr_accessor :options
+      attr_accessor :input_port_key
+      attr_accessor :output_port_key
+      attr_accessor :delivery
     end
   end
 end

data/lib/rflow/configuration/port.rb

@@ -3,24 +3,43 @@ require 'rflow/configuration/uuid_keyed'
 
 class RFlow
   class Configuration
+    # Represents a component port in the SQLite database.
     class Port < ConfigurationItem
       include UUIDKeyed
       include ActiveModel::Validations
 
+      # @!attribute component
+      #   The {Component} to which this port belongs.
+      #   @return [Component]
       belongs_to :component,  :primary_key => 'uuid', :foreign_key => 'component_uuid'
 
       # TODO: Make some sort of component/port validation work here
       #validate :component_has_defined_port
     end
 
-    # STI-based classes
+    # Subclass of {Port} to represent input ports.
     class InputPort < Port
+      # @!attribute input_connections
+      #   The connections delivering messages to this {InputPort}.
+      #   @return [Array<Connection>]
       has_many :input_connections, :class_name => 'RFlow::Configuration::Connection', :primary_key => 'uuid', :foreign_key => 'input_port_uuid'
+
+      # @!attribute connections
+      #   Synonym for {input_connections}.
+      #   @return [Array<Connection>]
       has_many :connections, :class_name => 'RFlow::Configuration::Connection', :primary_key => 'uuid', :foreign_key => 'input_port_uuid'
     end
 
+    # Subclass of {Port} to represent output ports.
     class OutputPort < Port
+      # @!attribute output_connections
+      #   The connections receiving messages from this {OutputPort}.
+      #   @return [Array<Connection>]
       has_many :output_connections, :class_name => 'RFlow::Configuration::Connection', :primary_key => 'uuid', :foreign_key => 'output_port_uuid'
+
+      # @!attribute connections
+      #   Synonym for {output_connections}.
+      #   @return [Array<Connection>]
       has_many :connections, :class_name => 'RFlow::Configuration::Connection', :primary_key => 'uuid', :foreign_key => 'output_port_uuid'
     end
   end

data/lib/rflow/configuration/setting.rb

@@ -3,11 +3,13 @@ require 'rflow/configuration/uuid_keyed'
 
 class RFlow
   class Configuration
+    # Represents a setting in the SQLite database.
     class Setting < ConfigurationItem
       include ActiveModel::Validations
 
       self.primary_key = 'name'
 
+      # Default settings.
       DEFAULTS = {
         'rflow.application_name'           => 'rflow',
         'rflow.application_directory_path' => '.',
@@ -18,6 +20,7 @@ class RFlow
         'rflow.log_level' => 'INFO',
       }
 
+      private
       DIRECTORY_PATHS = [
         'rflow.application_directory_path',
         'rflow.pid_directory_path',
@@ -52,6 +55,9 @@ class RFlow
         end
       end
 
+      public
+      # Look up a {Setting} by name from the SQLite database.
+      # @return [Setting]
       def self.[](name)
         Setting.find(name).value rescue nil
       end

data/lib/rflow/configuration/shard.rb

@@ -3,20 +3,26 @@ require 'rflow/configuration/uuid_keyed'
 
 class RFlow
   class Configuration
+    # Represents a process shard in the SQLite database.
     class Shard < ConfigurationItem
       include UUIDKeyed
       include ActiveModel::Validations
 
+      # Exception for when the shard is invalid.
       class ShardInvalid < StandardError; end
 
+      # @!attribute components
+      #   The {Component}s that are to run in this {Shard}.
+      #   @return [Array<Component>]
       has_many :components, :primary_key => 'uuid', :foreign_key => 'shard_uuid'
 
       validates_uniqueness_of :name
       validates_numericality_of :count, :only_integer => true, :greater_than => 0
     end
 
-    # STI-based classes
+    # Subclass of {Shard} representing a shard instantiated by a process.
     class ProcessShard < Shard; end
+    # Subclass of {Shard} representing a shard instantiated by a thread.
     class ThreadShard < Shard; end
   end
 end

data/lib/rflow/configuration/uuid_keyed.rb

@@ -2,7 +2,12 @@ require 'uuidtools'
 
 class RFlow
   class Configuration
+    # Mixin for any {ConfigurationItem} that has a UUID key.
+    # Sets +primary_key+ column to be +uuid+ and initializes the
+    # UUID on creation.
+    # @!visibility private
     module UUIDKeyed
+      # @!visibility private
       def self.included(base)
         base.class_eval do
           self.primary_key = 'uuid'

data/lib/rflow/connection.rb

@@ -1,8 +1,11 @@
 require 'rflow/message'
 
 class RFlow
+  # Represents an RFlow connection from one component to another.
   class Connection
     class << self
+      # Build an appropriate subclass of {Connection} based on the configuration.
+      # @return [Connection]
       def build(config)
         case config.type
         when 'RFlow::Configuration::ZMQConnection'
@@ -15,7 +18,22 @@ class RFlow
       end
     end
 
-    attr_accessor :config, :uuid, :name, :options
+    # The reference to the connection's configuration.
+    # @return [Configuration::Connection]
+    attr_accessor :config
+
+    # The connection's UUID.
+    # @return [String]
+    attr_accessor :uuid
+
+    # The connection's name.
+    # @return [String]
+    attr_accessor :name
+
+    # The connection's options Hash.
+    # @return [Hash]
+    attr_accessor :options
+
     attr_writer :recv_callback
     protected
     attr_reader :recv_callback
@@ -28,44 +46,55 @@ class RFlow
       @options = config.options
     end
 
-    # Subclass and implement to be able to handle future 'recv'
+    # Subclass and implement to be able to handle future +recv+
     # methods.  Will only be called in the context of a running
-    # EventMachine reactor
+    # EventMachine reactor.
+    # @return [void]
     def connect_input!
       raise NotImplementedError, 'Raw connections do not support connect_input.  Please subclass and define a connect_input method.'
     end
 
-    # Subclass and implement to be able to handle future 'send'
+    # Subclass and implement to be able to handle future +send+
     # methods.  Will only be called in the context of a running
-    # EventMachine reactor
+    # EventMachine reactor.
+    # @return [void]
     def connect_output!
       raise NotImplementedError, 'Raw connections do not support connect_output.  Please subclass and define a connect_output method.'
     end
 
     # Subclass and implement to handle outgoing messages.  The message
-    # will be a RFlow::Message object and the subclasses are expected
+    # will be a {RFlow::Message} object and the subclasses are expected
     # to marshal it up into something that will be unmarshalled on the
-    # other side
+    # other side.
+    # @return [void]
     def send_message(message)
       raise NotImplementedError, 'Raw connections do not support send_message.  Please subclass and define a send_message method.'
     end
 
     # Parent component will set this attribute if it expects to
-    # recieve messages.  Connection subclass should call it
-    # (recv_callback.call(message)) when it gets a new message, which
+    # receive messages.  {Connection} subclass should call it
+    # (<tt>recv_callback.call(message)</tt>) when it gets a new message, which
     # will be transmitted back to the parent component's
-    # process_message method.  Sublcass is responsible for
-    # deserializing whatever was on the wire into a RFlow::Message object
+    # {Component#process_message} method.  Subclass is responsible for
+    # deserializing whatever was on the wire into a {RFlow::Message} object.
+    # @return [Proc]
     def recv_callback
       @recv_callback ||= Proc.new {|message|}
     end
 
+    # If we are connected to an {Component::InputPort} subport, the key for that subport.
+    # @return [String]
     def input_port_key; config.input_port_key; end
+
+    # If we are connected to an {Component::OutputPort} subport, the key for that subport.
+    # @return [String]
     def output_port_key; config.output_port_key; end
   end
 
   # Primarily for testing purposes. Captures whatever messages are sent on it.
   class MessageCollectingConnection < Connection
+    # The messages that were collected.
+    # @return [Array<RFlow::Message>]
     attr_accessor :messages
 
     def initialize
@@ -73,6 +102,8 @@ class RFlow
       @messages = []
     end
 
+    # Override of {send_message} which adds the message to {messages}.
+    # @return [void]
     def send_message(message)
       @messages << message
     end
@@ -88,6 +119,8 @@ class RFlow
       @target_port = target_port
     end
 
+    # Override of {send_message} which forwards the message to the target port.
+    # @return [void]
     def send_message(message)
       @target_port.send_message(message)
     end
@@ -104,6 +137,8 @@ class RFlow
       @target_port = target_port
     end
 
+    # Override of {send_message} which forwards the message to the target port.
+    # @return [void]
     def send_message(message)
       @receiver.process_message(@target_port, nil, self, message)
     end

data/lib/rflow/connections/zmq_connection.rb

@@ -9,11 +9,16 @@ require 'rflow/broker'
 require 'sys/filesystem'
 
 class RFlow
+  # Contains all connections classes.
   module Connections
+    # Represents a ZeroMQ connection.
     class ZMQConnection < RFlow::Connection
       class << self
+        # The ZeroMQ context object.
+        # @return [EM::ZeroMQ::Context]
         attr_accessor :zmq_context
 
+        # @!visibility private
         def create_zmq_context
           version = LibZMQ::version
           RFlow.logger.debug { "Creating a new ZeroMQ context; ZeroMQ version is #{version[:major]}.#{version[:minor]}.#{version[:patch]}" }
@@ -23,12 +28,13 @@ class RFlow
           EM::ZeroMQ::Context.new(1)
         end
 
-        # Returns the current ZeroMQ context object or creates it if it does not exist.
         def zmq_context
           @zmq_context ||= create_zmq_context
         end
       end
 
+      # The ZeroMQ context object.
+      # @return [EM::ZeroMQ::Context]
       def zmq_context; ZMQConnection.zmq_context; end
 
       private
@@ -41,6 +47,8 @@ class RFlow
         zmq_context # cause the ZMQ context to be created before the reactor is running
       end
 
+      # Hook up the input to the real ZeroMQ sockets.
+      # @return [void]
       def connect_input!
         RFlow.logger.debug "Connecting input #{uuid} with #{options.find_all {|k, v| k.to_s =~ /input/}}"
         check_address(options['input_address'])
@@ -65,6 +73,8 @@ class RFlow
         input_socket
       end
 
+      # Hook up the output to the real ZeroMQ sockets.
+      # @return [void]
       def connect_output!
         RFlow.logger.debug "Connecting output #{uuid} with #{options.find_all {|k, v| k.to_s =~ /output/}}"
         check_address(options['output_address'])
@@ -74,6 +84,8 @@ class RFlow
         output_socket
       end
 
+      # Send a message along the connection into ZeroMQ.
+      # @return [void]
       def send_message(message)
         RFlow.logger.debug "#{name}: Sending message of type '#{message.data_type_name.to_s}'"
 
@@ -123,6 +135,9 @@ class RFlow
       end
     end
 
+    # Subclass of {ZMQConnection} representing a brokered ZeroMQ connection
+    # (one where messages are sent to a separate process performing the
+    # many-to-many brokering function).
     class BrokeredZMQConnection < ZMQConnection
     end
 
@@ -139,6 +154,8 @@ class RFlow
         super("broker-#{connection.name}", 'Broker')
       end
 
+      # Start the broker process. Returns when things are shutting down.
+      # @return [void]
       def run_process
         version = LibZMQ::version
         RFlow.logger.debug { "Creating a new ZeroMQ context; ZeroMQ version is #{version[:major]}.#{version[:minor]}.#{version[:patch]}" }