oflow 0.3.0

data/lib/oflow/hastasks.rb

@@ -0,0 +1,209 @@
+
+module OFlow
+
+  # Provides the ability to have Tasks and Flows.
+  module HasTasks
+    
+    # Initializes the tasks attribute.
+    def init_tasks()
+      @tasks = {}
+    end
+
+    # Creates a Flow and yield to a block with the newly create Flow. Used to
+    # contruct Flows.
+    # @param name [Symbol|String] base name for the Flow
+    # @param options [Hash] optional parameters
+    # @param block [Proc] block to yield to with the new Flow instance
+    # @return [Flow] new Flow
+    def flow(name, options={}, &block)
+      f = Flow.new(self, name, options)
+      @tasks[f.name] = f
+      yield(f) if block_given?
+      f.resolve_all_links()
+      # Wait to validate until at the top so up-links don't fail validation.
+      f.validate() if Env == self
+      f
+    end
+
+    # Creates a Task and yield to a block with the newly create Task. Used to
+    # configure Tasks.
+    # @param name [Symbol|String] base name for the Task
+    # @param actor_class [Class] Class to create an Actor instance of
+    # @param options [Hash] optional parameters
+    # @param block [Proc] block to yield to with the new Task instance
+    # @return [Task] new Task
+    def task(name, actor_class, options={}, &block)
+      t = Task.new(self, name, actor_class, options)
+      @tasks[t.name] = t
+      yield(t) if block_given?
+      t
+    end
+
+    # Validates the container by verifying all links on a task have been set to
+    # a valid destination and that destination has been resolved.
+    # @raise [ValidateError] if there is an error in validation
+    def validate()
+      # collects errors and raises all errors at once if there are any
+      errors = _validation_errors()
+      raise ValidateError.new(errors) unless errors.empty?
+    end
+
+    # Returns an Array of validation errors.
+    def _validation_errors()
+      errors = []
+      @tasks.each_value { |t| errors += t._validation_errors() }
+      errors
+    end
+
+    # Resolves all the Links on all the Tasks and Flows being managed as well as
+    # any Links in the instance itself.
+    def resolve_all_links()
+      @links.each_value { |lnk|
+        set_link_target(lnk) if lnk.target.nil?
+      }
+      @tasks.each_value { |t|
+        t.resolve_all_links()
+      }
+    end
+
+    # Iterates over each Task and yields to the provided block with each Task.
+    # @param blk [Proc] Proc to call on each iteration
+    def each_task(&blk)
+      @tasks.each { |name,task| blk.yield(task) }
+    end
+
+    # Performs a recursive walk over all Tasks and yields to the provided block
+    # for each. Flows are followed recusively.
+    # @param tasks_only [Boolean] indicates on Tasks and not Flows are yielded to
+    # @param blk [Proc] Proc to call on each iteration
+    def walk_tasks(tasks_only=true, &blk)
+      @tasks.each_value do |t|
+        if t.is_a?(Task)
+          blk.yield(t)
+        else
+          blk.yield(t) unless tasks_only
+          t.walk_tasks(tasks_only, &blk)
+        end
+      end
+    end
+
+    # Locates and return a Task with the specified name.
+    # @param name [String] name of the Task
+    # @return [Task|nil] the Task with the name specified or nil
+    def find_task(name)
+      name = name.to_sym unless name.nil?
+      return self if :flow == name
+      @tasks[name]
+    end
+
+    # Locates and return a Task with the specified full name.
+    # @param name [String] full name of the Task
+    # @return [Task|nil] the Task with the name specified or nil
+    def locate(name)
+      name = name[1..-1] if name.start_with?(':')
+      name = name[0..-2] if name.end_with?(':')
+      path = name.split(':')
+      _locate(path)
+    end
+
+    def _locate(path)
+      t = @tasks[path[0].to_sym]
+      return t if t.nil? || 1 == path.size
+      t._locate(path[1..-1])
+    end
+
+    # Returns the number of active Tasks.
+    def task_count()
+      @tasks.size
+    end
+
+    # Returns the sum of all the requests in all the Tasks's queues.
+    # @return [Fixnum] total number of items waiting to be processed
+    def queue_count()
+      cnt = 0
+      @tasks.each_value { |task| cnt += task.queue_count() }
+      cnt
+    end
+
+    # Returns true of one or more Tasks is either processing a request or has a
+    # request waiting to be processed on it's input queue.
+    # @return [true|false] the busy state across all Tasks
+    def busy?
+      @tasks.each_value { |task| return true if task.busy? }
+      false
+    end
+
+    # Calls the stop() method on all Tasks.
+    def stop()
+      @tasks.each_value { |task| task.stop() }
+    end
+
+    # Calls the step() method one Task that is stopped and has an item in the
+    # queue. The Tasks with the highest backed_up() value is selected.
+    def step()
+      max = 0.0
+      best = nil
+      walk_tasks() do |t|
+        if Task::STOPPED == t.state
+          bu = t.backed_up()
+          if max < bu
+            best = t
+            max = bu
+          end
+        end
+      end
+      best.step() unless best.nil?
+      best
+    end
+
+    # Calls the start() method on all Tasks.
+    def start()
+      @tasks.each_value { |task| task.start() }
+    end
+
+    # Wakes up all the Tasks in the Flow.
+    def wakeup()
+      @tasks.each_value { |t| t.wakeup() }
+    end
+
+    # Wakes up all the Tasks in the Flow and waits for the system to become idle
+    # before returning.
+    def flush()
+      wakeup()
+      @tasks.each_value { |t| t.flush() }
+      while busy?
+        sleep(0.2)
+      end
+    end
+
+    # Sets the state of all Tasks recursively. This should not be called
+    # directly.
+    def state=(s)
+      @tasks.each_value do |task|
+        task.state = s
+      end
+    end
+
+    # Shuts down all Tasks.
+    # @param flush_first [Boolean] flag indicating shutdown should occur after the system becomes idle
+    def shutdown(flush_first=false)
+      # block all tasks first so threads can empty queues
+      @tasks.each_value do |task|
+        task.state = Task::BLOCKED
+      end
+      # shutdown and wait for queues to empty if necessary
+      @tasks.each_value do |task|
+        task.shutdown(flush_first)
+      end
+      @tasks = {}
+    end
+
+    # Clears out all Tasks and Flows and resets the object back to a empty state.
+    def clear()
+      shutdown()
+      @tasks = {}
+      _clear()
+    end
+
+  end # HasTasks
+end # OFlow

