lockfile 1.1.0 → 1.3.0

data/bin/rlock

@@ -1,46 +1,50 @@
 #!/usr/bin/env ruby
-
 #
-# builtin
+# built-in
 #
-  require 'rbconfig'
-  major, minor, teeny = %w(MAJOR MINOR TEENY).map{|k| Config::CONFIG[k].to_i}
-  unless major >= 1 and minor >= 8
-    STDERR.puts "ruby-1.8.0 or greater is required, you are running <ruby-#{ major }.#{ minor }.#{ teeny }>"
-    STDERR.puts "check your PATH setting or install ruby-1.8.0 or greater"
-    exit 1 
-  end
   require 'optparse'
   require 'logger'
-  require 'yaml'
-  require 'pp'
-
 #
-# RAA
+# http://raa.ruby-lang.org/project/lockfile/
 #
-  require 'lockfile.rb'
+  require 'lockfile-1.3.0.rb'
 
   class Main
-#{{{
-    VERSION = '0.0.0'
-    PROGNAM = File.basename(File.expand_path($0))
+#--{{{
+    VERSION = Lockfile::VERSION 
 
     USAGE = 
-#{{{
+#--{{{
   <<-usage
   NAME
-    #{ PROGNAM } v#{ VERSION }
+    rlock v#{ VERSION }
 
   SYNOPSIS
-    #{ PROGNAM } [options]+ file.lock [program [-- [options]+] [args]+]
+    rlock [options]+ lockfile [program [args]+ | -- program options+ [args]+]
 
   DESCRIPTTION
-    #{ PROGNAM } creates NFS resistent lockfiles
+    rlock creates NFS safe lockfiles.  it can optionally run a program while
+    holding the lock, ensuring lockfile removal on program exit.  if a program
+    is specified to be run rlock will spawn a background thread to kept the
+    lockfile 'fresh' by touching it at a regular interval.  in this way a lease
+    is maintained on the lockfile and other processes attempting to obtain the
+    lock can determine that it is in use.  see the '--refresh' option for how to
+    control the touch interval.  any other process trying to obtain a lock will
+    automatically remove a stale lockfile; a stale lockfile is one that is older
+    than a certain age.  this age be controled via the '--max_age' option.
 
   ENVIRONMENT
-    LOCKFILE_DEBUG=1 will show internal actions of the library
+    LOCKFILE_DEBUG=1 
+      causes internal actions of the library to be shown on STDERR 
 
   DIAGNOSTICS
+   rlock attempts to exit with the status of 'program' except where it
+   cannot due to exceptional conditions.  in addition the message 
+
+    'RLOCK SUBCOMMAND FAILURE' 
+    
+    will be printed on STDERR if 'program' exits with non-zero status.
+
    success => $? == 0
    failure => $? != 0
 
@@ -48,68 +52,78 @@
    ara.t.howard@noaa.gov
 
   BUGS
-   > 1
+    1 < bugno && bugno < 42
 
   OPTIONS
   usage
-#}}}
+#--}}}
 
     EXAMPLES =
-#{{{
+#--{{{
   <<-examples
   EXAMPLES
 
-    0) simple usage - just create a file.lock in an atomic fashion 
+    0) simple usage - create lockfile in an atomic fashion (obtain a lock) 
 
-      ~ > #{ PROGNAM } file.lock
+      ~ > rlock lockfile
 
-    1) safe usage - create a file.lock, execute a command, and remove file.lock
+    1) safe usage - create a lockfile, execute a command, and remove lockfile
 
-      ~ > #{ PROGNAM } file.lock ls file.lock
+      ~ > rlock lockfile ls lockfile
 
     2) same as above, but logging verbose messages 
 
-      ~ > #{ PROGNAM } -v4 file.lock ls file.lock
+      ~ > rlock -v4 lockfile ls lockfile
    
-    3) same as above, but logging verbose messages and showing actions internal to
-       lockfile library
+    3) same as above, but logging verbose messages and showing actions internal
+    to lockfile library
 
-      ~ > #{ PROGNAM } -v4 -d file.lock ls file.lock
+      ~ > rlock -v4 -d lockfile ls lockfile
 
     4) same as above
 
