rq 0.1.7

data/lib/rq-0.1.7/querier.rb

@@ -0,0 +1,33 @@
+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/refresher.rb

@@ -0,0 +1,72 @@
+unless defined? $__rq_refresher__
+  module RQ 
+#{{{
+    LIBDIR = File::dirname(File::expand_path(__FILE__)) + File::SEPARATOR unless
+      defined? LIBDIR
+
+    class Refresher
+#{{{
+      SIGNALS = %w(SIGTERM SIGINT SIGKILL)
+      attr :path
+      attr :pid
+      attr :refresh_rate
+      def initialize path, refresh_rate = 8
+#{{{
+        @path = path
+        File::stat path
+        @refresh_rate = Float refresh_rate
+        @pipe = IO::pipe
+        if((@pid = Util::fork))
+          @pipe.last.close
+          @pipe = @pipe.first
+          @thread = Thread::new{loop{@pipe.gets}}
+          Process::detach @pid
+        else
+          begin
+            pid = Process::pid
+            ppid = Process::ppid
+            $0 = "#{ path }.refresher.#{ pid }"
+            SIGNALS.each{|sig| trap(sig){ raise }}
+            @pipe.first.close
+            @pipe = @pipe.last
+            loop do
+              FileUtils::touch @path
+              sleep @refresh_rate
+              Process::kill 0, ppid
+              @pipe.puts pid
+            end
+          rescue Exception => e
+            exit!
+          end
+        end
+#}}}
+      end
+      def kill
+#{{{
+        begin
+          @thread.kill rescue nil
+          @pipe.close rescue nil
+          SIGNALS.each{|sig| Process::kill sig, @pid rescue nil}
+        ensure
+=begin
+          n = 42
+          dead = false
+          begin
+            n.times do |i|
+              Process::kill 0, @pid
+              sleep 1
+            end
+          rescue Errno::ESRCH
+            dead = true
+          end
+          raise "runaway refresher <#{ @pid }> must be killed!" unless dead
+=end
+        end
+#}}}
+      end
+#}}}
+    end # class Refresher
+#}}}
+  end # module RQ
+$__rq_refresher__ = __FILE__ 
+end

data/lib/rq-0.1.7/sleepcycle.rb

@@ -0,0 +1,46 @@
+unless defined? $__rq_sleepcycle__
+  module RQ 
+#{{{
+    LIBDIR = File::dirname(File::expand_path(__FILE__)) + File::SEPARATOR unless
+      defined? LIBDIR
+
+#
+# the sleepcycle class provides timeouts for better than average polling
+# performance
+#
+    class SleepCycle < Array
+#{{{  
+      attr :min
+      attr :max
+      attr :range
+      attr :inc
+      def initialize min, max, inc
+#{{{
+        @min, @max, @inc = Float(min), Float(max), Float(inc)
+        @range = @max - @min
+        raise RangeError, "max < min" if @max < @min
+        raise RangeError, "inc > range" if @inc > @range
+        s = @min
+        push(s) and s += @inc while(s <= @max)
+        self[-1] = @max if self[-1] < @max
+        reset
+#}}}
+      end   
+      def next
+#{{{
+        ret = self[@idx]
+        @idx = ((@idx + 1) % self.size)
+        ret
+#}}}
+      end
+      def reset
+#{{{
+        @idx = 0
+#}}}
+      end
+#}}}      
+    end # class SleepCycle
+#}}}
+  end # module RQ
+$__rq_sleepcycle__ = __FILE__ 
+end

data/lib/rq-0.1.7/snapshotter.rb

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1,22 @@
+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

@@ -0,0 +1,90 @@
+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

@@ -0,0 +1,95 @@
+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

@@ -0,0 +1,609 @@
+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