tap 0.7.9

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2006-2007, Regents of the University of Colorado.
+Developer:: Simon Chiang, Biomolecular Structure Program
+Support:: UCHSC School of Medicine Deans Academic Enrichment Fund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this
+software and associated documentation files (the "Software"), to deal in the Software
+without restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
+to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,71 @@
+= Tap
+
+Task Application: A framework for configurable, file based, web ready workflow applications.
+
+== Description
+
+Tap fundamentally is a basic workflow engine wherein you can define tasks and rules to pass
+outputs from one task into another.  Tap uses a standardized folder layout to assist in 
+configuring tasks and managing files.  
+
+Tap can be run from the console or from an integrated web server built on the camping[link to camping]
+framework.  The Tap Server makes it easy to build tools and share them within an organization,
+or with a wider audience as you please.
+
+== Info 
+
+Copyright (c) 2006-2007, Regents of the University of Colorado.
+Developer:: Simon Chiang, Biomolecular Structure Program
+Support:: UCHSC School of Medicine Deans Academic Enrichment Fund
+Licence:: MIT-Style
+
+== Installation
+
+Tap is available as a gem on RubyForge[http://rubyforge.org/projects/tap].  Use:
+
+  % gem install tap
+  
+In addition, Tap may be installed through a {Firefox Add-On}[http://prosperity.uchsc.edu/tap/addon].  
+The Tap add-on provides shortcuts for starting and running Tap in a console or as a server.  
+
+== Usage
+
+Begin by creating a Tap folder:
+
+  % tap --generate root path/to/folder
+  
+This command generates the standard file structure for Tap, including folders for 
+configurations, data, task libraries, documentation, and testing.  Navigate into your
+folder and generate a task:
+
+  % tap --generate task say_hello
+  
+The task generator makes a stub configuration file, task, and test.  Open up each file to 
+see the basics of task creation.  Everthing is set up for the test run, so give it a go:
+
+  % tap say_hello "from me"
+  # => I[hh::mm::ss]       message hello from me!
+
+You can start an IRB session to interact with your tap tasks...
+
+  % tap --console
+  > Tap::App.run(:say_hello, "from me")
+  # => I[hh::mm::ss]       message hello from me!
+  
+Or start the server...
+
+  % tap --server
+  
+Now you can go to {http://localhost:3000/tap}[http://localhost:3000/tap] to see your
+Tap Server in action.
+
+== Auditing
+== Notes
+
+Tap takes a simplified approach to workflows where the idea is to setup 
+tasks, their configs, conditions, and on_complete behavior before running,
+and then to let the application act out this predefined logic.  Changing 
+task setup during execution can naturally cause unexpected behavior.  
+Various safeguards should let you get away with this inadvisable practice,
+but on the other hand you may just thread lock the whole caboodle.
+

data/Rakefile

@@ -0,0 +1,117 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+desc 'Default: Run tests.'
+task :default => :test
+
+desc 'Run tests.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = File.join('test', ENV['subset'] || '', ENV['pattern'] || '**/*_test.rb')
+  t.verbose = true
+  t.warning = true
+end
+
+desc 'Generate documentation.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'tap'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README', 'MIT-LICENSE')
+  rdoc.rdoc_files.include('lib/tap/**/*.rb')
+end
+
+#
+# Gem specification
+#
+require './lib/tap/version.rb'
+
+Gem::manage_gems
+
+spec = Gem::Specification.new do |s|
+	s.name = "tap"
+	s.version = Tap::VERSION
+	s.author = "Simon Chiang"
+	s.email = "simon.chiang@uchsc.edu"
+	s.homepage = "http://rubyforge.org/projects/tap/"
+	s.platform = Gem::Platform::RUBY
+	s.summary = "Framework for configurable, file-based applications."
+	s.files = Dir.glob("{bin,test,lib}/**/*") + ["MIT-LICENSE", "README", "Rakefile"]
+	s.require_path = "lib"
+	s.autorequire = "tap"
+	s.test_file = "test/tap_test_suite.rb"
+	s.bindir = "bin"
+	s.executables = ["tap"]
+  s.default_executable = "tap"
+  
+	s.has_rdoc = true
+  s.rdoc_options << '--title' << 'Tap - Task Application' << '--main' << 'README' 
+	s.extra_rdoc_files = ["README", "MIT-LICENSE"]
+  s.add_dependency("rails", ">= 1.2.3")  # only for generators?
+  s.add_dependency("activesupport", ">=1.4.2")
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+	pkg.need_tar = true
+end
+
+#
+# Hoe tasks
+#
+
+desc 'Install the package as a gem'
+task :install_gem => [:package] do
+#task :install_gem => [:clean, :package] do
+  sh "#{'sudo ' unless WINDOZE}gem install pkg/*.gem"
+end
+
+desc "Publish RDoc to RubyForge"
+task :publish_docs => [:clean, :docs] do
+  config = YAML.load(File.read(File.expand_path("~/.rubyforge/user-config.yml")))
+  host = "#{config["username"]}@rubyforge.org"
+
+  remote_dir = "/var/www/gforge-projects/#{rubyforge_name}/#{remote_rdoc_dir}"
+  local_dir = 'doc'
+
+  sh %{rsync #{rsync_args} #{local_dir}/ #{host}:#{remote_dir}}
+end
+
+desc 'Package and upload the release to rubyforge.'
+task :release => [:package] do |t|
+  require 'rubyforge'
+  
+#task :release => [:clean, :package] do |t|
+  v = ENV["VERSION"] or abort "Must supply VERSION=x.y.z"
+  abort "Versions don't match #{v} vs #{spec.version}" if v != spec.version.to_s
+  pkg = "pkg/#{spec.name}-#{spec.version}"
+
+  if $DEBUG then
+    puts "release_id = rf.add_release #{rubyforge_name.inspect}, #{name.inspect}, #{version.inspect}, \"#{pkg}.tgz\""
+    puts "rf.add_file #{rubyforge_name.inspect}, #{name.inspect}, release_id, \"#{pkg}.gem\""
+  end
+
+  rf = RubyForge.new
+  puts "Logging in"
+  rf.login
+
+  c = rf.userconfig
+  c["release_notes"] = description if description
+  c["release_changes"] = changes if changes
+  c["preformatted"] = true
+
+  #files = [(@need_tar ? "#{pkg}.tgz" : nil),
+  #         (@need_zip ? "#{pkg}.zip" : nil),
+  #         "#{pkg}.gem"].compact
+  
+  files = "#{pkg}.gem"
+  
+  puts "Releasing #{name} v. #{version}"
+  rf.add_release rubyforge_name, name, version, *files
+end
+
+desc 'Show information about the gem.'
+task :debug_gem do
+  puts spec.to_ruby
+end

data/bin/tap

@@ -0,0 +1,63 @@
+#require 'rdoc/usage'
+#require 'getoptlong'
+
+# add options as needed
+#opts = GetoptLong.new(
+#  [ '--help', '-h', GetoptLong::NO_ARGUMENT ])
+#  opts.each do |opt, arg|
+#    case opt
+#    when '--help' then nil
+#    end
+#  end
+
+lib_dir = File.join( File.dirname(__FILE__), "../lib/")
+require lib_dir + "tap.rb"
+
+# configure the app to app.yml if it exists
+if File.exists?("app.yml")
+  config = ERB.new( File.read("app.yml") ).result
+  config = YAML.load(config)
+  Tap::App.instance.reconfigure(config) if config
+end
+
+begin
+  command = ARGV.shift
+  case command  
+  when "help", "?", nil 
+    puts "usage: tap <command> [options] [args]"
+    puts "available commands:"
+    
+    commands = Tap::App.instance.glob(:script).collect do |script|
+      next unless File.extname(script) == ".rb" 
+      Tap::App.instance.relative_filepath(:script, script).chomp(".rb")
+    end
+    Tap::App.glob(lib_dir + "tap/script/**/*").each do |script|
+      next unless File.extname(script) == ".rb" 
+      command = Tap::App.relative_filepath(lib_dir + "tap/script", script).chomp(".rb")
+      commands << command unless commands.include?(command)
+    end
+    
+    print "  "
+    puts commands.sort.join("\n  ")
+    puts
+    
+  else
+    app_script_filepath = Tap::App.instance.filepath(:script, command + ".rb")
+    tap_script_filepath = lib_dir + "tap/script/#{command}.rb"
+
+    if File.exists?(app_script_filepath)
+      load app_script_filepath
+    elsif File.exists?(tap_script_filepath)
+      load tap_script_filepath
+    else
+      raise "Unknown command: '#{command}'"
+    end
+  end
+rescue
+  if Tap::App.instance.options.debug
+    raise 
+  else
+    puts $!.message
+    puts "Type 'tap help' for usage information."
+  end
+end

data/lib/tap.rb

@@ -0,0 +1,15 @@
+require 'active_support'
+
+$:.unshift File.dirname(__FILE__)
+
+require 'tap/version'
+require 'tap/root'
+require 'tap/app'
+require 'tap/task'
+require 'tap/workflow'
+require 'tap/file_task'
+require 'tap/support/audit'
+require 'tap/support/logger'
+require 'tap/support/templater'
+require 'tap/support/batch_queue'
+require 'tap/support/run_error'

data/lib/tap/app.rb

@@ -0,0 +1,739 @@
+require 'yaml'
+require 'logger'
+require 'ostruct'
+require 'getoptlong'
+require 'monitor'
+require 'thread'
+require 'thwait'
+require 'erb'
+
+module Tap
+  
+  # == Overview
+  #
+  # App coordinates the setup and running of tasks, and provides an interface 
+  # to the application directory structure.  App is convenient for use within 
+  # scripts, and can be extended with various modules to provide command line
+  # utilites or to be integrated within a tap server.  
+  #
+  # All tasks have an App (by default App.instance) which helps set the task 
+  # up by loading configuration templates from the application directory, and
+  # to which all queue commands are issued.  Tasks also access application-
+  # wide resources like the logger and various options through App.
+  #
+  #   task = Task.new {|task, input| input += 1 }
+  #   task.app             # => App.instance
+  #   task.queue 1,2,3
+  #
+  #   app.run      
+  #
+  #   task.outputs.collect do |audit| 
+  #     audit._current
+  #   end                 # => [2,3,4]
+  #
+  # === Running Tasks
+  #
+  # Tasks are run in the order they are originally queued.  Batched tasks are
+  # all queued at the same time and therefore will execute in succession.  
+  # Multithreaded tasks execute cosynchronously, each on their own thread.
+  #
+  # Workflows can be achieved by setting the condition and on_complete blocks
+  # for a task.  Tasks are skipped in the queue until the condition block is
+  # met with the currently queued inputs.  When a task finishes, it will
+  # execute the on_complete block where results can be dispacted to other
+  # tasks, and these tasks queued for execution.  
+  #
+  # In this system, the workflow logic exists among the tasks. App keeps on 
+  # running as long as it finds executable tasks in the queue.  
+  #
+  # === Error Handling
+  #
+  # When unhandled errors arise during a run, App enters a termination (rescue) 
+  # routine.  During termination a TerminationError is raised for each executing 
+  # task so that the task immediately exits, or begins executing its internal 
+  # error handling code (perhaps performing rollbacks).
+  #
+  # Additional errors that arise during termination are collected and packaged 
+  # with the orignal error into a RunError.  By default all errors are logged
+  # and the run exits.  If options.debug == true, then the RunError will be raised
+  # for further handling.
+  #
+  # Note: the task that caused the original unhandled error is no longer executing 
+  # when termination begins and thus will not recieve a TerminationError.  
+  #
+  class App < Root
+    include MonitorMixin
+    
+    class << self
+      attr_writer :instance
+      
+      # Returns the current instance of App.  If no instance has been set,
+      # then a new App with the default configuration will be initialized
+      # to instance. 
+      def instance
+        @instance ||= App.new
+      end
+      
+      # Runs the specified task and inputs with the current instance.
+      def run(task, *inputs)
+        instance.run(task, *inputs)
+      end
+      
+      # Parses the input argument as YAML, if arg is a string that matches
+      # the YAML document specifier (ie it begins with "---\n").  Otherwise
+      # returns the argument.
+      def parse_yaml(arg)
+        arg =~ /^---\s*\n/ ? YAML.load(arg) : arg
+      end
+      
+      def read_erb_yaml(filepath)
+        return nil unless File.exists?(filepath)
+        
+        input = File.read(filepath)
+        input = ERB.new(input).result 
+        YAML.load(input)
+      end
+      
+      def make_config(task, config, version=nil)
+        
+      end
+    end
+    
+    attr_reader :options, :logger, :queue, :state
+    attr_accessor :map
+    
+    module State
+      READY = 0
+      RUN = 1
+      STOP = 2
+      TERMINATE = 3
+    end  
+    
+    DEFAULT_MAX_THREADS = 10
+
+    # Creates a new App with the given configuration.  See reconfigure for
+    # configuration options.
+    def initialize(config={})
+      super()
+      
+      @queue = Support::BatchQueue.new
+      @threads = []
+      @thread_queue = nil
+      @main_thread = nil
+      @state = State::READY
+   
+      # defaults must be provided for options and logging to ensure
+      # that they will be initialized by reconfigure 
+      self.reconfigure( {
+        :options => {}, :logger => {}, :map => {},
+      }.merge(config) )
+    end
+     
+    # Returns the current configuration for the App.  
+    def config
+      {:root => self.root,
+      :directories => self.directories,
+      :absolute_paths => self.absolute_paths,
+      :options => self.options.marshal_dump,
+      :logger => {
+        :device => self.logger.logdev.dev,
+        :level => self.logger.level,
+        :datetime_format => self.logger.datetime_format},
+      :load_paths => self.load_paths}      
+    end
+    
+    # Reconfigures App with the input configurations; other configurations are not affected.
+    #
+    # Available configurations:
+    # root:: resets the root directory of the app using root=
+    # directories:: resets the app directories using directories= (note ALL direcotries 
+    #               are reset. use app[dir]= to set a single directory)
+    # options:: resets the application options (note ALL options are reset.  use 
+    #           app.options.opt= to set a single option)
+    # logger:: creates and sets a new logger from the configuration 
+    #
+    # Available logger configurations and defaults:
+    # device:: STDOUT
+    # level:: INFO (1) 
+    # datetime_format:: %H:%M:%S
+    #
+    # Notes:
+    # - Unknown configurations raise an error.  
+    # - Additional configurations may be added in subclasses using handle_configuration
+    def reconfigure(config={})
+      config = config.symbolize_keys
+      
+      # ensure critical keys are evaluated in the proper order
+      keys = [:root, :directories, :absolute_paths, :options, :load_paths, :loadable]
+      config.keys.each do |key|
+        keys << key unless keys.include?(key)
+      end 
+      
+      keys.each do |key|
+        next unless config.has_key?(key)
+        value = config[key]
+        
+        case key
+        when :root
+          self.root = value
+        when :directories 
+          self.directories = value
+        when :absolute_paths 
+          self.absolute_paths = value
+        when :options
+          @options = OpenStruct.new
+          value.each_pair {|k,v| options.send("#{k}=", v) }
+        when :logger
+          log_config = {
+            :device => STDOUT,
+            :level => 'INFO',
+            :datetime_format => '%H:%M:%S'
+          }.merge(value.symbolize_keys)
+
+          logger = Logger.new(log_config[:device]) 
+          logger.level = log_config[:level].kind_of?(String) ? Logger.const_get(log_config[:level]) : log_config[:level]
+          logger.datetime_format = log_config[:datetime_format]    
+          self.logger = logger
+        when :map
+          self.map = value
+        when :load_paths
+          self.load_paths = value
+        when :loadable
+          value.each {|dir| self.load_paths << self[dir]}
+        else
+          raise "Unknown configuration: #{key}" unless handle_configuation(key, value)
+        end
+      end
+    end
+    
+    #
+    # Dependencies and reloading
+    #
+    
+    def load_paths
+      Dependencies.load_paths
+    end
+    
+    def load_paths=(paths)
+      Dependencies.load_paths = paths
+    end
+    
+    def reload
+      # TODO - logging, maybe through Dependencies as
+      # RAILS_DEFAULT_LOGGER = logger  (problem with this during server?)
+      # Dependencies.log_activity = true
+      Dependencies.clear
+    end
+    
+    #
+    # Logging methods
+    #
+    
+    # Sets the current logger.  The logger is extended with Support::Logger to provide 
+    # additional logging capabilities.
+    def logger=(logger)
+      @logger = logger
+      @logger.extend Support::Logger unless @logger.nil?
+      @logger
+    end
+    
+    # Logs the action and message at the input level (default INFO).  
+    # Logging is suppressed if app.options.quiet
+    def log(action, msg="", level=Logger::INFO)
+      logger.add(level, msg, action.to_s) unless options.quiet
+    end
+    
+    def monitor(action="beginning", msg="", &block)
+      if options.quiet  
+        yield 
+        nil
+      else 
+        @monitoring = true
+        result = logger.monitor(action, msg, &block)
+        @monitoring = false
+        result
+      end
+    end
+    
+    def tick_monitor(action=nil, msg="", level=Logger::INFO)
+      unless options.quiet || !@monitoring
+        action.nil? ? 
+          logger.tick :
+          logger.format_add(level, msg, action.to_s) {|format| "\n" + format}
+      end
+    end
+    
+    def monitor_stats(hash)
+      unless options.quiet || !@monitoring
+        logger << "\n"
+        logger << hash.stringify_keys.to_yaml
+      end
+    end
+ 
+    #
+    # Task methods
+    #
+    
+    # Returns the specifed task, reconfigured with config (if provided). 
+    #
+    #   t = Task.new :key => 'value'
+    #   t = app.task(t, :key => 'another')
+    #   t.config[:key]      # => 'another'
+    #
+    # If a task name is given, then the appropriate class will be loaded and 
+    # instantiated into a task with given name.  The class is the de-versioned
+    # and camelized name, or the class as specified in map.
+    #
+    #   app.map             # => {"mapped-task" => "Task"}
+    #
+    #   t = app.task('mapped-task-1.0', :key => 'value')
+    #   t.class             # => Task
+    #   t.name              # => "mapped-task-1.0"
+    #   t.config[:key]      # => 'value'
+    #
+    def task(td, config=nil)
+      t = if td.kind_of?(Tap::Task) 
+        td 
+      else 
+        # lookup the corresponding class and instantiate
+        constants = task_class_name(td).split('::')
+        task_class = constants.inject(Object) do |klass, const| 
+          begin
+            klass.const_get(const)
+          rescue(NameError)
+            raise "unknown task '#{td}'"
+          end 
+        end
+        task_class.new(td)
+      end
+      
+      # reconfigure if a config is provided
+      t.config = config unless config.nil?
+      t
+    end
+    
+    def task_class_name(td)
+      case td
+      when Tap::Task then td.class.to_s
+      else
+        # de-version and resolve using map
+        name, version = deversion(td)
+        map.has_key?(name) ? map[name] : name.camelize
+      end
+    end
+    
+    # Creates and returns an array of configuration templates for the specified file.
+    # To make templates, the contents of the file are processed using ERB, then
+    # loaded as YAML and assembled into an array of hashes. 
+    #
+    #   # simple.yml => "key: value"
+    #   app.config_templates("simple.yml")  # => [{"key" => "value"}]
+    #
+    #   # array_with_erb.yml => %Q{ 
+    #   #   - key: <%= 1 %>
+    #   #   - key: <%= 1 + 1 %>}
+    #   app.config_templates("array_with_erb.yml")  # => [{"key" => 1}, {"key" => 2}]
+    #
+    # If no config templates are loaded (as when the filepath does not exist, or the
+    # file is empty), then the return will be a single empty template -- [{}].
+    def config_templates(filepath)
+      config_templates = App.read_erb_yaml(filepath)
+      
+      config_templates = case config_templates
+      when Array then config_templates
+      when Hash then [config_templates]
+      else
+        return [{}]
+      end
+      
+      config_templates      
+    end
+    
+    #
+    # Execution methods
+    #
+
+    # Dequeues the task and inputs and executes the task with the current task inputs.
+    # Only the provided task will be executed (ie the task batch will not be executed)
+    # and execution is on the current thread even if the task is multithreaded.  
+    #
+    # execute can only run if the application state is READY or RUN, and does not
+    # perform any error handling
+    def execute(task)
+      synchronize do
+        #log(:execute, task.to_dir, Logger::DEBUG) if options.debug
+  
+        unless state == State::READY || state == State::RUN
+          raise "cannot execute unless application state is READY or RUN" 
+        end
+     
+        if deq = queue.deq(task)
+          task, inputs = deq
+          task.execute(*inputs)
+        end
+      end
+    end
+
+    # Enqueues the task and inputs (if provided), then iterates through the queue  
+    # executing tasks using this execution cycle:
+    #  
+    #   for each enqueued task:
+    #     next unless executable?(task)
+    #   
+    #     dequeue task and inputs
+    #     if multithreading is allowed and task.multithread?
+    #       execute task on a thread
+    #     else
+    #       execute task
+    #
+    # At the end of run, the queue may still contain unexecuted tasks.  These
+    # tasks require additional inputs or conditions in order to execute. Tasks
+    # may be specified as a descriptor (ex: "some/task" => SomeTask.new) or
+    # as the task itself; run returns the specified task on completion.
+    def run(td=nil, *inputs)
+      synchronize do
+        # TODO: log starting run
+        
+        # lookup and enqueue the task, if provided
+        specified_task = task(td) if td
+        queue.enq(specified_task, *inputs) if specified_task
+
+        # generate threading variables
+        self.state = State::RUN
+        self.main_thread = Thread.current
+        max_threads = options.max_threads || DEFAULT_MAX_THREADS
+        self.thread_queue = max_threads > 0 ? Queue.new : nil
+        
+        begin 
+          execution_loop do 
+            task, inputs = queue.deq
+            
+            # if no tasks were in the queue 
+            # then clear the threads and 
+            # check for tasks again
+            unless task 
+              clear_threads
+              task, inputs = queue.deq
+            end
+            
+            # break -- no executable task was found
+            break if task.nil?
+
+            if thread_queue && task.multithread?
+              # TODO: log enqueuing task to thread
+              
+              # generate threads as needed and allowed
+              # to execute the threads in the thread queue
+              start_thread if threads.size < max_threads 
+
+              # NOTE: the producer-consumer relationship of execution
+              # threads and the thread_queue means that tasks will sit
+              # waiting until an execution thread opens up.  in the most
+              # extreme case all executing tasks and all tasks in the 
+              # task_queue could be the same task, each with different
+              # inputs.  this deviates from the idea of batch processing,
+              # but should be rare and not at all fatal given execute
+              # synchronization.  
+              thread_queue.enq [task, inputs]
+            
+            else
+              # TODO: log execute task
+              
+              # wait for threads to complete
+              # before executing the main thread
+              clear_threads
+              task.execute(*inputs)
+            end
+          end
+          
+          # if the run loop exited due to a STOP state,
+          # tasks may still be in the thread queue and/or
+          # running.  be sure these are cleared
+          if state == State::STOP
+            clear_thread_queue 
+            clear_threads 
+          end
+          
+        rescue
+          # when an error is generated, be sure to terminate
+          # all threads so they can clean up after themselves.
+          # clear the thread queue first so no more tasks are
+          # executed. collect any errors that arise during
+          # termination. 
+          clear_thread_queue
+          errors = terminate_threads
+
+          # handle the errors accordingly
+          if options.debug
+            raise Tap::Support::RunError.new($!, errors)
+          else
+            log($!.class, $!.message)
+            errors.each_with_index do |err, index|
+              next if err.nil?
+              log("[#{index}] #{err.class}", err.message)
+            end
+          end
+        end
+        
+        # reset run variables
+        self.thread_queue = nil
+        self.main_thread = nil
+        self.state = State::READY
+        
+        # TODO: log run complete
+        
+        specified_task
+      end
+    end
+    
+    # Signals a running application to stop executing tasks in the 
+    # queue by setting state = State::STOP.  Currently executing 
+    # tasks will continue their execution uninterrupted.
+    #
+    # Does nothing unless state is State::RUN.
+    def stop
+      self.state = State::STOP if state == State::RUN
+    end
+
+    # Terminates a running application by raising an error on the
+    # main execution thread which enters the application into a 
+    # terminate (rescue) mode.  By default the error will be a 
+    # TerminateError, but another error can be provided as cause
+    # for the termination.  The application state is set to 
+    # State::TERMINATE.
+    #
+    # Termination in this way allows executing tasks to invoke
+    # their specific error handling code, perhaps performing 
+    # rollbacks.  (ie terminate should be used as a graceful
+    # exit)
+    #
+    # Does nothing unless state is State::RUN or State::STOP.
+    def terminate(error=TerminateError.new)
+      if state == State::RUN || state == State::STOP
+        self.state = State::TERMINATE
+        
+        # the terminate error must be raised on the main thread
+        # so that the App will enter the termination (rescue) block
+        main_thread.raise(error)
+      end
+    end
+    
+    # Returns an information string for the App.  
+    #
+    #   App.new().info   # => 'state: 0 (READY) queue: 0 waiting: 0 (0) threads: 0'
+    #
+    # Provided information:
+    #
+    # state:: the integer and string values of the application state
+    # queue:: the number of tasks currently in the queue
+    # waiting:: the number of executable tasks in the queue, in parenthesis is the
+    #           number of objects in the thread queue (tasks, and perhaps nils to 
+    #           signal threads to clear)
+    # threads:: the number of execution threads
+    #
+    def info
+      state_str = State.constants.inject(nil) {|str, s| State.const_get(s) == state ? s : str}
+      "state: #{state} (#{state_str}) queue: #{queue.size} waiting: #{queue.num_executable} (#{thread_queue ? thread_queue.size : 0}) threads: #{threads.size}"
+    end
+    
+    #
+    # workflow related
+    #
+    
+    # Sets the condition block for the task.  If the task is batched, 
+    # then the condition will be set for each task in the batch.
+    def condition(task, &block) # :yields: task, inputs
+      task.batch.each {|t| t.condition(&block)}
+    end
+    
+    # Sets the on_complete block for the task.  If the task is batched, 
+    # then on_complete will be set for each task in the batch.
+    def on_complete(task, &block) # :yields: results
+      task.batch.each {|t| t.on_complete(&block)}
+    end
+    
+    # Sets multithread=true for each input task.  Batched tasks will
+    # have each task in the batch multithreaded.
+    def multithread(*tasks)
+      tasks.each do |task| 
+        task.batch.each {|t| t.multithread = true}
+      end
+    end
+    
+    # Sets a sequence workflow pattern for the tasks such that the
+    # completion of a task enqueues the next task with it's results.
+    # The condition block between these tasks will be set to the 
+    # input block, if provided.  Batched tasks will have the pattern 
+    # set for each task in the batch.
+    def sequence(*tasks, &block) # :yields: task, inputs
+      tasks.collect! {|td| task(td)}
+      current_task = tasks.shift
+      
+      tasks.each do |next_task|
+        # simply pass results from one task to the next.  
+        on_complete(current_task) {|results| queue.enq(next_task, *results) }
+        condition(next_task, &block)
+        current_task = next_task
+      end
+    end
+    
+    # Sets a fork workflow pattern for the tasks such that each of the
+    # targets will be enqueued with the results of the source when the
+    # source completes.  The condition block for the targets will 
+    # be set to the input block, if provided.  Batched tasks will have 
+    # the pattern set for each task in the batch.
+    def fork(source, *targets, &block) # :yields: task, inputs
+      on_complete(source) do |results|
+        targets.each do |target|
+          # forking requires new audit trails because the same 
+          # inputs are getting sent to multiple tasks
+          forked_results = results.collect {|result| result._fork }
+          queue.enq(target, *forked_results)
+        end
+      end
+      targets.each do |target|
+        condition(target, &block)
+      end if block_given?
+    end
+    
+    # Sets a merge workflow pattern for the tasks such that the results
+    # of each source will be enqueued to the target when the source 
+    # completes.  The condition block for the target will be set to the 
+    # input block, if provided.  Batched tasks will have the pattern set 
+    # for each task in the batch.
+    def merge(target, *sources, &block) # :yields: task, inputs
+      sources.each do |source|
+        # merging can use the existing audit trails... each distinct 
+        # input is getting sent to one place (the target)
+        on_complete(source) {|results| queue.enq(target, *results) }
+      end
+      condition(target, &block) if block_given?
+    end
+    
+    protected
+    
+    # A hook for handling unknown configurations in subclasses, called from
+    # reconfigure.  If handle_configuration evaluates to false, then reconfigure
+    # raises an error.
+    def handle_configuation(key, value)
+      false
+    end
+    
+    attr_writer :state
+    attr_accessor :thread_queue, :main_thread, :threads
+    
+    private
+    
+    def execution_loop
+      while true
+        case state
+        when State::STOP
+          break
+        when State::TERMINATE
+          # if an execution thread (main or multi) handles the
+          # termination error, then the thread may end up here --
+          # terminated but still running.  Raise another
+          # termination error to enter the termination 
+          # (rescue) code.
+          raise TerminateError.new
+        end
+        
+        yield
+      end
+    end
+
+    def clear_thread_queue
+      return unless thread_queue
+      
+      # clear the queue and enque the thread complete
+      # signals, so that the thread will exit normally
+      dequeued = []
+      while !thread_queue.empty?
+        dequeued << thread_queue.deq
+      end
+
+      # add dequeued tasks back, in order, to the task 
+      # queue so no tasks get lost due to the stop
+      #
+      # BUG: this will result in an already-newly-queued 
+      # task being promoted along with it's inputs
+      dequeued.reverse_each do |task, inputs|
+        # TODO: log about not executing
+        queue.priority_enq(task, *inputs) unless task.nil?
+      end
+    end
+  
+    def clear_threads
+      return if threads.empty?
+      
+      # clears threads gracefully by enqueuing nils, to break
+      # the threads out of their loops, then waiting for the
+      # threads to work through the queue to the nils
+      threads.size.times { thread_queue.enq nil }
+      ThreadsWait.all_waits(*threads) do |thread|
+        # TODO - log thread clear
+      end
+      threads.clear
+    end
+    
+    def start_thread
+      # start a new thread and add it to threads.
+      # threads simply loop and wait for a task to 
+      # be queued.  the thread will block until a 
+      # task is available (due to thread_queue.deq)
+      threads << Thread.new do 
+        # TODO - log thread start
+        
+        execution_loop do
+          task, inputs = thread_queue.deq
+          break if task.nil?
+           
+          # TODO: log execute task on thread #
+          begin
+            task.execute(*inputs)
+          rescue
+            # unless you're already terminating,
+            # an unhandled error should immediately
+            # terminate all threads
+            if state == State::TERMINATE
+              raise $!
+            else
+              terminate($!)
+            end
+          end
+        end 
+      end
+    end
+
+    def terminate_threads
+      # terminate each thread by raising an exception
+      # wait for the thread to exit and gather any
+      # errors that arise that are not from the 
+      # termination exception.
+      errors = []
+      threads.each_with_index do |thread, index|
+        next unless thread.alive?
+
+        begin
+          thread.raise TerminateError.new
+          thread.join
+        rescue TerminateError
+          # do not track these as errors 
+          # arising from termination
+        rescue
+          # track the thread of the error  
+          # with the error itself
+          errors[index] = $!
+        end
+      end
+      threads.clear
+    
+      errors
+    end
+    
+    # TerminateErrors are raised to kill executing tasks when terminate 
+    # is called on an running App.  
+    class TerminateError < RuntimeError
+    end
+  end
+end