-      ~ > LOCKFILE_DEBUG=1 #{ PROGNAM } -v4 file.lock ls file.lock
+      ~ > LOCKFILE_DEBUG=1 rlock -v4 lockfile ls lockfile
 
     5) same as above
 
       ~ > export LOCKFILE_DEBUG=1
-      ~ > #{ PROGNAM } -v4 file.lock ls file.lock
+      ~ > rlock -v4 lockfile ls lockfile
+
+    6) you need to tell the option parser to stop parsing rlock options if you
+    intend to pass options to 'program' 
+
+      ~ > rlock -v4 -d lockfile -- ls -ltar lockfile
+
+       without the '--' rlock would consume the '-ltar' option as one of
+       it's own.
 
-    6) note that you need to tell the option parser to stop parsing #{ PROGNAM }
-       options if you intend to pass options to 'program' 
+    7) lock lockfile and exec 'program' - remove the lockfile if it is older
+    than 4242 seconds
 
-      ~ > #{ PROGNAM } -v4 -d file.lock -- ls -ltar file.lock
+      ~ > rlock --max_age=4242 lockfile program 
 
-       without the '--' #{ PROGNAM } would consume the '-ltar' options, parsing it
-       as the logfile name 'tar'
+    8) lock lockfile and exec 'program' - remove the lockfile if it is older
+    than 4242 seconds, set the refresh rate to be 8 seconds.
 
-    7) lock file.lock and exec 'program' - remove the file.lock if it is older
-       than 4242 seconds
+      ~ > rlock --max_age=4242 --refresh=8 lockfile program 
 
-      ~ > #{ PROGNAM } --max_age=4242 file.lock program 
+    9) same as above, but fail if lockfile cannot be obtained within 1 minute
 
-    8) lock file.lock and exec 'program' - remove the file.lock if it is older
-       than 4242 seconds, also spawn a background thread which will refresh
-       file.lock every 8 seonds will 'program' is executing
+      ~ > rlock --max_age=4242 --refresh=8 --timeout=60 lockfile program 
 
-      ~ > #{ PROGNAM } --max_age=4242 --refresh=8 file.lock program 
+    10) lockfile creation involves making some temporary files.  normally these
+    are cleaned up unless rlock is killed with 'kill -9'.  these temp files are
+    normally 'sweeped' - searched for and removed - unless the '--dont_sweep'
+    option is given.  note that sweeping can remove ONLY old temp files created
+    by the same host since there is otherwise no way to tell if the offending
+    process is still running.
 
-    9) same as above, but fail if file.lock cannot be obtained within 1 minute
+    lock lockfile and run program - do not do any sweeping
 
-      ~ > #{ PROGNAM } --max_age=4242 --refresh=8 --timeout=60 file.lock program 
+      ~ > rlock --dont_sweep lockfile program 
 
   examples
-#}}}
+#--}}}
 
     EXIT_SUCCESS = 0
     EXIT_FAILURE = 1
@@ -119,16 +133,24 @@
     attr :logger
     attr :config
 
-    def initialize argv = cp(ARGV)
-#{{{
-      @argv = argv
+    def initialize argv = ARGV
+#--{{{
+      @argv = mcp argv
       parse_opts
+      if @opt_version
+        puts Main::VERSION
+        exit EXIT_SUCCESS
+      end
+      if @opt_help
+        usage
+        exit EXIT_SUCCESS
+      end
       parse_argv
-#}}}
+      run
+#--}}}
     end
     def run
-#{{{
-      usage and exit EXIT_SUCCESS if @opt_help
+#--{{{
       init_logging
 
       debug{ "lockpath <#{ @lockpath }>" }
@@ -154,7 +176,7 @@
         case @argv.size
           when 0
             opts['dont_clean'] = true
-            logger.debug{ "opts <#{ pretty opts }>" }
+            logger.debug{ "opts <#{ opts.inspect }>" }
             logger.debug{ "aquiring lock <#{ @lockpath }>..." }
           #
           # simple usage - just create the lockfile with opts
