oflow 0.3.0

data/lib/oflow/box.rb

@@ -0,0 +1,195 @@
+
+module OFlow
+
+  # A Box encapsulates data in the system. It provides a wrapper around the data
+  # which becomes immutable as it is frozen in transit between Tasks. The Box
+  # allows the contents to be modified by replacing the contents with thawed
+  # copies of the original data.
+  #
+  # Boxes are shipped between Tasks. A Tracker can also be attached to a Box to
+  # follow it and gather a history of it's movements.
+  class Box
+
+    # Tracker for the box if there is one.
+    attr_reader :tracker
+
+    # The contents of the Box.
+    attr_reader :contents
+    
+    # Create a new Box withe the content provided. The value provided will be
+    # frozen to inhibit changes to the value after the Box is created.
+    # @param value contents of the Box
+    # @param tracker [Tracker] used to track the progress of the Box
+    def initialize(value, tracker=nil)
+      @tracker = tracker
+      @contents = value
+    end
+    
+    # Receives a Box by creating a new Box whose contents is the same as the
+    # existing but with an updated tracker.
+    # @param location [String] where the Box was received, full name of Task
+    # @param op [Symbol] operation that the Box was received under
+    # @return [Box] new Box.
+    def receive(location, op)
+      return self if @tracker.nil?
+      Box.new(@contents, @tracker.receive(location, op))
+    end
+
+    # Sets or adds a value in inside the Box. The Box is changed with the new
+    # contents being thawed where necessary. A path is a set of element names in
+    # the case of a Hash or index numbers in the case of an Array joined with
+    # the ':' character as a separator.
+    # @param path [String] location of element to change or add. 
+    # @param value value for the addition or change
+    def set(path, value)
+      return aset(nil, value) if path.nil?
+      aset(path.split(':'), value)
+    end
+
+    # Sets or adds a value in inside the Box where the path is an array of
+    # element names or indices. Indices can be Fixnum or Strings.
+    # @param path [Array] location of element to change or add. 
+    # @param value value for the addition or change
+    def aset(path, value)
+      Box.new(_aset(path, @contents, value), @tracker)
+    end
+
+    # Returns the data element described by the path. A path is a set of element
+    # names in the case of a Hash or index numbers in the case of an Array
+    # joined with the ':' character as a separator.
+    # @param path [String] location of element to return
+    # @return the data element.
+    def get(path)
+      return @contents if path.nil?
+      aget(path.split(':'))
+    end
+
+    # Returns the data element described by the path which is an array of
+    # element names or indices. Indices can be Fixnum or Strings.
+    # @param path [Array] location of element to return
+    # @return the data element.
+    def aget(path)
+      _aget(path, @contents)
+    end
+
+    # Returns a string representation of the Box and contents.
+    def to_s()
+      "Box{#{@contents}, tracker: #{@tracker}}"
+    end
+    alias inspect to_s
+
+    # Called when passing to another Task. It freezes the contents recursively.
+    def freeze()
+      deep_freeze(@contents)
+      super
+    end
+
+    # Makes a copy of the frozen contents and the Box to allow modifications.
+    # @return [Box] new Box.
+    def thaw()
+      # Don't freeze the contents.
+      Box.new(thaw_value(@contents, true), @tracker)
+    end
+
+    # TBD make these module methods on a Freezer module 
+
+    def deep_freeze(value)
+      case value
+      when Array
+        value.each { |v| deep_freeze(v) }
+      when Hash
+        # hash keys are frozen already
+        value.each { |k, v| deep_freeze(v) }
+      end
+      # Don't freeze other Objects. This leaves an out for special purpose
+      # functionality.
+      value.freeze
+    end
+
+    # Make a copy of the value, unfrozen.
+    def thaw_value(value, recurse)
+      return value unless value.frozen? || recurse
+      case value
+      when Array
+        # thaws the array itself but not the elements
+        value = Array.new(value)
+        value.map! { |v| thaw_value(v, true) } if recurse
+      when Hash
+        # thaws the hash itself but not the elements
+        orig = value
+        value = {}
+        if recurse
+          orig.each { |k, v| value[k] = thaw_value(v, true) }
+        else
+          orig.each { |k, v| value[k] = v }
+        end
+      when String
+        value = String.new(value)
+      end
+      value
+    end
+
+    private
+
+    def _aset(path, value, rv)
+      return rv if path.nil? || path.empty?
+      p = path[0]
+      case value
+      when Array
+        value = Array.new(value) if value.frozen?
+        i = p.to_i
+        value[p.to_i] = _aset(path[1..-1], value[i], rv)
+      when Hash
+        if value.frozen?
+          orig = value
+          value = {}
+          orig.each { |k, v| value[k] = v }
+        end
+        if value.has_key?(p)
+          value[p] = _aset(path[1..-1], value[p], rv)
+        else
+          ps = p.to_sym
+          value[ps] = _aset(path[1..-1], value[ps], rv)
+        end
+      when NilClass
+        begin
+          i = p.to_i
+          value = []
+          value[i] = _aset(path[1..-1], nil, rv)
+        rescue
+          ps = p.to_sym
+          value = {}
+          value[ps] = _aset(path[1..-1], nil, rv)
+        end
+      else
+        raise FrozenError.new(p, value)
+      end
+      value
+    end
+
+    def _aget(path, value)
+      return value if path.nil? || path.empty? || value.nil?
+      p = path[0]
+      case value
+      when Array
+        begin
+          _aget(path[1..-1], value[p.to_i])
+        rescue
+          nil
+        end
+      when Hash
+        v = value[p] || value[p.to_sym]
+        _aget(path[1..-1], v)
+      else
+        if value.respond_to?(p.to_sym)
+          _aget(path[1..-1], value.send(p))
+        else
+          nil
+        end
+      end
+    end
+
+  end # Box
+
+end # OFlow
+

