rq 0.1.7 → 3.0.0

data/lib/rq-0.1.7/jobrunner.rb

@@ -1,63 +0,0 @@
-unless defined? $__rq_jobrunner__
-  module RQ 
-#{{{
-    LIBDIR = File::dirname(File::expand_path(__FILE__)) + File::SEPARATOR unless
-      defined? LIBDIR
-
-    require 'drb/drb'
-
-    require LIBDIR + 'util'
-
-    class  JobRunner
-#{{{
-      include DRbUndumped
-      attr :job
-      attr :jid
-      attr :cid
-      attr :shell
-      attr :command
-      alias pid cid
-      def initialize job
-#{{{
-        @job = job
-        @jid = job['jid']
-        @command = job['command']
-        @shell = job['shell'] || 'bash'
-        @r,@w = IO::pipe
-        @env = {}
-        @job.fields.each do |field|
-          key = "RQ_#{ field }".upcase.gsub(%r/\s+/,'_')
-          val = @job[field]
-          @env[key] = "#{ val }"
-        end
-        @cid = 
-          Util::fork do
-            begin
-              @env.each{|k,v| ENV[k] = v}
-              ENV['RQ_PID'] = "#{ $$ }"
-              @w.close
-              STDIN.reopen @r
-              if File::basename(@shell) == 'bash' || File::basename(@shell) == 'sh' 
-                exec [@shell, "__rq_job__#{ @jid }__#{ File::basename(@shell) }__"], '--login'
-              else
-                exec [@shell, "__rq_job__#{ @jid }__#{ File::basename(@shell) }__"], '-l'
-              end
-            rescue Exception => e
-              STDERR.puts(Util::errmsg(e))
-            end
-          end
-        @r.close
-#}}}
-      end
-      def run
-#{{{
-        @w.puts @command
-        @w.close
-#}}}
-      end
-#}}}
-    end # class JobRunner
-#}}}
-  end # module RQ
-$__rq_jobrunner__ = __FILE__ 
-end

data/lib/rq-0.1.7/lister.rb

@@ -1,22 +0,0 @@
-unless defined? $__rq_lister__
-  module RQ 
-#{{{
-    LIBDIR = File::dirname(File::expand_path(__FILE__)) + File::SEPARATOR unless
-      defined? LIBDIR
-
-    require LIBDIR + 'mainhelper'
-
-    class  Lister < MainHelper
-#{{{
-      def list 
-    #{{{
-        set_q
-        @q.list(*@argv)
-    #}}}
-      end
-#}}}
-    end # class Lister
-#}}}
-  end # module RQ
-$__rq_lister__ = __FILE__ 
-end

data/lib/rq-0.1.7/mainhelper.rb

@@ -1,53 +0,0 @@
-unless defined? $__rq_mainhelper__
-  module RQ 
-#{{{
-    LIBDIR = File::dirname(File::expand_path(__FILE__)) + File::SEPARATOR unless
-      defined? LIBDIR
-
-    require LIBDIR + 'util'
-    require LIBDIR + 'logging'
-
-    class  MainHelper
-#{{{
-      include Util
-      include Logging
-      attr :main
-      attr :logger
-      attr :argv
-      attr :env
-      attr :cmd
-      attr :options
-      attr :qpath
-      attr :mode
-      attr :q
-      def initialize main
-#{{{
-        @main = main
-        @logger = main.logger
-        @argv = main.argv
-        @env = main.env
-        @cmd = main.cmd
-        @options = main.options
-        @qpath = main.qpath
-        @mode = main.mode
-        @q = nil 
-#}}}
-      end
-      def set_q
-    #{{{
-        raise "q <#{ @qpath }> does not exist" unless test ?d, @qpath
-        @q = JobQueue::new @qpath, 'logger' => @logger
-        if @options['snapshot']
-          ss = "#{ $0 }_#{ Process::pid }_#{ Thread::current.id.abs }_#{ rand Time::now.to_i  }".gsub(%r|/|o,'_')
-          qtmp = File::join Dir::tmpdir, ss
-          @q = @q.snapshot qtmp, @options['retries']
-          at_exit{ FileUtils::rm_rf qtmp }
-        end
-    #}}}
-      end
-#}}}
-    end # class MainHelper
-#}}}
-  end # module RQ
-$__rq_mainhelper__ = __FILE__ 
-end

