lockfile 1.1.0

data/BUGS

@@ -0,0 +1,3 @@
+none known
+
+email Ara.T.Howard@noaa.gov with any reports please!

data/README

@@ -0,0 +1,165 @@
+= URLS
+
+http://raa.ruby-lang.org/project/lockfile/
+http://www.codeforpeople.com/lib/ruby/lockfile/
+
+= SYNOPSIS
+
+lib/lockfile.rb : a ruby library for creating NFS safe lockfiles
+
+bin/rlock : ruby command line tool which uses this library to create
+          lockfiles. run 'rlock -h' for more info
+
+= INSTALL
+
+  sudo ruby install.rb
+
+
+= BASIC ALGORITHIM
+
+  * create a globally uniq filename in the same filesystem as the desired
+    lockfile - this can be nfs mounted
+
+  * link(2) this file to the desired lockfile, ignore all errors
+
+  * stat the uniq filename and desired lockfile to determine is they are the
+    same, use only stat.rdev and stat.ino - ignore stat.nlink as NFS can cause
+    this report incorrect values 
+
+  * iff same, you have lock.  either return or run optional code block with
+    optional refresher thread keeping lockfile fresh during execution of code
+    block, ensuring that the lockfile is removed..
+
+  * iff not same try again a few times in rapid succession (poll), then, iff
+    this fails, sleep using incremental backoff time.  optionally remove
+    lockfile if it is older than a certain time, timeout if more than a certain
+    amount of time has passed attempting to lock file.
+
+
+= BASIC USAGE
+
+1)
+    lockfile = Lockfile.new 'file.lock'
+    begin
+      lockfile.lock
+      p 42
+    ensure
+      lockfile.unlock
+    end
+
+
+2)
+    require 'pstore'           # which is NOT nfs safe on it's own
+
+    opts = {                   # the keys can be symbols or strings
+
+      :retries        => nil,  # we will try forever to aquire the lock
+
+      :sleep_inc      => 2,    # we will sleep 2 seconds longer than the
+                               # previous sleep after each retry, cycling from
+                               # min_sleep upto max_sleep downto min_sleep upto
+                               # max_sleep, etc., etc.
+
+      :min_sleep      => 2,    # we will never sleep less than 2 seconds
+
+      :max_sleep      => 32,   # we will never sleep longer than 32 seconds
+
+      :max_age        => 1024, # we will blow away any files found to be older
+                               # than this (lockfile.thief? #=> true)
+
+      :suspend        => 64,   # iff we steal the lock from someone else - wait
+                               # this long to give them a chance to realize it
+
+      :refresh        => 8,    # we will spawn a bg thread that touches file
+                               # every 8 sec.  this thread also causes a
+                               # StolenLockError to be thrown if the lock
+                               # disappears from under us - note that the
+                               # 'detection' rate is limited to the refresh
+                               # interval - this is a race condition
+
+      :timeout        => nil,  # we will wait forever 
+
+      :poll_retries   => 16,   # the initial attempt to grab a lock is done in a
+                               # polling fashion, this number controls how many
+                               # times this is done - the total polling attempts
+                               # are considered ONE actual attempt (see retries
+                               # above)
+
+      :poll_max_sleep => 0.08, # when polling a very brief sleep is issued
+                               # between attempts, this is the upper limit of
+                               # that sleep timeout 
+
+      :debug => true,          # trace execution step on stdout
+    }
+
+    pstore = PStore.new 'file.db'
+    lockfile = Lockfile.new 'file.db.lock', opts 
+    lockfile.lock do
+      pstore.transaction do
+        pstore[:last_update_time] = Time.now
+      end
+    end
+
+3) same as 1 above - Lockfile.new takes a block and ensures unlock is called 
+
+    Lockfile.new('file.lock') do
+      p 42
+    end
+
+4) watch locking algorithim in action
+
+    Lockfile.debug = true
+    Lockfile.new('file.lock') do
+      p 42
+    end
+
+you can also set debugging via the ENV var LOCKFILE_DEBUG, eg.
+
+    ~ > LOCKFILE_DEBUG=true rlock lockfile
+
+= SAMPLES
+
+  * see samples/a.rb
+  * see samples/nfsstore.rb
+  * see bin/rlock
+
+= AUTHOR
+
+-a
+
+= EMAIL
+
+Ara.T.Howard@noaa.gov
+
+= BUGS
+
+> 1
+
+further notifications to email above
+
+= HISTORY
+
+  1.0.1:
+    - fixed bugette in sleep cycle where repeated locks with same lockfile would
+      not reset the cycle at the start of each lock
+  1.0.0:
+    - allow rertries to be nil, meaning to try forever
+    - default timeout is now nil - never timeout
+    - default refresh is now 8
+    - fixed bug where refresher thread was not actually touching lockfile! (ouch)
+    - added cycle method to timeouts
+        1-2-3-2-1-2-3-1...
+      pattern is constructed using min_sleep, sleep_inc, max_sleep
+  0.3.0:
+    - removed use of yaml in favour of hand parsing the lockfile contents, the
+      file as so small it just wasn't worth and i have had one core dump when yaml
+      failed to parse a (corrupt) file
+  0.2.0:
+    - added an initial polling style attempt to grab lock before entering normal
+      sleep/retry loop.  this has really helped performance when lock is under
+      heavy contention: i see almost no sleeping done by any of in the interested
+      processes
+  0.1.0:
+    - added ability of Lockfile.new to accept a block
+  0.0.0:
+    - initial version