@@ -164,27 +186,35 @@
 
             logger.debug{ "aquired lock <#{ @lockpath }>" }
           else
-            logger.debug{ "opts <#{ pretty opts }>" }
+            logger.debug{ "opts <#{ opts.inspect }>" }
             logger.debug{ "aquiring lock <#{ @lockpath }>..." }
           #
           # block usage - create the lockfile with opts, run block, rm lockfile
           #
+            status = 1
+
             lockfile = ::Lockfile.new @lockpath, opts
+
             lockfile.lock do
               logger.debug{ "aquired lock <#{ @lockpath }>" }
-              cmd = @argv.join ' '
-              logger.debug{ "cmd <#{ cmd }>" }
+              logger.debug{ "cmd <#{ @argv.join ' ' }>" }
               v = nil
               begin
                 v = $VERBOSE
                 $VERBOSE = nil 
-                system cmd 
+                STDOUT.flush
+                STDERR.flush
+                fork{ exec(*@argv) }
+                pid, status = Process::wait2
               ensure
                 $VERBOSE = v
               end
               logger.debug{ "status <#{ $? }>" }
             end
-            exit $?
+
+            status = status.exitstatus
+            STDERR.puts "RLOCK SUBCOMMAND FAILURE" unless status == 0
+            exit status
         end
       rescue => e
         logger.fatal{ e }
@@ -192,44 +222,25 @@
       end
 
       exit EXIT_SUCCESS
-#}}}
+#--}}}
     end
     def parse_opts
-#{{{
-      @op = OptionParser.new
+#--{{{
+      @op = OptionParser::new
       @op.banner = ''
       define_options
-      #begin
-        @op.parse! argv
-      #rescue OptionParser::InvalidOption => e
-        # preverve unknown options
-        #e.recover(argv)
-      #rescue Exception => e
-        #STDERR.puts PROGNAM
-        #STDERR.puts @op
-        #exit 2
-      #end
-
-#}}}
+      @op.parse! argv
+
+#--}}}
     end
     def parse_argv
-#{{{
+#--{{{
       usage and exit EXIT_FAILURE if @argv.empty?
       @lockpath = @argv.shift
-#}}}
-    end
-    def usage io = STDOUT
-#{{{
-      io << USAGE
-      io << "\n"
-      io << @op
-      io << "\n"
-      io << EXAMPLES if defined? EXAMPLES
-      self
-#}}}
+#--}}}
     end
     def define_options
