rq-ruby1.8 3.4.3

data/Rakefile

@@ -0,0 +1,37 @@
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "rq-ruby1.8"
+  gem.homepage = "http://github.com/pjotrp/rq"
+  gem.license = "BSD"
+  gem.summary = %Q{Ruby Queue scheduler}
+  gem.description = %Q{Zero configuration job scheduler for computer clusters}
+  gem.email = "pjotr.public01@thebird.nl"
+  gem.authors = ["Pjotr Prins"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+task :default => :spec
+
+task :test do
+  Dir.chdir('test') do 
+    sh './test_rq.rb'
+  end
+end
+
+

data/TODO

@@ -0,0 +1,24 @@
+---
+
+- migrate to Ruby1.9 (problem is the posixlock module, depending on ruby1.8)
+- write some rspec cases
+- create gem in rubygems (for ruby1.9)
+
+- confine/constrain mechanism
+- heartbeat to slave
+- ls show elapsed time
+- rq q 1234 234 bug???
+- full boolean resource monitoring and resource requests
+- pull out some infilter/outfilter classes for all the stdin/stdout parsing
+- rq relay mode (submit and track exit_status in local db)
+- config file configuration for feeder 
+- examples dir with shell commands/scripts
+- db message queue to send commands to remote nodes - ttl issues here...
+- consider/test tracking feeders in queue rather than using lock on local file?
+- use nodes to periodically generate stats and cache them
+
+X rotation bug when dest directory specified
+X backoff lockd recovery time
+X output for start/stop (include shush)
+X .rq dir for everything (log, pidfile)
+X cronify

data/TUTORIAL

@@ -0,0 +1,230 @@
+---
+=== SYNOPSIS
+---
+
+rq is a tool for instantly building simple linux clusters based on the concept
+of coordinated shared access to an nfs mounted priority job queue.  the idea is
+a simple one: one, or more, nodes take jobs from a priority queue, run them, and
+return their status and other information to the queue.  the priority queue
+itself is made available to all the 'feeding' nodes by virtue of it being placed
+on a globally visible nfs filesystem.
+
+                          -----------
+                          | priority |
+                          | queue    |
+                          -----------
+                         /      |     \
+                        /       |      \
+                       --------nfs-------
+                      /         |        \
+                     /          |         \
+                ----------  ----------  ----------
+                | node_a |  | node_b |  | node_c |
+                ----------  ----------  ----------
+
+all feeding nodes are equal, idependent, and isolated.  any node capable of
+mounting the nfs filesystem may submit to the queue.  so long as the nfs server
+and one node are up - the cluster can continute processing jobs.
+
+
+---
+=== EXAMPLE INSTALL
+---
+
+download rq from http://raa.ruby-lang.org/project/rq
+
+unpack rq-X.X.X.tgz
+
+cd ./depends/
+
+the ./depends/packages/ directory will contain ALL packages required to install
+rq including ruby[www.ruby-lang.org]
+
+the file ./depends/install.sh installs ALL required packages for ruby queue into
+an nfs mounted directory.  it is a simple script - feel free to read/edit.
+
+installed packages will include:
+
+* ruby
+* sqlite
+* sqlite-ruby
+* arrayfields
+* posixlock
+* lockfile
+* rq
+
+the install.sh procedure is reccomended since
+
+* a common nfs filesystem is required on which to store the queue anyhow
+
+* installing all packages into this common nfs filesystem means no
+  software will be installed locally on any node which simplifies maintainance
+  and the addition of new nodes to the cluster.
+
+* root privledges are not required for this technique
+
+* this technique implies only two requirements for any node to join the cluster
+  * the nfs filesystem is visible to it
+  * a single crontab entry has been added
+
+the user running ./depends/install.sh should have write permission (or sudo
+write permission) to the /nfs mounted directory.
+
+following are the steps for an install into the nfs mounted directory named
+'/nfs'.  absolutely NO packages or files will be installed outside this hierachy
+so simply use 'rm -rf' to un-install.  
+  
+  tar xvfz rq-X.X.X.tgz
+
+  cd rq-X.X.X/
+
+  cd depends/
+
+  ./install.sh /nfs  
+
+---
+=== EXAMPLE SETUP
+---
+
+= path setup
+
+the following instructions assume your PATH has been set appropriately on all
+nodes.  your path should be configured to include the bin directory of the nfs
+prefix used in the install.  eg:
+
+  export PATH=/nfs/bin/:$PATH
+
+if this has been done correctly the output of
+
+  which rq
+
+should report something like
+
+  /nfs/bin/rq
+
+/nfs being the location you just installed into
+
+
+= create the queue
+
+you must create/initialize the queue structure.  this should be done one time
+only from any host
+
+  rq /nfs/queue create
+
+
+= configure immortal feeders on all processing nodes
+
+add crontab entries similar to below to keep immortal feeders alive on ALL
+nodes.  this will not start feeders every 15 mintues - it will only attempt to
+start one every 15 minutes, failing silently if one is already running.
+
+  */15 * * * * /nfs/bin/rq /nfs/queue start 
+
+obviously you will need to edit the path to rq, the path to the queue, and
+possibly the log path.
+
+this can done automatically simply by running
+
+  rq /nfs/queue cron start
+
+essentially the crontab entry simply ensures that a feeder daemon is running on
+a node at all times, even after a reboot.  a majority of the time the cron entry
+will do nothing - only when no daemon is running will it be able to generate a
+pidfile and lock it in order to start feeding.  one feeder per queue per host is
+allowed by default.
+
+if you are not quite ready to setup crontab entries on a dozen machines and want
+to start a feeder from a terminal for debugging/testing purposes you might use
+something like this in a separate terminal/host from the one you'll submit jobs
+from:
+
+  /nfs/bin/rq /nfs/queue feed --min_sleep=2 --max_sleep=4
+
+which will log all output to STDERR and poll at a random interval between
+--min_sleep and --max_sleep.  a slight diversion is required here to explain
+min_sleep and max_sleep.
+
+once a feeder finds the queue to be empty it will begin polling the queue
+periodically to see if any new jobs have come in.  min_sleep and max_sleep
+define the lower and upper bound of the polling interval, which is actually
+chosen at random to be between these two numbers for performance reasons.
+
+_never_ would you use the polling interval shown above (min_sleep=2,
+max_sleep=4) in a production environment, such a rapid interval would _only_ be
+for debugging/testing.  
+  
+as reference the defaults for min_sleep and max_sleep are 42 and 240
+respectively, and this gives good responsiveness on a cluster of 12-20 machines.
+you can determine how long a job would sit in the queue, on average, before
+being noticed (assuming all nodes are not busy when the job is submitted) using
+this formula
+
+  median_sleep = ((max_sleep - min_sleep) / 2) + min_sleep
+
+  wait = n_nodes / median_sleep
+
+so, for example, if you use the default min_sleep and max_sleep for 10 feeding
+nodes a job would sit in the queue for, on average, about 10 seconds before
+being picked up.  
+
+it's very important to note all this talk of polling applies _only_ to nodes
+which have found the queue emtpy and are checking back at a regular interval to
+look for more work.  while the queue is full of jobs each node simply works to
+capacity to take jobs, runs them, and return them to the queue - so there is no
+polling.  in fact, it's best to consider the min_sleep and max_sleep options as
+affecting how quickly the cluster as a whole will tackle a freshly loaded queue:
+once the queue is loaded every node is 'too busy' to poll any longer.
+
+one other option which should be mentioned here is the --max_feed, -f option.
+this option simply determines the number of concurrent jobs rq will run at once.
+the default value is 2 - therefore two jobs will be running simoultaneously on
+each feeding node when the queue has been loaded with jobs.  this command
+
+  /nfs/bin/rq /nfs/queue feed --min_sleep=2 --max_sleep=4 --max_feed=1
+
+might be used in a terminal (logging to stderr) to watch rq in action.  limiting
+the number of feeders to 1 makes the output somewhat easier to understand.
+however, unless your machines cannot handle more than one of the jobs you plan
+to submit it's best to keep this number > 1 for production clusters.
+
+
+---
+=== EXAMPLE USAGE
+---
+
+
+= job submission
+
+submit a command line job to the nfs mounted queue
+
+  rq /nfs/queue submit 'echo 42'
+
+in this case the quoting is not needing but beware of shell expansion when
+submitting jobs from the shell
+
+submit a list of jobs from 'jobfile'.  jobfile is simply a text file with one
+command per line.  blank lines and comments (#) are ignored.
+
+  rq /nfs/queue submit - < jobfile 
+
+= cluster status
+
+check the status of your jobs (note that it may take cron a while to start
+feeders depending on the interval used to maintain them in your crontab file)
+
+  rq /nfs/queue status 
+
+= where to go from here
+
+for more info try
+
+  rq help
+
+
+---
+=== AUTHOR/ASSISTANCE/BUG REPORTS
+---
+
+  ara.t.howard@noaa.gov
+

data/VERSION

@@ -0,0 +1 @@
+3.4.3

data/bin/rq

@@ -0,0 +1,902 @@
+#!/usr/bin/env ruby1.8
+
+$: << '/var/lib/gems/1.8/gems/rq-ruby1.8-3.4.3/lib'  # locate gem1.8 install
+$: << '/usr/share/rq-ruby1.8/lib'
+
+# 
+# === the rq program
+# 
+# the rq program is the single command line interface by which all queue
+# operations are affected.  it always takes, as it's first argument, the name of
+# the queue to be operated on.  the second argument is always the mode of
+# operation.  the action taken and meaning of subsequent arguments depends
+# directory on the mode of operation.  for example the command
+# 
+#   rq queue create
+# 
+# has the the mode _create_ and will create the queue _queue_.  similarly the
+# command 
+# 
+#   rq queue submit my_job.sh huge_input_file.dat 
+# 
+# runs in _submit_ mode and will sumbit a job to _queue_.
+# 
+# run 
+# 
+#   rq --help
+# 
+# or see README
+# 
+# for the detailed instructions for each of the operation modes 
+# 
+
+  begin
+    require 'rq'
+  rescue LoadError
+    # a guess really...
+    libdir = File.join(File.dirname(File.dirname(__FILE__)), 'lib')
+    require File.join(libdir, 'rq')
+  end
+  module RQ
+  #
+  # the Main class is responsible for parsing command line paramters and
+  # switches, doing some validation, initializing logging, and, ultimately,
+  # delegating the bulk of the work to a MainHelper based on the _mode_ given.
+  # the relationship between Main and MainHelper is a tight one by design - the
+  # primary purpose of it being to prevent the Main class from becoming 10000
+  # lines long.  the delegators used include:
+  #
+  # * Creator
+  # * Submitter 
+  # * Lister 
+  # * StatusLister 
+  # * Deleter 
+  # * Updater 
+  # * Querier 
+  # * Executor 
+  # * Configurator 
+  # * Snapshotter 
+  # * Locker 
+  # * Backer 
+  # * Rotater 
+  # * Feeder 
+  # * IOViewer
+  #
+    class Main
+#--{{{
+      include Util
+      include Logging
+      include Usage
+
+    # an enumeration of option specifications used to parse command line
+      OPTSPEC =
+#--{{{
+      [
+        [
+          '--priority=priority', '-p', 
+          'modes <submit, resubmit> : set the job(s) priority - lowest(0) .. highest(n) - (default 0)'
+        ],
+        [
+          '--tag=tag', '-t', 
+          'modes <submit, resubmit> : set the job(s) user data tag'
+        ],
+        [
+          '--runner=runner',
+          'modes <submit, resubmit> : set the job(s) required runner(s)'
+        ],
+        [
+          '--restartable',
+          'modes <submit, resubmit> : set the job(s) to be restartable on node reboot'
+        ],
+        [
+          '--stage',
+          'modes <submit, resubmit> : set the job(s) initial state to be holding (default pending)'
+        ],
+        [
+          '--infile=infile', '-i',
+          'modes <submit, resubmit> : infile'
+        ],
+        [
+          '--stdin=[stdin]', '-s',
+          'modes <submit, resubmit, update> : stdin'
+        ],
+        [
+          '--data=data', '-d',
+          'modes <submit, resubmit, update> : data'
+        ],
+
+        [
+          '--quiet', '-q',
+          'modes <submit, resubmit, feed> : do not echo submitted jobs, fail silently if
+          another process is already feeding'
+        ],
+        [
+          '--daemon', '-D',
+          'modes <feed> : spawn a daemon'
+        ],
+        [
+          '--max_feed=max_feed',
+          'modes <feed> : the maximum number of concurrent jobs run'
+        ],
+        [
+          '--retries=retries',
+          'modes <feed> : specify transaction retries'
+        ],
+        [
+          '--min_sleep=min_sleep',
+          'modes <feed> : specify min sleep'
+        ],
+        [
+          '--max_sleep=max_sleep',
+          'modes <feed> : specify max sleep'
+        ],
+        [
+          '--loops=loops', '-L', 
+          'modes <feed> : specify how many times to loop (default forever)'
+        ],
+        [
+          '--exit=exit_code_map',
+          'modes <status> : specify and exit code map'
+        ],
+        [
+          '--fields=fields', '-f',
+          'limit which fields of output to display'
+        ],
+        [
+          '--snapshot', '-s',
+          'operate on snapshot of queue'
+        ],
+        [
+          '--editor=editor', '-e',
+          'editor command capable of opening multiple files at once = (default ENV["RQ_EDITOR"] || "vim -R -o")'
+        ],
+        [
+          '--verbosity=[verbostiy]', '-v', 
+          '0|fatal < 1|error < 2|warn < 3|info < 4|debug - (default info)'
+        ],
+        [
+          '--log=path','-l', 
+          'set log file - (default stderr)'
+        ],
+        [
+          '--log_age=log_age',
+          'daily | weekly | monthly - what age will cause log rolling (default nil)'
+        ],
+        [
+          '--log_size=log_size',
+          'size in bytes - what size will cause log rolling (default nil)'
+        ],
+        [
+          '--dot_rq_dir=[dot_rq_dir]',
+          'base dir for log/pidfile storage (default ~/.rq/full/path/to/queue)'
+        ],
+#      [
+#        '--config=path',
+#        'valid path - specify config file (default nil)'
+#      ],
+#      [
+#        '--template=[path]',
+#        'valid path - generate a template config file in path (default stdout)'
+#      ],
+        [
+          '--help', '-h', 
+          'this message'
+        ],
+        [
+          '--version',
+          'show version number'
+        ],
+      ]
+#--}}}
+
+    # the default config file searched for has this basename
+      CONFIG_DEFAULT_PATH = 'rq.conf'
+
+    # config files are searched for using this list of locations
+      CONFIG_SEARCH_PATH = %w( . ~ /dmsp/reference/etc /usr/local/etc /usr/etc /etc ) 
+
+    # the queue can be specified in the environment
+      Q = ENV['RQ_Q'] || ENV['RQ_QUEUE']
+
+      attr :logger
+      attr :argv
+      attr :env
+      attr :program
+      attr :stdin
+      attr :job_stdin
+      attr :data
+      attr :cmd
+      attr :options
+      attr :qpath
+      attr :mode
+      attr :q
+      attr :daemon
+      attr :quiet
+      attr :loops
+      attr :fields
+      attr :dot_rq_dir
+
+      alias_method 'stdin?', 'stdin'
+      alias_method 'job_stdin?', 'job_stdin'
+      alias_method 'data?', 'data'
+      alias_method 'quiet?', 'quiet'
+
+    # given a command line and environment run the rq program
+      def initialize argv = ARGV, env = ENV
+#--{{{
+        begin
+          @logger = Logger::new STDERR
+          @argv = Util::mcp(argv.to_a)
+          @env = Util::mcp(env.to_hash)
+          @program = $0
+          @cmd = ([File::expand_path($0)] + ARGV).join(' ')
+          @stdin = parse_stdin
+
+          parse_options
+
+          if(@options.has_key?('name'))
+            $0 = ([@options['name']] + ARGV).join(' ')
+          end
+
+          if(@options.has_key?('help') or @argv.include?('help'))
+            usage('port' => STDOUT, 'long' => true)
+            exit EXIT_SUCCESS
+          end
+
+          if(@options.has_key?('template') or (idx = @argv.index('template')))
+            gen_template(@options['template'] || @argv[idx + 1])
+            exit EXIT_SUCCESS
+          end
+
+          if @options.has_key?('version')
+            puts RQ::VERSION
+            exit EXIT_SUCCESS
+          end
+
+          if(@options.has_key?('stdin'))
+            @options['stdin'] ||= '-'
+            @job_stdin = @options['stdin']
+          end
+
+          if(@options.has_key?('quiet'))
+            @quiet = true
+          end
+
+          if(@options.has_key?('fields'))
+            @fields = @options['fields'].split(%r/,/).map{|f| f.strip}
+            @fields.uniq!
+          end
+
+          if(@options.has_key?('loops'))
+            @loops = @options['loops']
+            @loops = Integer @loops if @loops
+          end
+
+          parse_argv
+
+          setup_dot_rq_dir
+
+          status = run
+
+          case status
+            when Integer
+              exit status
+            else
+              exit(status ? EXIT_SUCCESS : EXIT_FAILURE)
+          end
+        rescue => e
+          unless SystemExit === e
+            logerr e
+            exit EXIT_FAILURE
+          else
+            exit e.status 
+          end
+        end
+#--}}}
+      end
+    # extract command lines args
+      def parse_argv
+#--{{{
+        @qpath = Q || @argv.shift
+        @mode = @argv.shift
+#--}}}
+      end
+    # determine storage for logs/pidfiles
+      def setup_dot_rq_dir
+#--{{{
+        if(@options.has_key?('dot_rq_dir'))
+          @dot_rq_dir = @options['dot_rq_dir']
+        end
+        if @dot_rq_dir.nil?
+          home = ENV['HOME'] || File::expand_path('~') rescue abort("ENV['HOME'] is unset!")
+          @dot_rq_dir = File::join home, '.rq', @qpath
+        end
+        FileUtils.mkdir_p @dot_rq_dir
+#--}}}
+      end
+    # select a MainHelper based on mode and delegate to it
+      def run
+#--{{{
+        @qpath = Util::realpath @qpath
+
+        if @mode.nil? or @mode.strip.empty?
+          usage 'port' => STDERR, 'long' => false
+          exit EXIT_FAILURE
+        end
+
+        shortcuts = {
+          'c'  => 'create',
+          's'  => 'submit',
+          'r'  => 'resubmit',
+          're' => 'resubmit',
+          'l'  => 'list',
+          'ls' => 'list',
+          't'  => 'status',
+          'd'  => 'delete',
+          'rm' => 'delete',
+          'u'  => 'update',
+          'q'  => 'query',
+          'e'  => 'execute',
+          'C'  => 'configure',
+          'S'  => 'snapshot',
+          'L'  => 'lock',
+          'B'  => 'backup',
+          'R'  => 'rotate',
+          'h'  => 'help',
+          'H'  => 'help',
+          'f'  => 'feed',
+          'io' => 'ioview',
+          '0'  => 'stdin',
+          '1'  => 'stdout',
+          '2'  => 'stderr',
+          'to' => 'touch',
+          'ta' => 'tail',
+          'cron' => 'cron',
+        }
+
+        if((longmode = shortcuts[@mode]))
+          @mode = longmode
+        end
+
+        begin
+          case @mode
+            when 'create'
+              create
+            when 'submit'
+              submit
+            when 'resubmit'
+              resubmit
+            when 'list'
+              list
+            when 'status'
+              status
+            when 'delete'
+              delete
+            when 'update'
+              update
+            when 'query'
+              query
+            when 'execute'
+              execute
+            when 'configure'
+              configure
+            when 'snapshot'
+              snapshot
+            when 'lock'
+              lock
+            when 'backup'
+              backup
+            when 'rotate'
+              rotate
+            when 'help'
+              usage 'port' => STDOUT, 'long' => true
+              exit EXIT_SUCCESS
+            when 'feed'
+              feed
+            when 'start'
+              start
+            when 'shutdown'
+              shutdown
+            when 'stop'
+              stop
+            when 'restart'
+              restart
+            when 'pid'
+              pid
+            when 'feeder'
+              feeder
+            when 'recover'
+              recover
+            when 'ioview'
+              ioview
+            when 'stdin'
+              dump_stdin
+            when 'stdout'
+              dump_stdout
+            when 'stderr'
+              dump_stderr
+            when 'stdin4'
+              stdin4
+            when 'stdout4'
+              stdout4
+            when 'stderr4'
+              stderr4
+            when 'touch'
+              touch
+            when 'tail'
+              tail
+            when 'cron'
+              cron
+            when 'crontab'
+              crontab
+            else
+              raise "invalid mode <#{ @mode }>"
+          end
+          self
+        rescue Errno::EPIPE => e
+          raise if STDOUT.tty?
+        end
+
+        EXIT_SUCCESS
+#--}}}
+      end
+    # delegated to a Creator 
+      def create 
+#--{{{
+        init_logging
+        creator = Creator::new self
+        creator.create
+#--}}}
+      end
+    # delegated to a Submitter 
+      def submit 
+#--{{{
+        init_logging
+        submitter = Submitter::new self
+        submitter.submit
+#--}}}
+      end
+    # delegated to a ReSubmitter 
+      def resubmit 
+#--{{{
+        init_logging
+        resubmitter = ReSubmitter::new self
+        resubmitter.resubmit
+#--}}}
+      end
+    # delegated to a Lister 
+      def list 
+#--{{{
+        init_logging
+        @options['snapshot'] = true
+        lister = Lister::new self
+        lister.list
+#--}}}
+      end
+    # delegated to a StatusLister 
+      def status 
+#--{{{
+        init_logging
+        @options['snapshot'] = true
+        statuslister = StatusLister::new self
+        statuslister.statuslist
+#--}}}
+      end
+    # delegated to a Deleter 
+      def delete
+#--{{{
+        init_logging
+        deleter = Deleter::new self
+        deleter.delete
+#--}}}
+      end
+    # delegated to a Updater 
+      def update 
+#--{{{
+        init_logging
+        updater = Updater::new self
+        updater.update
+#--}}}
+      end
+    # delegated to a Querier 
+      def query
+#--{{{
+        init_logging
+        querier = Querier::new self
+        querier.query
+#--}}}
+      end
+    # delegated to a Executor 
+      def execute 
+#--{{{
+        init_logging
+        executor = Executor::new self
+        executor.execute
+#--}}}
+      end
+    # delegated to a Configurator 
+      def configure 
+#--{{{
+        init_logging
+        configurator = Configurator::new self
+        configurator.configure
+#--}}}
+      end
+    # delegated to a Snapshotter 
+      def snapshot
+#--{{{
+        init_logging
+        snapshotter = Snapshotter::new self
+        snapshotter.snapshot
+#--}}}
+      end
+    # delegated to a Locker 
+      def lock
+#--{{{
+        init_logging
+        locker = Locker::new self
+        locker.lock
+#--}}}
+      end
+    # delegated to a Backer 
+      def backup 
+#--{{{
+        init_logging
+        backer = Backer::new self
+        backer.backup
+#--}}}
+      end
+    # delegated to a Rotater 
+      def rotate 
+#--{{{
+        init_logging
+        rotater = Rotater::new self
+        rotater.rotate
+#--}}}
+      end
+    # delegated to a Feeder 
+      def feed 
+#--{{{
+        feeder = Feeder::new self
+        feeder.feed
+#--}}}
+      end
+    # quietly start a daemon process
+      def start
+#--{{{
+        unless exists 
+          @options['daemon'] = true
+          @options['quiet'] = true
+          @options['log'] ||= File.join(@dot_rq_dir, 'log')
+          feeder = Feeder::new self
+          feeder.feed
+        end
+#--}}}
+      end
+    # clean stop
+      def shutdown 
+#--{{{
+        pid = (exists and signal_feeder('TERM'))
+        puts "pid <#{ pid }> signaled to stop a.s.a.p" if pid
+        exit(Integer === pid ? 0 : 1)
+#--}}}
+      end
+    # hard stop
+      def stop
+#--{{{
+        pid = (exists and signal_feeder('KILL'))
+        puts "pid <#{ pid }> signaled to stop now" if pid
+        exit(Integer === pid ? 0 : 1)
+#--}}}
+      end
+    # sighup based restart
+      def restart 
+#--{{{
+        pid = (exists and signal_feeder('HUP'))
+        puts "pid <#{ pid }> signaled to restart" if pid
+        exit(Integer === pid ? 0 : 1)
+#--}}}
+      end
+    # is a feeder running?
+      def feeder
+#--{{{
+        arg = @argv.shift
+        case arg
+          when /pid/
+            pid
+          else
+            puts "---\nfeeder : #{ exists ? true : false }"
+        end
+#--}}}
+      end
+    # pid of any running feeder
+      def pid
+#--{{{
+        puts "---\npid : #{ exists || '~' }"
+#--}}}
+      end
+    # attempt sqlite db recovery
+      def recover
+#--{{{
+        init_logging
+        recoverer = Recoverer::new self
+        recoverer.recover
+#--}}}
+      end
+    # spawn external process to view stdin/stdout/stderr of jids
+      def ioview
+#--{{{
+        init_logging
+        ioviewer = IOViewer::new self
+        ioviewer.ioview
+#--}}}
+      end
+    # dump stdin for jid
+      def dump_stdin
+#--{{{
+        dump_ios 'stdin', jids4(@argv)
+#--}}}
+      end
+    # dump stdout for jid
+      def dump_stdout
+#--{{{
+        dump_ios 'stdout', jids4(@argv)
+#--}}}
+      end
+    # dump stderr for jid
+      def dump_stderr
+#--{{{
+        dump_ios 'stderr', jids4(@argv)
+#--}}}
+      end
+    # dump stdin path for jid
+      def stdin4 jids = nil 
+#--{{{
+        if jids
+          File.join @qpath, 'stdin', jids.to_s
+        else
+          jids = jids4 @argv
+          #STDOUT << "---\n"
+          jids.flatten.each do |jid|
+            iopath = File.join @qpath, 'stdin', jid.to_s
+            #STDOUT << " - " << iopath << "\n"
+            puts iopath
+          end
+        end
+#--}}}
+      end
+    # dump stdout path for jid
+      def stdout4 jids = nil 
+#--{{{
+        if jids
+          File.join @qpath, 'stdout', jids.to_s
+        else
+          jids = jids4 @argv
+          #STDOUT << "---\n"
+          jids.flatten.each do |jid|
+            iopath = File.join @qpath, 'stdout', jid.to_s
+            #STDOUT << " - " << iopath << "\n"
+            puts iopath
+          end
+        end
+#--}}}
+      end
+    # dump stderr path for jid
+      def stderr4 jids = nil 
+#--{{{
+        if jids
+          File.join @qpath, 'stderr', jids.to_s
+        else
+          jids = jids4 @argv
+          #STDOUT << "---\n"
+          jids.flatten.each do |jid|
+            iopath = File.join @qpath, 'stderr', jid.to_s
+            #STDOUT << " - " << iopath << "\n"
+            puts iopath
+          end
+        end
+#--}}}
+      end
+    # delegated to a Toucher 
+      def touch 
+#--{{{
+        init_logging
+        toucher = Toucher::new self
+        toucher.touch
+#--}}}
+      end
+    # spawn external process to tail stdin/stdout/stderr of jids
+      def tail
+#--{{{
+        @options['editor'] = 'tail -F'
+        init_logging
+        ioviewer = IOViewer::new self
+        ioviewer.ioview rescue nil
+#--}}}
+      end
+    # add/delete crontab entry
+      def cron
+#--{{{
+        init_logging
+        cron = Cron::new self
+        cron.cron
+#--}}}
+      end
+      def crontab
+#--{{{
+        argv.unshift 'tab'
+        init_logging
+        cron = Cron::new self
+        cron.cron
+#--}}}
+      end
+
+      def dump_ios which, jids
+#--{{{
+        jids.each do |jid|
+          iopath = send "#{ which }4", jid
+          begin
+            cat iopath
+          rescue
+            next
+          end
+        end
+#--}}}
+      end
+      def cat path
+#--{{{
+        system("cat #{ path } 2>/dev/null") or open(path){|f| f.each{|line| print line}}
+#--}}}
+      end
+      def jids4 *list 
+#--{{{
+        jids = list.flatten.map{|elem| Integer elem}
+        #@stdin.each{|line| line.strip!; next if line.empty?; jids << line} if @stdin
+        if @stdin
+          mainhelper = MainHelper.new(self)
+          jobs = []
+          mainhelper.loadio @stdin, 'stdin', jobs
+          jobs.each{|job| jids << job['jid']}
+          jids.map!{|jid| Integer(jid) rescue abort("bad jid <#{ jid.inspect }>")}
+        end
+        jids
+#--}}}
+      end
+
+      def exists 
+#--{{{
+        begin
+          signal_feeder 0
+        rescue Errno::ESRCH 
+          false
+        end
+#--}}}
+      end
+      def signal_feeder sig
+#--{{{
+        feeder = Feeder::new self
+        pidfilepath = feeder.gen_pidfilepath
+        pid = Integer(IO::read(pidfilepath)) rescue nil
+        begin
+          Process::kill(sig, pid)
+          pid
+        rescue
+          nil
+        end
+#--}}}
+      end
+    # parses '-' from cmdline, but not if it's after a '--'
+      def parse_stdin
+#--{{{
+        dash_dash, dash = %w( -- - ).map{|d| @argv.index d}
+        if dash
+          if dash_dash
+            if dash < dash_dash
+              @argv.delete '-'
+              STDIN
+            end
+          else
+            @argv.delete '-'
+            STDIN
+          end
+        end
+#--}}}
+      end
+    # uses OPTSPEC to parse command line switches
+      def parse_options
+#--{{{
+        @op = OptionParser.new
+        @options = {}
+        OPTSPEC.each do |spec|
+          k = spec.first.gsub(%r/(?:--)|(?:=.*$)|(?:\s+)/o,'')
+          @op.def_option(*spec){|v| v = v.to_s; @options[k] = v.empty? ? nil : v}
+          #@op.def_option(*spec){|v| @options[k] = v}
+        end
+
+        if((env_opts = (ENV['RQ_OPTS'] || ENV['RQ_OPTIONS'])))
+          require 'shellwords'
+          @op.parse! Shellwords.shellwords(env_opts)
+        end
+
+        @op.parse! @argv 
+
+        @options
+#--}}}
+      end
+    # initialize logging object - all classes then use this object  
+      def init_logging
+#--{{{
+        log, log_age, log_size, verbosity = 
+          @options.values_at 'log', 'log_age', 'log_size', 'verbosity'
+        log_age = atoi log_age rescue nil
+        log_size = atoi log_size rescue nil
+        $logger = @logger = Logger::new(log || STDERR, log_age, log_size)
+      #
+      # hack to fix Logger sync bug
+      #
+        @logger.class.instance_eval do
+          attr :logdev unless @logger.respond_to?(:logdev)
+        end
+
+        @logdev = @logger.logdev.dev 
+        @logdev.sync = true
+        level = nil
+        verbosity ||=
+          if @options.has_key? 'verbosity'
+            'debug'
+          else
+            'info'
+          end
+        verbosity =
+          case verbosity
+            when /^\s*(?:4|d|debug)\s*$/io
+              level = 'Logging::DEBUG'
+              4
+            when /^\s*(?:3|i|info)\s*$/io
+              level = 'Logging::INFO'
+              3
+            when /^\s*(?:2|w|warn)\s*$/io
+              level = 'Logging::WARN'
+              2
+            when /^\s*(?:1|e|error)\s*$/io
+              level = 'Logging::ERROR'
+              1
+            when /^\s*(?:0|f|fatal)\s*$/io
+              level = 'Logging::FATAL'
+              0
+            else
+              abort "illegal verbosity setting <#{ verbosity }>" 
+          end
+        @logger.level = 2 - ((verbosity % 5) - 2) 
+        #debug {"logging level <#{ level }>"}
+        @logger
+#--}}}
+      end
+    # initialize configuration file - not currenlty utilized 
+      def init_config
+#--{{{
+        @config =
+          if @options['config']
+            ConfigFile::new(@options['config'])
+          else
+            ConfigFile::any CONFIG_DEFAULT_PATH, CONFIG_SEARCH_PATH
+          end
+        debug { "config.path <#{ @config.path }>" }
+        @config
+#--}}}
+      end
+    # generate a template/sample config file which can then be edited
+      def gen_template template
+#--{{{
+        ConfigFile::gen_template(template)
+        self
+#--}}}
+      end
+#--}}}
+    end
+  end
+
+#
+# run main program unless included as a library (testing purposes)
+#
+  RQ::Main::new ARGV, ENV