data/lib/oflow/env.rb

@@ -0,0 +1,52 @@
+
+module OFlow
+
+  # The platform that Flows are created in. It is the outer most element of the
+  # OFlow system.
+  class Env
+
+    extend HasTasks
+    extend HasLog
+    extend HasName
+    extend HasErrorHandler
+
+    # The default logging level.
+    @@log_level = Logger::WARN
+
+    init_name(nil, '')
+    init_tasks()
+
+    # Returns the default log level.
+    # @return [Fixnum] the default log level which is one of the Logger::Severity values.
+    def self.log_level()
+      @@log_level
+    end
+
+    # Sets the default log level.
+    # @param level [Fixnum] Logger::Severity to set the default log level to
+    def self.log_level=(level)
+      @@log_level = level unless level < Logger::Severity::DEBUG || Logger::Severity::FATAL < level
+    end
+
+    # Resets the error handler and log. Usually called on init and by the
+    # clear() method.
+    def self._clear()
+      @error_handler = Task.new(self, :error, Actors::ErrorHandler)
+      @log = Task.new(self, :log, Actors::Log)
+    end
+
+    _clear()
+
+    # Describes all the Flows and Tasks in the system.
+    def self.describe(detail=0, indent=0)
+      i = ' ' * indent
+      lines = ["#{i}#{self} {"]
+      @tasks.each_value { |t|
+        lines << t.describe(detail, indent + 2)
+      }
+      lines << i + "}"
+      lines.join("\n")
+    end
+
+  end # Env
+end # OFlow

data/lib/oflow/errors.rb

@@ -0,0 +1,74 @@
+
+module OFlow
+  # An Exception indicating a Task was currently not receiving new requests.
+  class BlockedError < Exception
+    def initialize()
+      super("Blocked, try again later")
+    end
+  end # BlockedError
+
+  # An Exception indicating a Task was too busy to complete the requested
+  # operation.
+  class BusyError < Exception
+    def initialize()
+      super("Busy, try again later")
+    end
+  end # BusyError
+
+  # An Exception indicating a data value is frozen and can not be modified.
+  class FrozenError < Exception
+    def initialize(name, value)
+      super("#{name}, a #{value.class} Object is frozen")
+    end
+  end # FrozenError
+
+  # An Exception indicating an error in setup or configuration.
+  class ConfigError < Exception
+    def initialize(msg)
+      super(msg)
+    end
+  end # ConfigError
+
+  # An Exception raised when no destination is found.
+  class LinkError < Exception
+    def initialize(dest)
+      super("No destination found for '#{dest}'.")
+    end
+  end # LinkError
+
+  # An Exception raised when there are validation errors.
+  class ValidateError < Exception
+    attr_accessor :problems
+
+    def initialize(errors)
+      @problems = errors
+      ma = ["#{errors.size} validation errors."]
+      errors.each { |e| ma << e.to_s }
+      super(ma.join("\n  "))
+    end
+
+    class Problem
+      LINK_ERROR = 'link_error'
+      MISSING_ERROR = 'missing_link_error'
+      INPUT_ERROR = 'input_link_error'
+
+      attr_reader :task_name
+      attr_reader :kind
+      attr_reader :message
+
+      def initialize(task_name, kind, msg)
+        @task_name = task_name
+        @kind = kind
+        @message = msg
+      end
+      
+      def to_s()
+        "#{@task_name}: #{@message}"
+      end
+      alias inpsect to_s
+
+    end # Problem
+
+  end # ValidateError
+
+end # OFlow

data/lib/oflow/flow.rb