data/lib/oflow/inspector.rb

@@ -0,0 +1,501 @@
+
+require 'oterm'
+
+module OFlow
+
+  class Inspector < ::OTerm::Executor
+    attr_reader :running
+
+    def initialize(port=6060)
+      super()
+      @running = true
+      
+      register('busy', self, :busy, 'returns the busy state of the system.', nil)
+      register('list', self, :list, '[-r] [<id>] lists Flows and Tasks.',
+               %|Shows a list of Flow and Task full names that fall under the id if one is
+provided, otherwise the top leve is assumed. If the -r option is specified then
+the names of all the Flows and Tasks under the named item are displayed.|)
+      register('show', self, :show, '[-v] <id> displays a description of a Flow or Task.',
+               %|Shows a description of the identified Flow or Task. If the -v option is
+specified then a detailed description of the Tasks is displayed which included
+the number of requests queued and the status of the Task. More -v arguments
+will give increasing more detail.|)
+      register('start', self, :start, '[<task id>] start or restart a Task.', nil)
+      register('step', self, :step, '[<task id>] step once.',
+               %|Step once for the Task specfified or once for some Task that is
+waiting if no Task is identified.|)
+      register('stop', self, :stop, '[<task id>] stops a Task.', nil)
+      register('verbosity', self, :verbosity, '[<level>] show or set the verbosity or log level.', nil)
+      register('watch', self, :watch, '[<task id> displays status of Tasks.',
+               %|Displays the Task name, activity indicator, queued count, and number of
+requests processed. If the terminal supports real time updates the displays
+stays active until the X character is pressed. While running options are
+available for sorting on name, activity, or queue size.|)
+
+      # register('debug', self, :debug, 'toggles debug mode.', nil)
+
+      @server = ::OTerm::Server.new(self, port, false)
+    end
+
+    def join()
+      @server.join()
+    end
+
+    def shutdown(listener, args)
+      super
+      @running = false
+      Env.shutdown()
+    end
+
+    def greeting()
+      "Welcome to the Operations Flow Inspector."
+    end
+
+    def debug(listener, args)
+      @server.debug = !@server.debug
+    end
+
+    def busy(listener, args)
+      if Env.busy?()
+        listener.out.pl("One or more Tasks is busy.")
+      else
+        listener.out.pl("All Tasks are idle.")
+      end
+    end
+
+    def flows(listener, args)
+      Env.each_task() do |t|
+        listener.out.pl(t.full_name)
+      end
+    end
+
+    def list(listener, args)
+      if nil == args
+        Env.each_task() do |task|
+          listener.out.pl(task.full_name)
+        end
+        return
+      end
+      recurse, id, ok = _parse_opt_id_args(args, 'r', listener)
+      return unless ok
+      if id.nil?
+        flow = Env
+      else
+        flow = Env.locate(id)
+      end
+      if flow.nil?
+        listener.out.pl("--- No Flow or Task found for #{id}")
+        return
+      end
+      _walk(flow, recurse, listener) do |task|
+        listener.out.pl(task.full_name) unless Env == task
+      end
+    end
+
+    def show(listener, args)
+      if nil == args
+        listener.out.pl("--- No Flow or Task specified")
+        return
+      end
+      detail, id, ok = _parse_opt_id_args(args, 'v', listener)
+      return unless ok
+
+      task = Env.locate(id)
+      if task.nil?
+        listener.out.pl("--- Failed to find '#{id}'")
+        return
+      end
+      listener.out.pl(task.describe(detail))
+    end
+
+    def start(listener, args)
+      if nil == args || 0 == args.size()
+        Env.start()
+        listener.out.pl("All Tasks restarted")
+      else
+        args.strip!
+        task = Env.locate(args)
+        if task.nil?
+          listener.out.pl("--- Failed to find '#{args}'")
+        else
+          task.start()
+          listener.out.pl("#{task.full_name} restarted")
+        end
+      end
+    end
+
+    def step(listener, args)
+      lg = Env.log()
+      stop_after = false
+      if !lg.nil? && Task::STOPPED == lg.state
+        lg.start()
+        stop_after = true
+      end
+
+      if nil == args || 0 == args.size()
+        task = Env
+      else
+        args.strip!
+        task = Env.locate(args)
+      end
+      if task.nil?
+        listener.out.pl("--- Failed to find '#{args}'")
+      else
+        task = task.step()
+        if task.nil?
+          listener.out.pl("--- No tasks in '#{args}' are stopped or have have queued requests")
+        else
+          listener.out.pl("#{task.full_name} stepped")
+        end
+      end
+      lg.stop() if stop_after
+    end
+
+    def stop(listener, args)
+      if nil == args || 0 == args.size()
+        Env.stop()
+        listener.out.pl("All Tasks stopped(paused)")
+      else
+        args.strip!
+        task = Env.locate(args)
+        if task.nil?
+          listener.out.pl("--- Failed to find '#{args}'")
+        else
+          task.stop()
+          listener.out.pl("#{task.full_name} stopped(paused)")
+        end
+      end
+    end
+
+    def verbosity(listener, args)
+      lg = Env.log
+      if lg.nil?
+        listener.out.pl("--- No logger")
+        return
+      end
+      lga = lg.actor
+      if nil != args && 0 < args.size()
+        args.strip!
+        lg.receive(:severity, Box.new(args))
+        listener.out.pl("verbosity change pending")
+      elsif lga.respond_to?(:severity)
+        listener.out.pl("verbosity: #{lga.severity()}")
+      else
+        listener.out.pl("--- Logger does support requests for verbosity level")
+      end
+    end
+
+    def watch(listener, args)
+      tasks = []
+      if args.nil? || 0 == args.size()
+        Env.walk_tasks() { |t| tasks << t }
+      else
+        args.strip!
+        task = Env.locate(args)
+        if task.nil?
+          listener.out.pl("--- Failed to find '#{args}'")
+          return
+        elsif task.kind_of?(HasTasks)
+          task.walk_tasks() { |t| tasks << t }
+        else
+          tasks << task
+        end
+      end
+      if listener.out.is_vt100?
+        _dynamic_watch(listener, tasks)
+      else
+        max_len = 10
+        tasks.each do |t|
+          len = t.full_name.size
+          max_len = len if max_len < len
+        end
+        listener.out.pl("  %#{max_len}s  %-11s  %5s  %9s" % ['Task Name', 'Q-cnt/max', 'busy?', 'processed'])
+        tasks.each do |t|
+          listener.out.pl("  %#{max_len}s  %5d/%-5d  %5s  %9d" % [t.full_name, t.queue_count(), t.max_queue_count().to_i, t.busy?(), t.proc_count()])
+        end
+      end
+    end
+
+    # sort by values
+    BY_NAME = 'name'
+    BY_ACTIVITY = 'activity'
+    BY_QUEUE = 'queued'
+    BY_COUNT = 'count'
+    BY_STATE = 'state'
+
+    def _dynamic_watch(listener, tasks)
+      o = listener.out
+      sort_by = BY_NAME
+      rev = false
+      delay = 0.4
+      tasks.map! { |t| TaskStat.new(t) }
+      lines = tasks.size + 3
+      h, w = o.screen_size()
+      lines = h - 1 if lines > h - 1
+      o.clear_screen()
+      done = false
+      until done
+        tasks.each { |ts| ts.refresh() }
+        max = 6
+        max_n = 1
+        tasks.each do |ts|
+          max = ts.name.size if max < ts.name.size
+          max_n = ts.count.size if max_n < ts.count.size
+        end
+        # 5 for space between after, 3 for state, max_n for number
+        max_q = w - max - 8 - max_n
+
+        case sort_by
+        when BY_NAME
+          if rev
+            tasks.sort! { |a,b| b.name <=> a.name }
+          else
+            tasks.sort! { |a,b| a.name <=> b.name }
+          end
+        when BY_ACTIVITY
+          if rev
+            tasks.sort! { |a,b| a.activity <=> b.activity }
+          else
+            tasks.sort! { |a,b| b.activity <=> a.activity }
+          end
+        when BY_QUEUE
+          if rev
+            tasks.sort! { |a,b| a.queued <=> b.queued }
+          else
+            tasks.sort! { |a,b| b.queued <=> a.queued }
+          end
+        when BY_COUNT
+          if rev
+            tasks.sort! { |a,b| a.proc_cnt <=> b.proc_cnt }
+          else
+            tasks.sort! { |a,b| b.proc_cnt <=> a.proc_cnt }
+          end
+        when BY_STATE
+          if rev
+            tasks.sort! { |a,b| a.state <=> b.state }
+          else
+            tasks.sort! { |a,b| b.state <=> a.state }
+          end
+        end
+        o.set_cursor(1, 1)
+        o.bold()
+        o.underline()
+        o.p("%1$*2$s ? %3$*4$s @ Queued %5$*6$s" % ['#', -max_n, 'Task', -max, ' ', max_q])
+        o.attrs_off()
+        i = 2
+        tasks[0..lines].each do |ts|
+          o.set_cursor(i, 1)
+          o.p("%1$*2$s %5$c %3$*4$s " % [ts.count, max_n, ts.name, -max, ts.state])
+          o.set_cursor(i, max + max_n + 5)
+          case ts.activity
+          when 0
+            o.p(' ')
+          when 1
+            o.p('.')
+          when 2, 3
+            o.p('o')
+          else
+            o.p('O')
+          end
+          o.p(' ')
+          qlen = ts.queued
+          qlen = max_q if max_q < qlen
+          if 0 < qlen
+            o.reverse()
+            o.p("%1$*2$d" % [ts.queued, -qlen])
+            o.attrs_off()
+          end
+          o.clear_to_end()
+          i += 1
+        end
+        o.bold()
+        o.set_cursor(i, 1)
+        if rev
+          o.p("E) exit  R) ")
+          o.reverse()
+          o.p("reverse")
+          o.attrs_off()
+          o.bold()
+          o.p("  +) faster  -) slower [%0.1f]" % [delay])
+        else
+          o.p("E) exit  R) reverse  +) faster  -) slower [%0.1f]" % [delay])
+        end
+        i += 1
+        o.set_cursor(i, 1)
+        o.p('sort by')
+        { '#' => BY_COUNT, '?' => BY_STATE, 'N' => BY_NAME, 'A' => BY_ACTIVITY, 'Q' => BY_QUEUE }.each do |c,by|
+          if by == sort_by
+            o.p("  #{c}) ")
+            o.reverse()
+            o.p(by)
+            o.attrs_off()
+            o.bold()
+          else
+            o.p("  #{c}) #{by}")
+          end
+        end
+        o.attrs_off()
+
+        c = o.recv_wait(1, delay, /./)
+        unless c.nil?
+          case c[0]
+          when 'e', 'E'
+            done = true
+          when 'n', 'N'
+            sort_by = BY_NAME
+            rev = false
+          when 'a', 'A'
+            sort_by = BY_ACTIVITY
+            rev = false
+          when 'q', 'Q'
+            sort_by = BY_QUEUE
+            rev = false
+          when '#', 'c', 'C'
+            sort_by = BY_COUNT
+            rev = false
+          when '?', 's', 'S'
+            sort_by = BY_STATE
+            rev = false
+          when 'r', 'R'
+            rev = !rev
+          when '+'
+            delay /= 2.0 unless delay <= 0.1
+          when '-'
+            delay *= 2.0 unless 3.0 <= delay
+          end
+        end
+      end
+      o.pl()
+    end
+
+    def tab(cmd, listener)
+      start = cmd.index(' ')
+      if start.nil?
+        super
+        return
+      end
+      op = cmd[0...start]
+      start = cmd.rindex(' ')
+      pre = cmd[0...start]
+      last = cmd[start + 1..-1]
+
+      return if '-' == last[0]
+
+      # Tab completion is different depending on the command.
+      names = []
+      case op.downcase()
+      when 'verbosity'
+        names = ['fatal', 'error', 'warn', 'info', 'debug'].select { |s| s.start_with?(last.downcase()) }
+      else # expect id or options
+        with_colon = ':' == last[0]
+        Env.walk_tasks(false) do |t|
+          fn = t.full_name
+          fn = fn[1..-1] unless with_colon
+          names << fn if fn.start_with?(last)
+        end
+      end
+      
+      return if 0 == names.size
+      if 1 == names.size
+        listener.move_col(1000)
+        listener.insert(names[0][last.size..-1])
+        listener.out.prompt()
+        listener.out.p(listener.buf)
+      else
+        listener.out.pl()
+        names.each do |name|
+          listener.out.pl("#{pre} #{name}")
+        end
+        best = best_completion(last, names)
+        if best == last
+          listener.update_cmd(0)
+        else
+          listener.move_col(1000)
+          listener.insert(best[last.size..-1])
+          listener.out.prompt()
+          listener.out.p(listener.buf)
+        end
+      end
+    end
+
+    def _parse_opt_id_args(args, opt, listener)
+      opt_cnt = 0
+      id = nil
+      args.strip!
+      args.split(' ').each do |a|
+        if '-' == a[0]
+          a[1..-1].each_char do |c|
+            if c == opt
+              opt_cnt += 1
+            else
+              listener.out.pl("--- -#{c} is not a valid option")
+              return [0, nil, false]
+            end
+          end
+        elsif !id.nil?
+          listener.out.pl("--- Multiple Ids specified")
+          return [0, nil, false]
+        else
+          id = a
+        end
+      end
+      [opt_cnt, id, true]
+    end
+
+    def _walk(flow, recurse, listener, &block)
+      if flow.respond_to?(:each_task)
+        if recurse
+          block.yield(flow)
+          flow.each_task() do |task|
+            _walk(task, true, listener, &block)
+          end
+        else
+          flow.each_task() do |task|
+            block.yield(task)
+          end
+        end
+      else
+        block.yield(flow)
+      end
+    end
+
+    class TaskStat
+      attr_reader :task
+      attr_reader :queued
+      attr_reader :activity
+      attr_reader :name
+      attr_reader :proc_cnt
+      attr_reader :count
+      attr_reader :state
+
+      STATE_MAP = {
+        Task::STARTING => '^',
+        Task::STOPPED => '*',
+        Task::RUNNING => ' ',
+        Task::CLOSING => 'X',
+        Task::BLOCKED => '-',
+        Task::STEP => 's',
+      }
+      def initialize(t)
+        @task = t
+        @proc_cnt = t.proc_count()
+        @activity = 0
+        @queued = t.queue_count()
+        @name = t.full_name
+        @count = @proc_cnt.to_s
+        @state = STATE_MAP.fetch(t.state, '?')
+      end
+
+      def refresh()
+        cnt = @task.proc_count()
+        @activity = cnt - @proc_cnt
+        @proc_cnt = cnt
+        @queued = @task.queue_count()
+        @count = cnt.to_s
+        @state = STATE_MAP.fetch(@task.state, '?')
+      end
+
+    end # TaskStat
+
+  end # Inspector
+end # OFlow