-#{{{
+#--{{{
       options = [
         ['--retries=n','-r', "default(#{ Lockfile.retries.inspect }) - (nil => forever)"],
         ['--max_age=n','-a', "default(#{ Lockfile.max_age.inspect })"],
@@ -242,7 +253,9 @@
         ['--debug','-d', "default(#{ Lockfile.debug.inspect })"],
         ['--poll_retries=n','-R', "default(#{ Lockfile.poll_retries.inspect })"],
         ['--poll_max_sleep=n','-S', "default(#{ Lockfile.poll_max_sleep.inspect })"],
+        ['--dont_sweep','-w', "default(#{ Lockfile.dont_sweep.inspect })"],
 
+        ['--version'],
         ['--verbosity=0-4|debug|info|warn|error|fatal','-v'],
         ['--log=path','-l'],
         ['--log_age=log_age'],
@@ -254,20 +267,20 @@
         get, set = opt_attr opt
         @op.def_option(*option){|v| self.send(set, (v or true))}
       end
-#}}}
+#--}}}
     end
     %w(debug info warn error fatal).each do |m|
       eval "def #{ m }(*args,&block);@logger.#{ m }(*args,&block);end"
     end
     def init_logging
-#{{{
+#--{{{
       if @opt_log_age
         @opt_log_age = @opt_log_age.to_i if @opt_log_age =~ /\d/
       end
       if @opt_log_size
         @opt_log_size = @opt_log_size.to_i if @opt_log_size =~ /\d/
       end
-      $logger = @logger = Logger.new(@opt_log || $stdout, @opt_log_age, @opt_log_size)
+      $logger = @logger = Logger::new(@opt_log || STDERR, @opt_log_age, @opt_log_size)
 
       level = nil
       @opt_verbosity ||= 'info'
@@ -292,11 +305,20 @@
             abort "illegal verbosity setting <#{ @opt_verbosity }>" 
         end
       @logger.level = 2 - ((@opt_verbosity % 5) - 2) 
-      debug {"logging level <#{ level }>"}
-#}}}
+#--}}}
+    end
+    def usage io = STDOUT
+#--{{{
+      io << USAGE
+      io << "\n"
+      io << @op
+      io << "\n"
+      io << EXAMPLES if defined? EXAMPLES
+      self
+#--}}}
     end
     def opt_attr opt
-#{{{
+#--{{{
       get = "opt_#{ opt }"
       set = "#{ get }="
       code = <<-code
@@ -307,20 +329,14 @@
       code
       instance_eval code 
       [get, set]
-#}}}
+#--}}}
     end
-    def cp obj
-#{{{
-      Marshal.load(Marshal.dump(obj))
-#}}}
+    def mcp obj
+#--{{{
+      Marshal::load(Marshal::dump(obj))
+#--}}}
     end
-    def pretty obj
-#{{{
-      PP::pp obj, ''
-#}}}
-    end
-#}}}
+#--}}}
   end
 
-
-  Main.new(ARGV).run if $0 == __FILE__
+  Main::new if $0 == __FILE__

data/bin/rlock-1.3.0

@@ -0,0 +1,342 @@
+#!/usr/bin/env ruby
+#
+# built-in
+#
+  require 'optparse'
+  require 'logger'
+#
+# http://raa.ruby-lang.org/project/lockfile/
+#
+  require 'lockfile-1.3.0.rb'
+
+  class Main
+#--{{{
+    VERSION = Lockfile::VERSION 
+
+    USAGE = 
+#--{{{
+  <<-usage
+  NAME
+    rlock v#{ VERSION }
+
+  SYNOPSIS
+    rlock [options]+ lockfile [program [args]+ | -- program options+ [args]+]
+
+  DESCRIPTTION
+    rlock creates NFS safe lockfiles.  it can optionally run a program while
+    holding the lock, ensuring lockfile removal on program exit.  if a program
+    is specified to be run rlock will spawn a background thread to kept the
+    lockfile 'fresh' by touching it at a regular interval.  in this way a lease
+    is maintained on the lockfile and other processes attempting to obtain the
+    lock can determine that it is in use.  see the '--refresh' option for how to
+    control the touch interval.  any other process trying to obtain a lock will
+    automatically remove a stale lockfile; a stale lockfile is one that is older
+    than a certain age.  this age be controled via the '--max_age' option.
+
+  ENVIRONMENT
+    LOCKFILE_DEBUG=1 
+      causes internal actions of the library to be shown on STDERR 
+
+  DIAGNOSTICS
+   rlock attempts to exit with the status of 'program' except where it
+   cannot due to exceptional conditions.  in addition the message 
+
+    'RLOCK SUBCOMMAND FAILURE' 
+    
+    will be printed on STDERR if 'program' exits with non-zero status.
+
+   success => $? == 0
+   failure => $? != 0
+
+  AUTHOR
+   ara.t.howard@noaa.gov
+
+  BUGS
+    1 < bugno && bugno < 42
+
+  OPTIONS
+  usage
+#--}}}
+
+    EXAMPLES =
+#--{{{
+  <<-examples
+  EXAMPLES
+
+    0) simple usage - create lockfile in an atomic fashion (obtain a lock) 
+
+      ~ > rlock lockfile
+
+    1) safe usage - create a lockfile, execute a command, and remove lockfile
+
+      ~ > rlock lockfile ls lockfile
+
+    2) same as above, but logging verbose messages 
+
+      ~ > rlock -v4 lockfile ls lockfile
+   
+    3) same as above, but logging verbose messages and showing actions internal
+    to lockfile library
+
+      ~ > rlock -v4 -d lockfile ls lockfile
+
+    4) same as above
+
+      ~ > LOCKFILE_DEBUG=1 rlock -v4 lockfile ls lockfile
+
+    5) same as above
+
+      ~ > export LOCKFILE_DEBUG=1
+      ~ > rlock -v4 lockfile ls lockfile
+
+    6) you need to tell the option parser to stop parsing rlock options if you
+    intend to pass options to 'program' 
+
+      ~ > rlock -v4 -d lockfile -- ls -ltar lockfile
+
+       without the '--' rlock would consume the '-ltar' option as one of
+       it's own.
+
+    7) lock lockfile and exec 'program' - remove the lockfile if it is older
+    than 4242 seconds
+
+      ~ > rlock --max_age=4242 lockfile program 
+
+    8) lock lockfile and exec 'program' - remove the lockfile if it is older
+    than 4242 seconds, set the refresh rate to be 8 seconds.
+
+      ~ > rlock --max_age=4242 --refresh=8 lockfile program 
+
+    9) same as above, but fail if lockfile cannot be obtained within 1 minute
+
+      ~ > rlock --max_age=4242 --refresh=8 --timeout=60 lockfile program 
+
+    10) lockfile creation involves making some temporary files.  normally these
+    are cleaned up unless rlock is killed with 'kill -9'.  these temp files are
+    normally 'sweeped' - searched for and removed - unless the '--dont_sweep'
+    option is given.  note that sweeping can remove ONLY old temp files created
+    by the same host since there is otherwise no way to tell if the offending
+    process is still running.
+
+    lock lockfile and run program - do not do any sweeping
+
+      ~ > rlock --dont_sweep lockfile program 
+
+  examples
+#--}}}
+
+    EXIT_SUCCESS = 0
+    EXIT_FAILURE = 1
+
+    attr :argv
+    attr :op
+    attr :logger
+    attr :config
+
+    def initialize argv = ARGV
+#--{{{
+      @argv = mcp argv
+      parse_opts
+      if @opt_version
+        puts Main::VERSION
+        exit EXIT_SUCCESS
+      end
+      if @opt_help
+        usage
+        exit EXIT_SUCCESS
+      end
+      parse_argv
+      run
+#--}}}
+    end
+    def run
+#--{{{
+      init_logging
+
+      debug{ "lockpath <#{ @lockpath }>" }
+
+      opts = {}
+      options = 
+        %w(retries max_age sleep_inc min_sleep max_sleep suspend timeout refresh poll_retries poll_max_sleep)
+      options.each do |opt|
+        if((val = eval("opt_#{ opt }")))
+          begin
+            opts[opt] = Integer val 
+            logger.debug{ "<#{ opt }> <#{ val }>" }
+          rescue
+            logger.fatal{ "illegal value <#{ val.inspect }> for opt <#{ opt }>" }
+            exit EXIT_FAILURE
+          end
+        end
+      end
+
+      opts['debug'] = true if opt_debug
+
+      begin
+        case @argv.size
+          when 0
+            opts['dont_clean'] = true
+            logger.debug{ "opts <#{ opts.inspect }>" }
+            logger.debug{ "aquiring lock <#{ @lockpath }>..." }
+          #
+          # simple usage - just create the lockfile with opts
+          #
+            lockfile = ::Lockfile.new @lockpath, opts
+            lockfile.lock
+
+            logger.debug{ "aquired lock <#{ @lockpath }>" }
+          else
+            logger.debug{ "opts <#{ opts.inspect }>" }
+            logger.debug{ "aquiring lock <#{ @lockpath }>..." }
+          #
+          # block usage - create the lockfile with opts, run block, rm lockfile
+          #
+            status = 1
+
+            lockfile = ::Lockfile.new @lockpath, opts
+
+            lockfile.lock do
+              logger.debug{ "aquired lock <#{ @lockpath }>" }
+              logger.debug{ "cmd <#{ @argv.join ' ' }>" }
+              v = nil
+              begin
+                v = $VERBOSE
+                $VERBOSE = nil 
+                STDOUT.flush
+                STDERR.flush
+                fork{ exec(*@argv) }
+                pid, status = Process::wait2
+              ensure
+                $VERBOSE = v
+              end
+              logger.debug{ "status <#{ $? }>" }
+            end
+
+            status = status.exitstatus
+            STDERR.puts "RLOCK SUBCOMMAND FAILURE" unless status == 0
+            exit status
+        end
+      rescue => e
+        logger.fatal{ e }
+        exit EXIT_FAILURE
+      end
+
+      exit EXIT_SUCCESS
+#--}}}
+    end
+    def parse_opts
+#--{{{
+      @op = OptionParser::new
+      @op.banner = ''
+      define_options
+      @op.parse! argv
+
+#--}}}
+    end
+    def parse_argv
+#--{{{
+      usage and exit EXIT_FAILURE if @argv.empty?
+      @lockpath = @argv.shift
+#--}}}
+    end
+    def define_options
+#--{{{
+      options = [
+        ['--retries=n','-r', "default(#{ Lockfile.retries.inspect }) - (nil => forever)"],
+        ['--max_age=n','-a', "default(#{ Lockfile.max_age.inspect })"],
+        ['--sleep_inc=n','-s', "default(#{ Lockfile.sleep_inc.inspect })"],
+        ['--max_sleep=n','-p', "default(#{ Lockfile.max_sleep.inspect })"],
+        ['--min_sleep=n','-P', "default(#{ Lockfile.min_sleep.inspect })"],
+        ['--suspend=n','-u', "default(#{ Lockfile.suspend.inspect })"],
+        ['--timeout=n','-t', "default(#{ Lockfile.timeout.inspect }) - (nil => never)"],
+        ['--refresh=n','-f', "default(#{ Lockfile.refresh.inspect })"],
+        ['--debug','-d', "default(#{ Lockfile.debug.inspect })"],
+        ['--poll_retries=n','-R', "default(#{ Lockfile.poll_retries.inspect })"],
+        ['--poll_max_sleep=n','-S', "default(#{ Lockfile.poll_max_sleep.inspect })"],
+        ['--dont_sweep','-w', "default(#{ Lockfile.dont_sweep.inspect })"],
+
+        ['--version'],
+        ['--verbosity=0-4|debug|info|warn|error|fatal','-v'],
+        ['--log=path','-l'],
+        ['--log_age=log_age'],
+        ['--log_size=log_size'],
+        ['--help','-h'],
+      ]
+      options.each do |option|
+        opt = option.first.gsub(%r/(?:--)|(?:=.*$)/o,'').strip
+        get, set = opt_attr opt
+        @op.def_option(*option){|v| self.send(set, (v or true))}
+      end
+#--}}}
+    end
+    %w(debug info warn error fatal).each do |m|
+      eval "def #{ m }(*args,&block);@logger.#{ m }(*args,&block);end"
+    end
+    def init_logging
+#--{{{
+      if @opt_log_age
+        @opt_log_age = @opt_log_age.to_i if @opt_log_age =~ /\d/
+      end
+      if @opt_log_size
+        @opt_log_size = @opt_log_size.to_i if @opt_log_size =~ /\d/
+      end
+      $logger = @logger = Logger::new(@opt_log || STDERR, @opt_log_age, @opt_log_size)
+
+      level = nil
+      @opt_verbosity ||= 'info'
+      @opt_verbosity =
+        case @opt_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 <#{ @opt_verbosity }>" 
+        end
+      @logger.level = 2 - ((@opt_verbosity % 5) - 2) 
+#--}}}
+    end
+    def usage io = STDOUT
+#--{{{
+      io << USAGE
+      io << "\n"
+      io << @op
+      io << "\n"
+      io << EXAMPLES if defined? EXAMPLES
+      self
+#--}}}
+    end
+    def opt_attr opt
+#--{{{
+      get = "opt_#{ opt }"
+      set = "#{ get }="
+      code = <<-code
+        class << self
+          def #{ get }; defined?(@#{ get }) ? @#{ get } : nil; end
+          def #{ set } value; @#{ get } = value; end
+        end
+      code
+      instance_eval code 
+      [get, set]
+#--}}}
+    end
+    def mcp obj
+#--{{{
+      Marshal::load(Marshal::dump(obj))
+#--}}}
+    end
+#--}}}
+  end
+
+  Main::new if $0 == __FILE__