@@ -0,0 +1,75 @@
+
+module OFlow
+
+  # The Class used to managing interactions between Tasks and sub-Flows. It can
+  # be thought of as a container for Tasks where the Flow keeps track of the
+  # Links between the Tasks.
+  class Flow
+    include HasTasks
+    include HasLinks
+    include HasName
+    include HasErrorHandler
+    include HasLog
+
+    # Create a new Flow.
+    # @param flow [Flow] Flow containing the Flow
+    # @param name [name] Flow base name
+    # @param options [Hash] additional options for the Flow
+    def initialize(flow, name, options)
+      init_name(flow, name)
+      init_tasks()
+      init_links()
+    end
+
+    # Add a Link from the edge of the Flow to a Task contained in the Flow.
+    # @param label [Symbol|String] identifier for the Link
+    # @param task_name [Symbol|String] _name base name of teh Task to link to
+    # @param op [Symbol|String] operation to call when forwarding a request to the target Task
+    def route(label, task_name, op)
+      op = op.to_sym unless op.nil?
+      label = label.to_sym unless label.nil?
+      raise ConfigError.new("Link #{label} already exists.") unless find_link(label).nil?
+      @links[label] = Link.new(task_name.to_sym, op, true)
+    end
+
+    # Receive a request which is redirected to a Linked target Task.
+    # @param op [Symbol] identifies the link that points to the destination Task or Flow
+    # @param box [Box] contents or data for the request
+    def receive(op, box)
+      box = box.receive(full_name, op)
+      lnk = find_link(op)
+      raise LinkError.new(op) if lnk.nil? || lnk.target.nil?
+      lnk.target.receive(lnk.op, box)
+    end
+
+    # Returns true if the Flow has a Link identified by the op.
+    # @param op [Symbol] identifies the Link in question
+    def has_input(op)
+      !find_link(op).nil?
+    end
+
+    # Returns a String describing the Flow.
+    # @param detail [Fixnum] higher values result in more detail in the description
+    # @param indent [Fixnum] the number of spaces to indent the description
+    def describe(detail=0, indent=0)
+      i = ' ' * indent
+      lines = ["#{i}#{name} (#{self.class}) {"]
+      @tasks.each_value { |t|
+        lines << t.describe(detail, indent + 2)
+      }
+      @links.each { |local,link|
+        if link.ingress
+          lines << "  #{i}#{local} * #{link.target_name}:#{link.op}"
+        else
+          lines << "  #{i}#{local} => #{link.target_name}:#{link.op}"
+        end
+      }
+      lines << i + "}"
+      lines.join("\n")
+    end
+
+    def _clear()
+    end
+
+  end # Flow
+end # OFlow

data/lib/oflow/haserrorhandler.rb

@@ -0,0 +1,48 @@
+
+module OFlow
+
+  # Provides functionality to find an error handler Task which is how error are
+  # handled in the system. Each Flow or Task can have a different error
+  # handler. If a Flow does not have an error handler the error bubbles up to
+  # the next Flow until an error handler is found.
+  module HasErrorHandler
+
+    # Returns an error handler Task by checking for an @error_handler variable,
+    # then looking for a Task with a base name of :error in itself or any of the
+    # containing Flows.
+    # @return [Task|nil] Task to handle errors
+    def error_handler()
+      return @error_handler if instance_variable_defined?(:@error_handler) && !@error_handler.nil?
+      if instance_variable_defined?(:@flow)
+        if @flow.respond_to?(:find_task)
+          eh = @flow.find_task(:error)
+          return eh unless eh.nil?
+        end
+        if @flow.respond_to?(:error_handler)
+          eh = @flow.error_handler()
+          return eh unless eh.nil?
+        end
+      end      
+      nil
+    end
+
+    # Sets avaliable for handling errors.
+    # @param t [Task|nil] Task for handling error or nil to unset
+    def error_handler=(t)
+      @error_handler = t
+    end
+
+    # Handles errors by putting a requestion on the error handler Task.
+    # @param e [Exception] error to handle
+    def handle_error(e)
+      handler = error_handler()
+      unless handler.nil?
+        handler.receive(nil, Box.new([e, full_name()]))
+      else
+        puts "** [#{full_name()}] #{e.class}: #{e.message}"
+        e.backtrace.each { |line| puts "    #{line}" }
+      end
+    end
+
+  end # HasErrorHandler
+end # OFlow

data/lib/oflow/haslinks.rb