data/VERSION

@@ -0,0 +1 @@
+1.1.0

data/bin/rlock

@@ -0,0 +1,326 @@
+#!/usr/bin/env ruby
+
+#
+# builtin
+#
+  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
+#
+  require 'lockfile.rb'
+
+  class Main
+#{{{
+    VERSION = '0.0.0'
+    PROGNAM = File.basename(File.expand_path($0))
+
+    USAGE = 
+#{{{
+  <<-usage
+  NAME
+    #{ PROGNAM } v#{ VERSION }
+
+  SYNOPSIS
+    #{ PROGNAM } [options]+ file.lock [program [-- [options]+] [args]+]
+
+  DESCRIPTTION
+    #{ PROGNAM } creates NFS resistent lockfiles
+
+  ENVIRONMENT
+    LOCKFILE_DEBUG=1 will show internal actions of the library
+
+  DIAGNOSTICS
+   success => $? == 0
+   failure => $? != 0
+
+  AUTHOR
+   ara.t.howard@noaa.gov
+
+  BUGS
+   > 1
+
+  OPTIONS
+  usage
+#}}}
+
+    EXAMPLES =
+#{{{
+  <<-examples
+  EXAMPLES
+
+    0) simple usage - just create a file.lock in an atomic fashion 
+
+      ~ > #{ PROGNAM } file.lock
+
+    1) safe usage - create a file.lock, execute a command, and remove file.lock
+
+      ~ > #{ PROGNAM } file.lock ls file.lock
+
+    2) same as above, but logging verbose messages 
+
+      ~ > #{ PROGNAM } -v4 file.lock ls file.lock
+   
+    3) same as above, but logging verbose messages and showing actions internal to
+       lockfile library
+
+      ~ > #{ PROGNAM } -v4 -d file.lock ls file.lock
+
+    4) same as above
+
+      ~ > LOCKFILE_DEBUG=1 #{ PROGNAM } -v4 file.lock ls file.lock
+
+    5) same as above
+
+      ~ > export LOCKFILE_DEBUG=1
+      ~ > #{ PROGNAM } -v4 file.lock ls file.lock
+
+    6) note that you need to tell the option parser to stop parsing #{ PROGNAM }
+       options if you intend to pass options to 'program' 
+
+      ~ > #{ PROGNAM } -v4 -d file.lock -- ls -ltar file.lock
+
+       without the '--' #{ PROGNAM } would consume the '-ltar' options, parsing it
+       as the logfile name 'tar'
+
+    7) lock file.lock and exec 'program' - remove the file.lock if it is older
+       than 4242 seconds
+
+      ~ > #{ PROGNAM } --max_age=4242 file.lock program 
+
+    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
+
+      ~ > #{ PROGNAM } --max_age=4242 --refresh=8 file.lock program 
+
+    9) same as above, but fail if file.lock cannot be obtained within 1 minute
+
+      ~ > #{ PROGNAM } --max_age=4242 --refresh=8 --timeout=60 file.lock program 
+
+  examples
+#}}}
+
+    EXIT_SUCCESS = 0
+    EXIT_FAILURE = 1
+
+    attr :argv
+    attr :op
+    attr :logger
+    attr :config
+
+    def initialize argv = cp(ARGV)
+#{{{
+      @argv = argv
+      parse_opts
+      parse_argv
+#}}}
+    end
+    def run
+#{{{
+      usage and exit EXIT_SUCCESS if @opt_help
+      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 <#{ pretty opts }>" }
+            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 <#{ pretty opts }>" }
+            logger.debug{ "aquiring lock <#{ @lockpath }>..." }
+          #
+          # block usage - create the lockfile with opts, run block, rm lockfile
+          #
+            lockfile = ::Lockfile.new @lockpath, opts
+            lockfile.lock do
+              logger.debug{ "aquired lock <#{ @lockpath }>" }
+              cmd = @argv.join ' '
+              logger.debug{ "cmd <#{ cmd }>" }
+              v = nil
+              begin
+                v = $VERBOSE
+                $VERBOSE = nil 
+                system cmd 
+              ensure
+                $VERBOSE = v
+              end
+              logger.debug{ "status <#{ $? }>" }
+            end
+            exit $?
+        end
+      rescue => e
+        logger.fatal{ e }
+        exit EXIT_FAILURE
+      end
+
+      exit EXIT_SUCCESS
+#}}}
+    end
+    def parse_opts
+#{{{
+      @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
+
+#}}}
+    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 })"],
+        ['--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 })"],
+
+        ['--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 || $stdout, @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) 
+      debug {"logging level <#{ level }>"}
+#}}}
+    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 cp obj
+#{{{
+      Marshal.load(Marshal.dump(obj))
+#}}}
+    end
+    def pretty obj
+#{{{
+      PP::pp obj, ''
+#}}}
+    end
+#}}}
+  end
+
+
+  Main.new(ARGV).run if $0 == __FILE__