data/lib/rq-0.1.7/querier.rb

@@ -1,33 +0,0 @@
-unless defined? $__rq_queryier__
-  module RQ 
-#{{{
-    LIBDIR = File::dirname(File::expand_path(__FILE__)) + File::SEPARATOR unless
-      defined? LIBDIR
-
-    require LIBDIR + 'mainhelper'
-
-    class Querier < MainHelper
-#{{{
-      def query
-    #{{{
-        set_q
-        where_clause = @argv.join ' '
-        if where_clause.empty? or not STDIN.tty?
-          debug{ "reading where_clause from STDIN" }
-          while((buf = STDIN.gets))
-            buf.strip!
-            buf.gsub! %r/#.*$/o, ''
-            next if buf.empty?
-            where_clause << "#{ buf } "
-          end
-        end
-        @q.qdb.transaction_retries = 1
-        @q.query where_clause
-    #}}}
-      end
-#}}}
-    end # class Queryier
-#}}}
-  end # module RQ
-$__rq_queryier__ = __FILE__ 
-end

data/lib/rq-0.1.7/snapshotter.rb

@@ -1,25 +0,0 @@
-unless defined? $__rq_snapshotter__
-  module RQ 
-#{{{
-    LIBDIR = File::dirname(File::expand_path(__FILE__)) + File::SEPARATOR unless
-      defined? LIBDIR
-
-    require LIBDIR + 'mainhelper'
-
-    class  Snapshotter < MainHelper
-#{{{
-      def snapshot 
-    #{{{
-        set_q
-        qtmp = @argv.shift
-        raise "<#{ qtmp }> exists" if qtmp and test(?e, qtmp)
-        qss = @q.snapshot qtmp, @options['retries']
-        info{ "created q snapshot <#{ qtmp }>" }
-    #}}}
-      end
-#}}}
-    end # class Snapshotter
-#}}}
-  end # module RQ
-$__rq_snapshotter__ = __FILE__ 
-end

data/lib/rq-0.1.7/statuslister.rb

@@ -1,22 +0,0 @@
-unless defined? $__rq_statuslister__
-  module RQ 
-#{{{
-    LIBDIR = File::dirname(File::expand_path(__FILE__)) + File::SEPARATOR unless
-      defined? LIBDIR
-
-    require LIBDIR + 'mainhelper'
-
-    class  StatusLister < MainHelper
-#{{{
-      def statuslist 
-    #{{{
-        set_q
-        @q.status(*@argv)
-    #}}}
-      end
-#}}}
-    end # class StatusLister
-#}}}
-  end # module RQ
-$__rq_statuslister__ = __FILE__ 
-end

data/lib/rq-0.1.7/submitter.rb