@@ -0,0 +1,64 @@
+
+module OFlow
+
+  # Adds support for Links. Used by Flow and Env.
+  module HasLinks
+
+    # Sets up the links attribute.
+    def init_links()
+      @links = {}
+    end
+
+    # Creates a Link identified by the label that has a target Task or Flow and
+    # operation.
+    # @param label [Symbol|String] identifer of the Link
+    # @param target [Symbol|String] identifer of the target Task
+    # @param op [Symbol|String] operation to perform on the target Task
+    def link(label, target, op)
+      label = label.to_sym unless label.nil?
+      op = op.to_sym unless op.nil?
+      raise ConfigError.new("Link #{label} already exists.") unless @links[label].nil?
+      label = label.to_sym unless label.nil?
+      @links[label] = Link.new(target.to_sym, op)
+    end
+
+    # Attempts to find and resolve the Link identified by the label. Resolving a
+    # Link uses the target identifier to find the target Task and save that in
+    # the Link.
+    # @param label [Symbol|String] identifer of the Link
+    # @return [Link] returns the Link for the label
+    def resolve_link(label)
+      label = label.to_sym unless label.nil?
+      lnk = @links[label] || @links[nil]
+      return nil if lnk.nil?
+      set_link_target(lnk) if lnk.target.nil?
+      lnk
+    end
+
+    # Sets the target Task for a Link.
+    # @param lnk [Link] Link to find the target Task for.
+    def set_link_target(lnk)
+        if lnk.ingress
+          task = find_task(lnk.target_name)
+        else
+          task = @flow.find_task(lnk.target_name)
+        end
+        lnk.instance_variable_set(:@target, task)
+    end
+
+    # Attempts to find the Link identified by the label.
+    # @param label [Symbol|String] identifer of the Link
+    # @return [Link] returns the Link for the label
+    def find_link(label)
+      label = label.to_sym unless label.nil?
+      @links[label] || @links[nil]
+    end
+
+    # Returns the Links.
+    # @return [Hash] Hash of Links with the keys as Symbols that are the labels of the Links.
+    def links()
+      @links
+    end
+    
+  end # HasLinks
+end # OFlow

data/lib/oflow/haslog.rb

@@ -0,0 +1,72 @@
+
+module OFlow
+
+  # Adds the ability to log by sending log requests to a log Task.
+  module HasLog
+
+    # Returns a log Task by looking for that Task in an attribute and then in
+    # the contained Tasks or Tasks in outer Flows.
+    # @return [Task] log Task.
+    def log()
+      return @log if instance_variable_defined?(:@log) && !@log.nil?
+      # Log task take precedence over log variable.
+      if respond_to?(:find_task)
+        lg = find_task(:log)
+        return lg unless lg.nil?
+      end
+      return @flow.log if instance_variable_defined?(:@flow) && @flow.respond_to?(:log)
+      nil
+    end
+
+    # Sets the log attribute.
+    # @param t [Task] log Task
+    def log=(t)
+      @log = t
+    end
+
+    # Lower level logging method. Generally only used when one of the primary
+    # severity methods are called.
+    # @param level [String] message severity or level
+    # @param msg [String] message to log
+    # @param fn [String] full name of Task or Flow calling the log function
+    def log_msg(level, msg, fn)
+      lt = log()
+      unless lt.nil?
+        lt.receive(level, Box.new([msg, fn]))
+      else
+        puts "[#{fn}] #{msg}"
+      end
+    end
+
+    # Logs the message if logging level is at least debug.
+    # @param msg [String] message to log
+    def debug(msg)
+      log_msg(:debug, msg, full_name())
+    end
+
+    # Logs the message if logging level is at least info.
+    # @param msg [String] message to display or log
+    def info(msg)
+      log_msg(:info, msg, full_name())
+    end
+
+    # Logs the message if logging level is at least error.
+    # @param msg [String] message to display or log
+    def error(msg)
+      log_msg(:error, msg, full_name())
+    end
+
+    # Logs the message if logging level is at least warn.
+    # @param msg [String] message to display or log
+    def warn(msg)
+      log_msg(:warn, msg, full_name())
+    end
+
+    # Logs the message if logging level is at least fatal.
+    # @param msg [String] message to display or log
+    def fatal(msg)
+      log_msg(:fatal, msg, full_name())
+    end
+
+  end # HasLog
+end # OFlow

data/lib/oflow/hasname.rb

@@ -0,0 +1,31 @@
+
+module OFlow
+
+  # Adds support for a name attribute and the ability to form full name for a
+  # named item.
+  module HasName
+    # The name.
+    attr_reader :name
+
+    # The containing Flow is used to support the full_name() method otherwise it
+    # just sets the name.
+    # @param flow [Flow|Env] containing Flow
+    # @param name [Symbol|String] base name
+    def init_name(flow, name)
+      @flow = flow
+      @name = name.to_sym
+    end
+
+    # Similar to a full file path. The full_name described the containment of
+    # the named item.
+    # @return [String] full name of item
+    def full_name()
+      if @flow.respond_to?(:full_name)
+        @flow.full_name() + ':' + @name.to_s
+      else
+        @name.to_s
+      end
+    end
+
+  end # HasName
+end # OFlow