@@ -1,90 +0,0 @@
-unless defined? $__rq_submitter__
-  module RQ 
-#{{{
-    LIBDIR = File::dirname(File::expand_path(__FILE__)) + File::SEPARATOR unless
-      defined? LIBDIR
-
-    require LIBDIR + 'mainhelper'
-
-    class  Submitter < MainHelper
-#{{{
-      def submit
-    #{{{
-        set_q
-
-        priority = @options['priority'] || 0
-        debug{ "priority <#{ priority }>" }
-
-        tag = @options['tag']
-        debug{ "tag <#{ tag }>" }
-
-        infile = @options['infile'] 
-        debug{ "infile <#{ infile }>" }
-
-        jobs = [] 
-
-        unless @argv.empty?
-          job = Job::new
-          job['command'] = @argv.join(' ') 
-          job['priority'] = priority
-          job['tag'] = tag 
-          jobs << job
-        end
-
-        loadio = lambda do |io, path|
-          while((line = io.gets))
-            if line =~ %r/^---\s*$/o
-              loaded = YAML::load io 
-              raise "no jobs in <#{ path }>" unless 
-                Array === loaded and 
-                Hash === loaded.first and Hash === loaded.last
-              loaded.each{|job| jobs << job}
-              loaded = nil
-            else
-              line.gsub!(%r/(?:^\s+)|(?:\s+$)|(?:#.*$)/o, '')
-              next if line.empty?
-              job = Job::new
-              job['command'] = line
-              job['priority'] = priority
-              job['tag'] = tag 
-              jobs << job
-            end
-          end
-        end
-
-        if infile
-          open(infile) do |f|
-            debug{ "reading jobs from <#{ infile }>" }
-            loadio.call f, infile 
-          end
-        end
-
-        if jobs.empty? or not STDIN.tty? 
-          debug{ "reading jobs from <stdin>" }
-          loadio.call STDIN, 'stdin' 
-        end
-
-        raise "no jobs specified!" if jobs.empty?
-    
-        if @options['quiet'] 
-          @q.submit(*jobs)
-        else
-          puts '---'
-          fields = @q.db.fields
-          @q.submit(*jobs) do |tuple|
-            puts '-'
-            fields.each{|f| puts " #{ f }: #{ tuple[ f ] }"}
-          end
-        end
-    
-        jobs = nil
-    
-        self
-    #}}}
-      end
-#}}}
-    end # class Submitter
-#}}}
-  end # module RQ
-$__rq_submitter__ = __FILE__ 
-end

data/lib/rq-0.1.7/updater.rb

@@ -1,95 +0,0 @@
-unless defined? $__rq_updater__
-  module RQ 
-#{{{
-    LIBDIR = File::dirname(File::expand_path(__FILE__)) + File::SEPARATOR unless
-      defined? LIBDIR
-
-    require LIBDIR + 'mainhelper'
-
-    class  Updater < MainHelper
-#{{{
-      def update 
-    #{{{
-        set_q
-        jids = []
-        kvs = {} 
-      #
-      # scan argv for jids to update 
-      #
-        while((arg = @argv.first))
-          case arg
-            when %r/^\d+$/o
-              jids << Integer(arg)
-            when %r/^jid\s*=\s*(\d+)$/io
-              jids << Integer($1)
-            when %r/^p(?:ending)$/o
-              jids << 'pending' 
-            else
-              break
-          end
-          @argv.shift
-        end
-      #
-      # scan argv for key=val pairs
-      #
-        cmdline = @argv.join(' ')
-        keyeqpat = %r/\s*([^\s=]+)\s*=\s*/
-        keyvals = cmdline.split keyeqpat
-        keyvals.shift
-        loop do
-          k = keyvals.shift
-          v = keyvals.shift
-          break if k.nil? and v.nil?
-          raise "syntax error in update <#{ cmdline }> @ <#{ k }>" unless
-            k and v
-          k.strip!
-          v.strip!
-          kvs[k] = v
-        end
-        raise "no updates" if kvs.empty?
-      #
-      # scan stdin for jids to update if in pipeline
-      #
-        #if jids.empty? or not STDIN.tty? 
-        if not STDIN.tty? 
-          #pat = %r/^(?:\s*jid\s*:)?\s*(\d+)\s*$/io
-          while((line = STDIN.gets))
-            case line
-              when %r/^(?:\s*jid\s*:)?\s*(\d+)\s*$/io
-                jids << Integer($1)
-              when %r/^\s*p(?:ending)\s*$/io
-                jids << 'pending' 
-              else
-                next
-            end
-          end
-        end
-        #jids.map!{|jid| jid =~ %r/^\s*\d+\s*$/o ? Integer(jid) : jid}
-        #raise "no jids" if jids.empty?
-      #
-      # if no jids were specified simply update all pending jobs
-      #
-        jids << 'pending' if jids.empty?
-      #
-      # apply the update
-      #
-        if @options['quiet'] 
-          @q.update(kvs,*jids)
-        else
-          puts '---'
-          tuples = @q.update(kvs,*jids)
-          fields = nil
-          tuples.each do |tuple|
-            puts '-'
-            fields ||= tuple.fields
-            fields.each{|f| puts " #{ f }: #{ tuple[f] }" }
-          end
-        end
-    #}}}
-      end
-#}}}
-    end # class Updater
-#}}}
-  end # module RQ
-$__rq_updater__ = __FILE__ 
-end

data/lib/rq-0.1.7/usage.rb

@@ -1,609 +0,0 @@
-unless defined? $__rq_usage__
-  module RQ 
-#{{{
-    LIBDIR = File::dirname(File::expand_path(__FILE__)) + File::SEPARATOR unless
-      defined? LIBDIR
-
-    require LIBDIR + 'util'
-
-    module  Usage
-#{{{
-      def cget const
-#{{{
-        begin
-          klass::const_get const
-        rescue NameError
-          nil
-        end
-#}}}
-      end
-      def usage opts = {}
-#{{{
-        port = getopt 'port', opts
-        long = getopt 'long', opts
-
-        port = STDERR if port.nil?
-
-        if(long and (txt = cget 'USAGE'))
-          port << txt << "\n"
-        elsif((txt = cget 'USAGE_BANNER'))
-          port << txt << "\n"
-        else
-          port << "#{ $0 } [options]* [args]*" << "\n"
-        end
-
-        if((optspec = cget 'OPTSPEC'))
-          port << 'OPTIONS' << "\n"
-          optspec.each do |os| 
-            a, b, c = os
-            long, short, desc = nil
-            [a,b,c].each do |word|
-              next unless word
-              word.strip!
-              case word
-                when %r/^--[^-]/o
-                  long = word
-                when %r/^-[^-]/o
-                  short = word
-                else
-                  desc = word
-              end
-            end
-            spec = ((long and short) ? [long, short] : [long])
-            if spec
-              port << columnize(spec.join(', '), 80, 2)
-              port << "\n"
-            end
-            if desc
-              port << columnize(desc, 80, 8)
-              port << "\n"
-            end
-          end
-          port << "\n"
-        end
-
-        if((txt = cget 'EXAMPLES'))
-          port << txt << "\n"
-        end
-
-        port
-#}}}
-      end
-      module_function :usage
-      public :usage
-
-      PROGNAM = 'rq' 
-
-      USAGE_BANNER = 
-#{{{
-<<-usage_banner
-NAME
-  #{ PROGNAM } v#{ VERSION }
-
-SYNOPSIS
-  #{ PROGNAM } (queue | export RQ_Q=q) mode [mode_args]* [options]*
-usage_banner
-#}}}
-
-      USAGE = 
-#{{{
-<<-usage
-#{ USAGE_BANNER }
-
-DESCRIPTION
-  ruby queue (rq) is a tool used to create instant linux clusters by managing
-  sqlite databases as nfs mounted priority work queues.  multiple instances of
-  #{ PROGNAM } running from multiples hosts can work from these queues to
-  distribute processing load to n nodes - bringing many dozens of otherwise
-  powerful cpus to their knees with a single blow.  clearly this software should
-  be kept out of the hands of free radicals, seti enthusiasts, and j. safran.
-
-  the central concept of #{ PROGNAM } is that n nodes work in isolation to pull
-  jobs from an central nfs mounted work priority work queue in a synchronized
-  fashion.  the nodes have absolutely no knowledge of each other and all
-  communication if done via the queue meaning that, so long as the queue is
-  available via nfs and a single node is running jobs from it, the system will
-  continue to process jobs.  there is no centralized process whatsoever - all
-  nodes work to take jobs from the queue and run them as fast as possible.  this
-  creates a system which load balances automatically and is robust in face of
-  node failures.
-
-  the first argument to any #{ PROGNAM } command is the name of the queue.  this
-  name may be omitted if, and only if, the environment variable RQ_Q has been
-  set to contain the absolute path of target queue.
-  
-  #{ PROGNAM } operates in one of the modes create, submit, list, status,
-  delete, update, query, execute, configure, snapshot, lock, backup, help, or
-  feed.  depending on the mode of operation and the options used the meaning of
-  'mode_args' may change.
-
-MODES
-
-  the following mode abbreviations exist
-
-    c  => create
-    s  => submit
-    l  => list
-    ls => list
-    t  => status
-    d  => delete
-    rm => delete
-    u  => update
-    q  => query
-    e  => execute
-    C  => configure
-    S  => snapshot
-    L  => lock
-    b  => backup
-    h  => help
-    f  => feed
-
-  create, c :
-
-    create a queue.  the queue must be located on an nfs mounted file system
-    visible from all nodes intended to run jobs from it.
-
-    examples :
-
-      0) to create a queue
-          ~ > #{ PROGNAM } /path/to/nfs/mounted/q create
-        or simply
-          ~ > #{ PROGNAM } /path/to/nfs/mounted/q c
-
-
-  submit, s :
-
-    submit jobs to a queue to be proccesed by a feeding node.  any 'mode_args'
-    are taken as the command to run.  note that 'mode_args' are subject to shell
-    expansion - if you don't understand what this means do not use this feature
-    and pass jobs on stdin.
-
-    when running in submit mode a file may by specified as a list of commands to
-    run using the '--infile, -i' option.  this file is taken to be a newline
-    separated list of commands to submit, blank lines and comments (#) are
-    allowed.  if submitting a large number of jobs the input file method is
-    MUCH, more efficient.  if no commands are specified on the command line #{ PROGNAM } 
-    automatically reads them from STDIN.  yaml formatted files are also allowed
-    as input (http://www.yaml.org/) - note that the output of nearly all #{ PROGNAM } 
-    commands is valid yaml and may, therefore, be piped as input into the submit
-    command.
-
-    when submitting the '--priority, -p' option can be used here to determine
-    the priority of jobs.  priorities may be any whole number - zero is the
-    default.  note that submission of a high priority job will NOT supplant
-    currently running low priority jobs, but higher priority jobs WILL always
-    migrate above lower priority jobs in the queue in order that they be run as
-    soon as possible.  constant submission of high priority jobs may create a
-    starvation situation whereby low priority jobs are never allowed to run.
-    avoiding this situation is the responsibility of the user.  the only
-    guaruntee #{ PROGNAM } makes regarding job execution is that jobs are
-    executed in an 'oldest highest priority' order and that running jobs are
-    never supplanted.
-
-    examples :
-
-      0) submit the job ls to run on some feeding host
-
-        ~ > #{ PROGNAM } q s ls
-
-      1) submit the job ls to run on some feeding host, at priority 9
-
-        ~ > #{ PROGNAM } -p9 q s ls 
-
-      2) submit 42000 jobs (quietly) from a command file.
-
-        ~ > wc -l cmdfile 
-        42000
-        ~ > #{ PROGNAM } q s -q < cmdfile
-
-      3) submit 42 priority 9 jobs from a command file.
-
-        ~ > wc -l cmdfile 
-        42
-        ~ > #{ PROGNAM } -p9 q s < cmdfile
-
-      4) submit 42 priority 9 jobs from a command file, marking them as
-         'important' using the '--tag, -t' option.
-
-        ~ > wc -l cmdfile 
-        42
-        ~ > #{ PROGNAM } -p9 -timportant q s < cmdfile
-
-      5) re-submit all the 'important' jobs (see 'query' section below)
-
-        ~ > #{ PROGNAM } q query tag=important | #{ PROGNAM } q s
-
-      6) re-submit all jobs which are already finished (see 'list' section
-         below) 
-
-        ~ > #{ PROGNAM } q l f | #{ PROGNAM } q s 
-
-
-  list, l, ls :
-
-    list mode lists jobs of a certain state or job id.  state may be one of
-    pending, running, finished, dead, or all.  any 'mode_args' that are numbers
-    are taken to be job id's to list.
-
-    states may be abbreviated to uniqueness, therefore the following shortcuts
-    apply :        
-
-      p => pending
-      r => running
-      f => finished
-      d => dead
-      a => all
-
-    examples :
-
-      0) show everything in q
-          ~ > #{ PROGNAM } q list all
-        or
-          ~ > #{ PROGNAM } q l all
-        or
-          ~ > export RQ_Q=q 
-          ~ > #{ PROGNAM } l
-
-      1) show q's pending jobs
-          ~ > #{ PROGNAM } q list pending
-
-      2) show q's running jobs
-          ~ > #{ PROGNAM } q list running 
-
-      3) show q's finished jobs
-          ~ > #{ PROGNAM } q list finshed 
-
-      4) show job id 42 
-          ~ > #{ PROGNAM } q l 42 
-
-
-  status, t :
-
-    status mode shows the global state the queue.  there are no 'mode_args'.
-    the meaning of each state is as follows:
-
-      pending  => no feeder has yet taken this job
-      running  => a feeder has taken this job
-      finished => a feeder has finished this job
-      dead     => #{ PROGNAM } died while running a job, has restarted, and moved
-                  this job to the dead state
-
-    note that #{ PROGNAM } cannot move jobs into the dead state unless it has
-    been restarted.  this is because no node has any knowledge of other nodes
-    and cannot possibly know if a job was started on a node that died, or is
-    simply taking a very long time.  only the node that dies, upon restart, can
-    determine that is has jobs that 'were started before it started' and move
-    these jobs into the dead state.  normally only a machine crash would cause a
-    job to be placed into the dead state.  dead jobs are never automatically
-    restarted, this is the responsibility of an operator.
-
-    examples :
-
-      0) show q's status
-
-        ~ > #{ PROGNAM } q t 
-
-
-  delete, d :
-
-    delete combinations of pending, running, finished, dead, or jobs specified
-    by jid.  the delete mode is capable of parsing the output of list and query
-    modes, making it possible to create custom filters to delete jobs meeting
-    very specific conditions.
-
-    'mode_args' are the same as for list.  note that while it is possible to
-    delete a running job, but there is no way to actually STOP it mid execution
-    since the node doing the deleteing has no way to communicate this
-    information to the (probably) remote execution node.  therefore you should
-    use the 'delete running' feature with care and only for housekeeping
-    purposes or to prevent future jobs from being scheduled.
-
-    examples :
-
-      0) delete all pending, running, and finished jobs from a queue
-
-        ~ > #{ PROGNAM } q d all
-
-      1) delete all pending jobs from a queue
-
-        ~ > #{ PROGNAM } q d p 
-
-      2) delete all finished jobs from a queue
-
-        ~ > #{ PROGNAM } q d f 
-
-      3) delete jobs via hand crafted filter program
-
-        ~ > #{ PROGNAM } q list | yaml_filter_prog | #{ PROGNAM } q d
-
-
-  update, u :
-
-    update assumes all leading arguments are jids to update with subsequent
-    key=value pairs.  currently only the 'command', 'priority', and 'tag' fields
-    of pending jobs can be updated.
-
-    examples:
-
-      0) update the priority of job 42 
-
-        ~ > #{ PROGNAM } q update 42 priority=7 
-
-      1) update the priority of all pending jobs 
-
-        ~ > #{ PROGNAM } q update pending priority=7 
-
-      2) query jobs with a command matching 'foobar' and update their command 
-         to be 'barfoo'
-
-        ~ > #{ PROGNAM } q q "command like '%foobar%'" |\\
-            #{ PROGNAM } q u command=barfoo 
-
-
-  query, q :
-
-    query exposes the database more directly the user, evaluating the where
-    clause specified on the command line (or from STDIN).  this feature can be
-    used to make a fine grained slection of jobs for reporting or as input into
-    the delete command.  you must have a basic understanding of SQL syntax to
-    use this feature, but it is fairly intuitive in this limited capacity.
-
-    examples:
-
-      0) show all jobs submitted within a specific 10 minute range
-
-        ~ > #{ PROGNAM } q query "started >= '2004-06-29 22:51:00' and started < '2004-06-29 22:51:10'"
-
-      1) shell quoting can be tricky here so input on STDIN is also allowed to
-         avoid shell expansion
-
-        ~ > cat constraints.txt 
-        started >= '2004-06-29 22:51:00' and
-        started < '2004-06-29 22:51:10'
-
-        ~ > #{ PROGNAM } q query < contraints.txt
-          or (same thing)
-
-        ~ > cat contraints.txt| #{ PROGNAM } q query
-
-        ** in general all but numbers will need to be surrounded by single quotes **
-
-      2) this query output might then be used to delete those jobs
-
-        ~ > cat contraints.txt | #{ PROGNAM } q q | #{ PROGNAM } q d
-
-      3) show all jobs which are either finished or dead 
-
-        ~ > #{ PROGNAM } q q "state='finished' or state='dead'"
-
-      4) show all jobs which have non-zero exit status
-
-        ~ > #{ PROGNAM } q query exit_status!=0 
-
-      5) if you plan to query groups of jobs with some common feature consider
-         using the '--tag, -t' feature of the submit mode which allows a user to
-         tag a job with a user defined string which can then be used to easily
-         query that job group 
-
-        ~ > #{ PROGNAM } q submit --tag=my_jobs < joblist 
-        ~ > #{ PROGNAM } q query tag=my_jobs 
-
-
-  execute, e :
-
-    execute mode is to be used by expert users with a knowledge of sql syntax
-    only.  it follows the locking protocol used by #{ PROGNAM } and then allows
-    the user to execute arbitrary sql on the queue.  unlike query mode a write
-    lock on the queue is obtained allowing a user to definitively shoot
-    themselves in the foot.  for details on a queue's schema the file
-    'db.schema' in the queue directory should be examined.
-
-      examples :
-
-        0) list all jobs
-
-          ~ > #{ PROGNAM } q execute 'select * from jobs'
-
-
-  configure, C :
-
-    this mode is not supported yet.
-
-
-  snapshot, p :
-
-    snapshot provides a means of taking a snapshot of the q. use this feature
-    when many queries are going to be run; for example when attempting to figure
-    out a complex pipeline command your test queries will not compete with the
-    feeders for the queue's lock.  you should use this option whenever possible
-    to avoid lock competition.
-
-    examples:
-
-      0) take a snapshot using default snapshot naming, which is made via the
-         basename of the q plus '.snapshot'
-
-        ~ > #{ PROGNAM } /path/to/nfs/q snapshot 
-
-      1) use this snapshot to chceck status
-
-        ~ > #{ PROGNAM } ./q.snapshot status 
-
-      2) use the snapshot to see what's running on which host
-
-        ~ > #{ PROGNAM } ./q.snapshot list running | grep `hostname` 
-
-    note that there is also a snapshot option - this option is not the same as
-    the snapshot command.  the option can be applied to ANY command. if in
-    effect then that command will be run on a snapshot of the database and the
-    snapshot then immediately deleted.  this is really only useful if one were
-    to need to run a command against a very heavily loaded queue and did not
-    wish to wait to obtain the lock.  eg.
-
-      0) get the status of a heavily loaded queue
-
-        ~ > #{ PROGNAM } q t --snapshot
-
-      1) same as above 
-
-        ~ > #{ PROGNAM } q t -s
-
-
-  lock, L :
-
-    lock the queue and then execute an arbitrary shell command.  lock mode uses
-    the queue's locking protocol to safely obtain a lock of the specified type
-    and execute a command on the user's behalf.  lock type must be one of
-
-      (r)ead | (sh)ared | (w)rite | (ex)clusive
-
-    examples :
-
-      0) get a read lock on the queue and make a backup
-
-        ~ > #{ PROGNAM } q L read -- cp -r q q.bak
-
-        (the '--' is needed to tell #{ PROGNAM } to stop parsing command line
-         options which allows the '-r' to be passed to the 'cp' command)
-
-
-  backup, b :
-
-    backup mode is exactly the same as getting a read lock on the queue and
-    making a copy of it.  this mode is provided as a convenience.
-
-      0) make a backup of the queue using default naming ( qname + timestamp + .bak )
-
-        ~ > #{ PROGNAM } q b
-
-      1) make a backup of the queue as 'q.bak' 
-
-        ~ > #{ PROGNAM } q b q.bak
-
-  help, h :
-
-    this message
-
-    examples :
-
-      0) get this message
-
-        ~> #{ PROGNAM } q help
-        or
-        ~> #{ PROGNAM } help
-
-
-  feed, f :
-
-    take jobs from the queue and run them on behalf of the submitter as quickly
-    as possible.  jobs are taken from the queue in an 'oldest highest priority'
-    first order.  
-    
-    feeders can be run from any number of nodes allowing you to harness the CPU
-    power of many nodes simoultaneously in order to more effectively clobber
-    your network, anoy your sysads, and set output raids on fire.
-    
-    the most useful method of feeding from a queue is to do so in daemon mode so
-    that if the process loses it's controling terminal it will not exit when you
-    exit your terminal session.  use the '--daemon, -d' option to accomplish
-    this.  by default only one feeding process per host per queue is allowed to
-    run at any given moment.  because of this it is acceptable to start a feeder
-    at some regular interval from a cron entry since, if a feeder is alreay
-    running, the process will simply exit and otherwise a new feeder will be
-    started.  in this way you may keep feeder processing running even acroess
-    machine reboots without requiring sysad intervention to add an entry to the
-    machine's startup tasks.
-
-
-    examples :
-
-      0) feed from a queue verbosely for debugging purposes, using a minimum and
-         maximum polling time of 2 and 4 respectively.  you would NEVER specify
-         polling times this brief except for debugging purposes!!!
-
-        ~ > #{ PROGNAM } q feed -v4 -m2 -M4
-
-      1) same as above, but viewing the executed sql as it is sent to the
-         database
-
-        ~ > RQ_SQL_DEBUG=1 #{ PROGNAM } q f -v4 -m2 -M4
-
-      2) feed from a queue in daemon mode - logging to /home/ahoward/rq.log
-
-        ~ > #{ PROGNAM } q f -d -l/home/ahoward/rq.log
-
-         log rolling in daemon mode is automatic so your logs should never need
-         to be deleted to prevent disk overflow.
-
-      3) use something like this sample crontab entry to keep a feeder running
-         forever - it attempts to (re)start every fifteen minutes but exits if
-         another process is already feeding.
-
-        #
-        # your crontab file - sample only
-        #
-
-        */15 * * * * /full/path/to/bin/rq /full/path/to/nfs/mounted/q f -d -l/home/username/cfq.log -q
-
-        the '--quiet, -q' here tells #{ PROGNAM } to exit quietly (no STDERR)
-        when another process is found to already be feeding so that no cron
-        message would be sent under these conditions.
-
-
-NOTES
-  - realize that your job is going to be running on a remote host and this has
-    implications.  paths, for example, should be absolute, not relative.
-    specifically the submitted job script must be visible from all hosts
-    currently feeding from a queue as must be the input and output
-    files/directories.
-
-  - jobs are currently run under the bash shell using the --login option.
-    therefore any settings in your .bashrc will apply - specifically your PATH
-    setting.  you should not, however, rely on jobs running with any given
-    environment.
-
-  - you need to consider __CAREFULLY__ what the ramifications of having multiple
-    instances of your program all potentially running at the same time will be.
-    for instance, it is beyond the scope of #{ PROGNAM } to ensure multiple
-    instances of a given program will not overwrite each others output files.
-    coordination of programs is left entirely to the user.
-
-  - the list of finished jobs will grow without bound unless you sometimes
-    delete some (all) of them.  the reason for this is that #{ PROGNAM } cannot
-    know when the user has collected the exit_status of a given job, and so
-    keeps this information in the queue forever until instructed to delete it.
-    if you have collected the exit_status of you job(s) it is not an error to
-    then delete that job from the finished list - the information is kept for
-    your informational purposes only.  in a production system it would be normal
-    to periodically save, and then delete, all finished jobs.
-
-ENVIRONMENT
-  RQ_Q: set to the full path of nfs mounted queue
-
-    the queue argument to all commands may be omitted if, and only if, the
-    environment variable 'RQ_Q' contains the full path to the q.  eg.
-
-      ~ > export RQ_Q=/full/path/to/my/q
-
-    this feature can save a considerable amount of typing for those weak of
-    wrist.
-
-DIAGNOSTICS
- success : $? == 0
- failure : $? != 0
-
-AUTHOR
-  #{ AUTHOR }
-
-BUGS
- 0 < bugno && bugno <= 42
-
- reports to #{ AUTHOR }
-usage
-#}}}
-#}}}
-    end # module Usage
-#}}}
-  end # module RQ
-$__rq_usage__ = __FILE__ 
-end