lockfile 1.4.0 → 1.4.1

data/README

@@ -0,0 +1,221 @@
+URLS
+
+  http://rubyforge.org/projects/codeforpeople/
+  http://codeforpeople.com/lib/ruby/lockfile/
+  http://raa.ruby-lang.org/project/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
+              and to run arbitrary commands while holding them. 
+
+              for example
+
+                rlock lockfile -- cp -r huge/ huge.bak/
+              
+              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 
+
+      :dont_clean     => false, # normally a finalizer is defined to clean up
+                                # after lockfiles, settin this to true prevents this 
+
+      :dont_sweep     => false, # normally locking causes a sweep to be made.  a
+                                # sweep removes any old tmp files created by
+                                # processes of this host only which are no
+                                # longer alive
+
+      :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 (debugging only)
+
+      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
+
+  5) simplified interface : no lockfile object required
+
+      Lockfile('lock', :retries => 0) do
+        puts 'only one instance running!'
+      end
+
+
+SAMPLES
+
+  * see samples/a.rb
+  * see samples/nfsstore.rb
+  * see samples/lock.sh
+  * see bin/rlock
+
+AUTHOR
+
+  Ara T. Howard
+
+EMAIL
+
+  Ara.T.Howard@noaa.gov
+
+BUGS
+
+  bugno > 1 && bugno < 42
+
+HISTORY
+
+  1.4.1:
+    - Mike Kasick <mkasick@club.cc.cmu.edu> reported a bug whereby false/nil
+      values for options were ignored.  patched to address this bug
+    - added Lockfile method for high level interface sans lockfile object
+    - updated rlock program to allow nil/true/false values passed on command
+      line.  eg
+
+        rlock --max_age=nil lockfile -- date --iso-8601=seconds
+
+  1.4.0:
+    - gem'd up
+    - added Lockfile::create method which atomically creates a file and opens
+      it: 
+
+        Lockfile::create("atomic_even_on_nfs", "r+") do |f|
+          f.puts 42
+        end
+
+      arguments are the same as those for File::open.  note that there is no way
+      to accomplish this otherwise since File::O_EXCL fails silently on nfs,
+      flock does not work on nfs, and posixlock (see raa) can only lock a file
+      after it is open so the open itself is still a race.
+
+  1.3.0:
+    - added sweep functionality.  hosts can clean up any tmp files left around
+      by other processes that may have been killed using -9 to prevent proper
+      clean up.  it is only possible to clean up after processes on the same
+      host as there is no other way to determine if the process that created the
+      file is alive.  in summary - hosts clean up after other processes on that
+      same host if needed.
+    - added attempt/try_again methods
+  1.2.0:
+    - fixed bug where stale locks not removed when retries == 0
+  1.1.0
+    - unfortunately i've forgotten
+  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/bin/rlock

@@ -7,7 +7,7 @@
 #
 # http://raa.ruby-lang.org/project/lockfile/
 #
-  require 'lockfile-1.3.0.rb'
+  require 'lockfile-1.4.1.rb'
 
   class Main
 #--{{{
@@ -159,10 +159,12 @@
       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 }")))
+        #if((val = eval("opt_#{ opt }")))
+        if(send("opt_#{ opt }?"))
+          val = send "opt_#{ opt }"
           begin
-            opts[opt] = Integer val 
-            logger.debug{ "<#{ opt }> <#{ val }>" }
+            val = (opts[opt] = String === val ? Integer(val) : val)
+            logger.debug{ "<#{ opt }> <#{ val.inspect }>" }
           rescue
             logger.fatal{ "illegal value <#{ val.inspect }> for opt <#{ opt }>" }
             exit EXIT_FAILURE
@@ -265,7 +267,21 @@
       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))}
+        value4 = lambda do |v|
+          case v
+            when NilClass, %r/^t|true$/i
+              true
+            when %r/^f|false$/i
+              false
+            when %r/^nil|nul|null$/i
+              nil
+            else
+              v
+          end
+        end
+        @op.def_option(*option) do |v|
+          send set, value4[v]
+        end
       end
 #--}}}
     end
@@ -319,10 +335,12 @@
     end
     def opt_attr opt
 #--{{{
+      query = "opt_#{ opt }?"
       get = "opt_#{ opt }"
       set = "#{ get }="
       code = <<-code
         class << self
+          def #{ query }; defined? @#{ get }; end
           def #{ get }; defined?(@#{ get }) ? @#{ get } : nil; end
           def #{ set } value; @#{ get } = value; end
         end

data/bin/{rlock-1.3.0 → rlock-1.4.1}

@@ -7,7 +7,7 @@
 #
 # http://raa.ruby-lang.org/project/lockfile/
 #
-  require 'lockfile-1.3.0.rb'
+  require 'lockfile-1.4.1.rb'
 
   class Main
 #--{{{
@@ -159,10 +159,12 @@
       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 }")))
+        #if((val = eval("opt_#{ opt }")))
+        if(send("opt_#{ opt }?"))
+          val = send "opt_#{ opt }"
           begin
-            opts[opt] = Integer val 
-            logger.debug{ "<#{ opt }> <#{ val }>" }
+            val = (opts[opt] = String === val ? Integer(val) : val)
+            logger.debug{ "<#{ opt }> <#{ val.inspect }>" }
           rescue
             logger.fatal{ "illegal value <#{ val.inspect }> for opt <#{ opt }>" }
             exit EXIT_FAILURE
@@ -265,7 +267,21 @@
       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))}
+        value4 = lambda do |v|
+          case v
+            when NilClass, %r/^t|true$/i
+              true
+            when %r/^f|false$/i
+              false
+            when %r/^nil|nul|null$/i
+              nil
+            else
+              v
+          end
+        end
+        @op.def_option(*option) do |v|
+          send set, value4[v]
+        end
       end
 #--}}}
     end
@@ -319,10 +335,12 @@
     end
     def opt_attr opt
 #--{{{
+      query = "opt_#{ opt }?"
       get = "opt_#{ opt }"
       set = "#{ get }="
       code = <<-code
         class << self
+          def #{ query }; defined? @#{ get }; end
           def #{ get }; defined?(@#{ get }) ? @#{ get } : nil; end
           def #{ set } value; @#{ get } = value; end
         end

data/doc/rlock.help

@@ -0,0 +1,95 @@
+  NAME
+    rlock v1.3.0
+
+  SYNOPSIS
+    rlock [options]+ file.lock [program [-- [options]+] [args]+]
+
+  DESCRIPTTION
+    rlock 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
+
+
+    -r, --retries=n                  default(nil) - (nil => forever)
+    -a, --max_age=n                  default(1024)
+    -s, --sleep_inc=n                default(2)
+    -p, --max_sleep=n                default(32)
+    -P, --min_sleep=n                default(2)
+    -u, --suspend=n                  default(64)
+    -t, --timeout=n                  default(nil) - (nil => never)
+    -f, --refresh=n                  default(8)
+    -d, --debug                      default(false)
+    -R, --poll_retries=n             default(16)
+    -S, --poll_max_sleep=n           default(0.08)
+    -w, --dont_sweep                 default(false)
+    -v=0-4|debug|info|warn|error|fatal
+        --verbosity
+    -l, --log=path
+        --log_age=log_age
+        --log_size=log_size
+    -h, --help
+
+  EXAMPLES
+
+    0) simple usage - just create a file.lock in an atomic fashion 
+
+      ~ > rlock file.lock
+
+    1) safe usage - create a file.lock, execute a command, and remove file.lock
+
+      ~ > rlock file.lock ls file.lock
+
+    2) same as above, but logging verbose messages 
+
+      ~ > rlock -v4 file.lock ls file.lock
+   
+    3) same as above, but logging verbose messages and showing actions internal to
+       lockfile library
+
+      ~ > rlock -v4 -d file.lock ls file.lock
+
+    4) same as above
+
+      ~ > LOCKFILE_DEBUG=1 rlock -v4 file.lock ls file.lock
+
+    5) same as above
+
+      ~ > export LOCKFILE_DEBUG=1
+      ~ > rlock -v4 file.lock ls file.lock
+
+    6) note that you need to tell the option parser to stop parsing rlock
+       options if you intend to pass options to 'program' 
+
+      ~ > rlock -v4 -d file.lock -- ls -ltar file.lock
+
+       without the '--' rlock 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
+
+      ~ > rlock --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
+
+      ~ > rlock --max_age=4242 --refresh=8 file.lock program 
+
+    9) same as above, but fail if file.lock cannot be obtained within 1 minute
+
+      ~ > rlock --max_age=4242 --refresh=8 --timeout=60 file.lock program 
+

data/gemspec.rb

@@ -0,0 +1,23 @@
+lib, version = File::basename(File::dirname(File::expand_path(__FILE__))).split %r/-/, 2
+
+require 'rubygems'
+
+Gem::Specification::new do |spec|
+  spec.name = lib 
+  spec.version = version 
+  spec.platform = Gem::Platform::RUBY
+  spec.summary = lib 
+
+  spec.files = Dir::glob "**/**"
+  spec.executables = Dir::glob("bin/*").map{|exe| File::basename exe}
+  
+  spec.require_path = "lib" 
+  spec.autorequire = lib
+
+  spec.has_rdoc = File::exist? "doc" 
+  spec.test_suite_file = "test/#{ lib }.rb" if File::directory? "test"
+
+  spec.author = "Ara T. Howard"
+  spec.email = "ara.t.howard@noaa.gov"
+  spec.homepage = "http://codeforpeople.com/lib/ruby/#{ lib }/"
+end

data/install.rb

@@ -0,0 +1,206 @@
+#!/usr/bin/env ruby
+require 'rbconfig'
+require 'find'
+require 'ftools'
+require 'tempfile'
+include Config
+
+LIBDIR      = "lib"
+LIBDIR_MODE = 0644
+
+BINDIR      = "bin"
+BINDIR_MODE = 0755
+
+
+$srcdir            = CONFIG["srcdir"]
+$version           = CONFIG["MAJOR"]+"."+CONFIG["MINOR"]
+$libdir            = File.join(CONFIG["libdir"], "ruby", $version)
+$archdir           = File.join($libdir, CONFIG["arch"])
+$site_libdir       = $:.find {|x| x =~ /site_ruby$/}
+$bindir            = CONFIG["bindir"] || CONFIG['BINDIR']
+$ruby_install_name = CONFIG['ruby_install_name'] || CONFIG['RUBY_INSTALL_NAME'] || 'ruby'
+$ruby_ext          = CONFIG['EXEEXT'] || ''
+$ruby              = File.join($bindir, ($ruby_install_name + $ruby_ext))
+
+if !$site_libdir
+  $site_libdir = File.join($libdir, "site_ruby")
+elsif $site_libdir !~ %r/#{Regexp.quote($version)}/
+  $site_libdir = File.join($site_libdir, $version)
+end
+
+def install_rb(srcdir=nil, destdir=nil, mode=nil, bin=nil)
+#{{{
+  path   = []
+  dir    = []
+  Find.find(srcdir) do |f|
+    next unless FileTest.file?(f)
+    next if (f = f[srcdir.length+1..-1]) == nil
+    next if (/CVS$/ =~ File.dirname(f))
+    next if f =~ %r/\.lnk/
+    path.push f
+    dir |= [File.dirname(f)]
+  end
+  for f in dir
+    next if f == "."
+    next if f == "CVS"
+    File::makedirs(File.join(destdir, f))
+  end
+  for f in path
+    next if (/\~$/ =~ f)
+    next if (/^\./ =~ File.basename(f))
+    unless bin
+      File::install(File.join(srcdir, f), File.join(destdir, f), mode, true)
+    else
+      from = File.join(srcdir, f)
+      to = File.join(destdir, f)
+      shebangify(from) do |sf|
+        $deferr.print from, " -> ", File::catname(from, to), "\n"
+        $deferr.printf "chmod %04o %s\n", mode, to 
+        File::install(sf, to, mode, false)
+      end
+    end
+  end
+#}}}
+end
+def shebangify f
+#{{{
+  open(f) do |fd|
+    buf = fd.read 42 
+    if buf =~ %r/^\s*#\s*!.*ruby/o
+      ftmp = Tempfile::new("#{ $$ }_#{ File::basename(f) }")
+      begin
+        fd.rewind
+        ftmp.puts "#!#{ $ruby  }"
+        while((buf = fd.read(8192)))
+          ftmp.write buf
+        end
+        ftmp.close
+        yield ftmp.path
+      ensure
+        ftmp.close!
+      end
+    else
+      yield f
+    end
+  end
+#}}}
+end
+def ARGV.switch
+#{{{
+  return nil if self.empty?
+  arg = self.shift
+  return nil if arg == '--'
+  if arg =~ /^-(.)(.*)/
+    return arg if $1 == '-'
+    raise 'unknown switch "-"' if $2.index('-')
+    self.unshift "-#{$2}" if $2.size > 0
+    "-#{$1}"
+  else
+    self.unshift arg
+    nil
+  end
+#}}}
+end
+def ARGV.req_arg
+#{{{
+  self.shift || raise('missing argument')
+#}}}
+end
+def linkify d, linked = []
+#--{{{
+  if test ?d, d
+    versioned = Dir[ File::join(d, "*-[0-9].[0-9].[0-9].rb") ]
+    versioned.each do |v| 
+      src, dst = v, v.gsub(%r/\-[\d\.]+\.rb$/, '.rb')
+      lnk = nil
+      begin
+        if test ?l, dst
+          lnk = "#{ dst }.lnk"
+          puts "#{ dst } -> #{ lnk }"
+          File::rename dst, lnk
+        end
+        unless test ?e, dst
+          puts "#{ src } -> #{ dst }"
+          File::copy src, dst 
+          linked << dst
+        end
+      ensure
+        if lnk
+          at_exit do
+            puts "#{ lnk } -> #{ dst }"
+            File::rename lnk, dst
+          end
+        end
+      end
+    end
+  end
+  linked
+#--}}}
+end
+
+
+#
+# main program
+#
+
+libdir = $site_libdir
+bindir = $bindir
+no_linkify = false
+linked = nil
+help = false
+
+usage = <<-usage
+  #{ File::basename $0 }
+    -d, --destdir    <destdir>
+    -l, --libdir     <libdir>
+    -b, --bindir     <bindir>
+    -r, --ruby       <ruby>
+    -n, --no_linkify
+    -s, --sudo
+    -h, --help
+usage
+
+begin
+  while switch = ARGV.switch
+    case switch
+    when '-d', '--destdir'
+      libdir = ARGV.req_arg
+    when '-l', '--libdir'
+      libdir = ARGV.req_arg
+    when '-b', '--bindir'
+      bindir = ARGV.req_arg
+    when '-r', '--ruby'
+      $ruby = ARGV.req_arg
+    when '-n', '--no_linkify'
+      no_linkify = true
+    when '-s', '--sudo'
+      sudo = 'sudo' 
+    when '-h', '--help'
+      help = true
+    else
+      raise "unknown switch #{switch.dump}"
+    end
+  end
+rescue
+  STDERR.puts $!.to_s
+  STDERR.puts usage
+  exit 1
+end    
+
+if help
+  STDOUT.puts usage
+  exit
+end
+
+unless no_linkify
+  linked = linkify('lib') + linkify('bin')
+end
+
+system "#{ $ruby } extconf.rb && make && #{ sudo } make install" if test(?s, 'extconf.rb')
+
+install_rb(LIBDIR, libdir, LIBDIR_MODE)
+install_rb(BINDIR, bindir, BINDIR_MODE, bin=true)
+
+if linked
+  linked.each{|path| File::rm_f path}
+end

data/lib/{lockfile-1.4.0.rb → lockfile-1.4.1.rb}

@@ -5,7 +5,7 @@ unless defined? $__lockfile__
 
   class Lockfile
 #--{{{
-    VERSION = '1.4.0'
+    VERSION = '1.4.1'
 
     class LockError < StandardError; end
     class StolenLockError < LockError; end
@@ -171,21 +171,20 @@ unless defined? $__lockfile__
       @path  = path
       @opts  = opts
 
-      @retries          = getopt('retries') || @klass.retries
-      @max_age          = getopt('max_age') || @klass.max_age
-      @sleep_inc        = getopt('sleep_inc') || @klass.sleep_inc
-      @min_sleep        = getopt('min_sleep') || @klass.min_sleep
-      @max_sleep        = getopt('max_sleep') || @klass.max_sleep
-      @suspend          = getopt('suspend') || @klass.suspend
-      @timeout          = getopt('timeout') || @klass.timeout
-      @refresh          = getopt('refresh') || @klass.refresh
-      @dont_clean       = getopt('dont_clean') || @klass.dont_clean
-      @poll_retries     = getopt('poll_retries') || @klass.poll_retries
-      @poll_max_sleep   = getopt('poll_max_sleep') || @klass.poll_max_sleep
-      @dont_sweep       = getopt('dont_sweep') || @klass.dont_sweep
-      @dont_use_lock_id = getopt('dont_use_lock_id') || @klass.dont_use_lock_id
-
-      @debug          = getopt('debug') || @klass.debug
+      @retries          = getopt 'retries'          , @klass.retries
+      @max_age          = getopt 'max_age'          , @klass.max_age
+      @sleep_inc        = getopt 'sleep_inc'        , @klass.sleep_inc
+      @min_sleep        = getopt 'min_sleep'        , @klass.min_sleep
+      @max_sleep        = getopt 'max_sleep'        , @klass.max_sleep
+      @suspend          = getopt 'suspend'          , @klass.suspend
+      @timeout          = getopt 'timeout'          , @klass.timeout
+      @refresh          = getopt 'refresh'          , @klass.refresh
+      @dont_clean       = getopt 'dont_clean'       , @klass.dont_clean
+      @poll_retries     = getopt 'poll_retries'     , @klass.poll_retries
+      @poll_max_sleep   = getopt 'poll_max_sleep'   , @klass.poll_max_sleep
+      @dont_sweep       = getopt 'dont_sweep'       , @klass.dont_sweep
+      @dont_use_lock_id = getopt 'dont_use_lock_id' , @klass.dont_use_lock_id
+      @debug            = getopt 'debug'            , @klass.debug
 
       @sleep_cycle = SleepCycle::new @min_sleep, @max_sleep, @sleep_inc 
 
@@ -508,9 +507,12 @@ unless defined? $__lockfile__
       FileUtils.touch path
 #--}}}
     end
-    def getopt key
+    def getopt key, default = nil
 #--{{{
-      @opts[key] || @opts[key.to_s] || @opts[key.to_s.intern]
+      [ key, key.to_s, key.to_s.intern ].each do |k|
+        return @opts[k] if @opts.has_key?(k)
+      end
+      return default
 #--}}}
     end
     def to_str
@@ -550,5 +552,11 @@ unless defined? $__lockfile__
 #--}}}
   end
 
+  def Lockfile path, *a, &b
+#--{{{
+    Lockfile.new(path, *a, &b)
+#--}}}
+  end
+
   $__lockfile__ == __FILE__ 
 end

data/lib/lockfile.rb

@@ -5,7 +5,7 @@ unless defined? $__lockfile__
 
   class Lockfile
 #--{{{
-    VERSION = '1.4.0'
+    VERSION = '1.4.1'
 
     class LockError < StandardError; end
     class StolenLockError < LockError; end
@@ -171,21 +171,20 @@ unless defined? $__lockfile__
       @path  = path
       @opts  = opts
 
-      @retries          = getopt('retries') || @klass.retries
-      @max_age          = getopt('max_age') || @klass.max_age
-      @sleep_inc        = getopt('sleep_inc') || @klass.sleep_inc
-      @min_sleep        = getopt('min_sleep') || @klass.min_sleep
-      @max_sleep        = getopt('max_sleep') || @klass.max_sleep
-      @suspend          = getopt('suspend') || @klass.suspend
-      @timeout          = getopt('timeout') || @klass.timeout
-      @refresh          = getopt('refresh') || @klass.refresh
-      @dont_clean       = getopt('dont_clean') || @klass.dont_clean
-      @poll_retries     = getopt('poll_retries') || @klass.poll_retries
-      @poll_max_sleep   = getopt('poll_max_sleep') || @klass.poll_max_sleep
-      @dont_sweep       = getopt('dont_sweep') || @klass.dont_sweep
-      @dont_use_lock_id = getopt('dont_use_lock_id') || @klass.dont_use_lock_id
-
-      @debug          = getopt('debug') || @klass.debug
+      @retries          = getopt 'retries'          , @klass.retries
+      @max_age          = getopt 'max_age'          , @klass.max_age
+      @sleep_inc        = getopt 'sleep_inc'        , @klass.sleep_inc
+      @min_sleep        = getopt 'min_sleep'        , @klass.min_sleep
+      @max_sleep        = getopt 'max_sleep'        , @klass.max_sleep
+      @suspend          = getopt 'suspend'          , @klass.suspend
+      @timeout          = getopt 'timeout'          , @klass.timeout
+      @refresh          = getopt 'refresh'          , @klass.refresh
+      @dont_clean       = getopt 'dont_clean'       , @klass.dont_clean
+      @poll_retries     = getopt 'poll_retries'     , @klass.poll_retries
+      @poll_max_sleep   = getopt 'poll_max_sleep'   , @klass.poll_max_sleep
+      @dont_sweep       = getopt 'dont_sweep'       , @klass.dont_sweep
+      @dont_use_lock_id = getopt 'dont_use_lock_id' , @klass.dont_use_lock_id
+      @debug            = getopt 'debug'            , @klass.debug
 
       @sleep_cycle = SleepCycle::new @min_sleep, @max_sleep, @sleep_inc 
 
@@ -508,9 +507,12 @@ unless defined? $__lockfile__
       FileUtils.touch path
 #--}}}
     end
-    def getopt key
+    def getopt key, default = nil
 #--{{{
-      @opts[key] || @opts[key.to_s] || @opts[key.to_s.intern]
+      [ key, key.to_s, key.to_s.intern ].each do |k|
+        return @opts[k] if @opts.has_key?(k)
+      end
+      return default
 #--}}}
     end
     def to_str
@@ -550,5 +552,11 @@ unless defined? $__lockfile__
 #--}}}
   end
 
+  def Lockfile path, *a, &b
+#--{{{
+    Lockfile.new(path, *a, &b)
+#--}}}
+  end
+
   $__lockfile__ == __FILE__ 
 end

data/rlock

@@ -0,0 +1,2 @@
+#!/bin/sh
+RUBYLIB=./lib ./bin/rlock "$@"

data/samples/a.rb

@@ -0,0 +1,112 @@
+#!/usr/bin/env ruby
+$:.unshift '../lib'
+#
+# puts this script in an nfs located directory and run from a couple of nodes at
+# once.  the list should appear ordered from either host - note that times may
+# not be ordered depending on the system clocks
+#
+
+#
+# builtin
+#
+  require 'socket'
+  require 'pstore'
+#
+# do what we can to invalidate any nfs caching
+#
+  def timestamp time = Time.now
+#{{{
+    usec = "#{ time.usec }"
+    usec << ('0' * (6 - usec.size)) if usec.size < 6 
+    time.strftime('%Y-%m-%d %H:%M:%S.') << usec
+#}}}
+  end
+  def hostname
+#{{{
+    @__hostname__ ||= Socket::gethostname
+#}}}
+  end
+  def tmpnam dir = Dir.tmpdir, seed = File.basename($0)
+#{{{
+    pid = Process.pid
+    path = "%s_%s_%s_%s_%d" % 
+      [hostname, seed, pid, timestamp.gsub(/\s+/o,'_'), rand(101010)]
+    File.join(dir, path)
+#}}}
+  end
+  def uncache file 
+#{{{
+    refresh = nil
+    begin
+      is_a_file = File === file
+      path = (is_a_file ? file.path : file.to_s) 
+      stat = (is_a_file ? file.stat : File.stat(file.to_s)) 
+      refresh = tmpnam(File.dirname(path))
+      File.link path, refresh rescue File.symlink path, refresh
+      File.chmod stat.mode, path
+      File.utime stat.atime, stat.mtime, path
+    ensure 
+      begin
+        File.unlink refresh if refresh
+      rescue Errno::ENOENT
+      end
+    end
+#}}}
+  end
+#
+# raa - http://raa.ruby-lang.org/project/lockfile/
+#
+  require 'lockfile'
+  pstore = PStore.new 'test.db'
+  timeout = 60
+  max_age = 8
+  refresh = 2
+  debug = false
+  lockfile = Lockfile.new 'test.lock', 
+                          :timeout => timeout,
+                          :max_age => max_age,
+                          :refresh => refresh,
+                          :debug   => debug
+#
+# flock throws ENOLCK on nfs file systems in newer linux kernels
+# plus we want to show that lockfile alone can do the locking
+#
+  class File
+    def flock(*args,&block);true;end
+  end
+#
+# if locking does not work this loop will blow up (Marshal load error) or appear
+# un-ordered.  actually it will eventually blow up due to nfs caching - but that
+# is not the fault of the lockfile class!  for the most part it is a simply demo
+# of locking.  the file will never become corrupt, it just will be unreadable at
+# times due to kernel caching.
+#
+  loop do
+    lockfile.lock do
+      uncache pstore.path 
+      pstore.transaction do
+      #
+      # get/update list
+      #
+        pstore[:list] = [] unless pstore.root? :list
+        list = pstore[:list]
+        tuple = [list.size, hostname, Time.now.to_f]
+        list << tuple
+      #
+      # show last 16 elements
+      #
+        puts '---'
+        list[-([list.size, 16].min)..-1].each{|tuple| p tuple}
+        puts '---'
+      #
+      # keep it a reasonable size
+      #
+        list.shift while list.size > 1024
+      #
+      # write back updates
+      #
+        pstore[:list] = list
+      end
+    end
+    sleep 1 
+  end

data/samples/lock

@@ -0,0 +1,4 @@
+host: jib.ngdc.noaa.gov
+pid: 18176
+ppid: 5245
+time: 2004-11-18 14:40:43.218731

data/samples/lock.sh

@@ -0,0 +1,13 @@
+#!/bin/sh
+
+export RUBYLIB="../lib:./lib"
+
+export PATH="../bin:./bin:$PATH"
+
+#export LOCKFILE_DEBUG=1
+
+(r=`ruby -e 'p(rand(2))'`; sleep $r; rlock ./lockfile 'sleep 1; printf "\n$$ aquired lock @ `date`\n\n"') &
+(r=`ruby -e 'p(rand(2))'`; sleep $r; rlock ./lockfile 'sleep 1; printf "\n$$ aquired lock @ `date`\n\n"') &
+(r=`ruby -e 'p(rand(2))'`; sleep $r; rlock ./lockfile 'sleep 1; printf "\n$$ aquired lock @ `date`\n\n"') &
+
+wait

data/samples/lockfile

@@ -0,0 +1,4 @@
+host: jib.ngdc.noaa.gov
+pid: 18193
+ppid: 5245
+time: 2004-11-18 14:41:59.320552

data/samples/nfsstore.rb

@@ -0,0 +1,203 @@
+#
+# How to use:
+#
+# db = NFSStore.new("/tmp/foo")
+# db.transaction do
+#   p db.roots
+#   ary = db["root"] = [1,2,3,4]
+#   ary[0] = [1,1.5]
+# end
+
+# db.transaction do
+#   p db["root"]
+# end
+
+require "ftools"
+require "digest/md5"
+require "socket"
+
+require 'lockfile'
+
+class NFSStore
+  HOSTNAME = Socket::gethostname
+  class Error < StandardError
+  end
+
+  def initialize(file)
+    dir = File::dirname(file)
+    unless File::directory? dir
+      raise NFSStore::Error, format("directory %s does not exist", dir)
+    end
+    if File::exist? file and not File::readable? file
+      raise NFSStore::Error, format("file %s not readable", file)
+    end
+    @transaction = false
+    @filename = file
+    @lockfile = Lockfile.new "#{ @filename }.lock",:max_age=>64,:refresh=>8
+    @abort = false
+  end
+
+  def in_transaction
+    raise NFSStore::Error, "not in transaction" unless @transaction
+  end
+  private :in_transaction
+
+  def [](name)
+    in_transaction
+    @table[name]
+  end
+  def fetch(name, default=NFSStore::Error)
+    unless @table.key? name
+      if default==NFSStore::Error
+	raise NFSStore::Error, format("undefined root name `%s'", name)
+      else
+	default
+      end
+    end
+    self[name]
+  end
+  def []=(name, value)
+    in_transaction
+    @table[name] = value
+  end
+  def delete(name)
+    in_transaction
+    @table.delete name
+  end
+  def roots
+    in_transaction
+    @table.keys
+  end
+  def root?(name)
+    in_transaction
+    @table.key? name
+  end
+  def path
+    @filename
+  end
+  def commit
+    in_transaction
+    @abort = false
+    throw :pstore_abort_transaction
+  end
+  def abort
+    in_transaction
+    @abort = true
+    throw :pstore_abort_transaction
+  end
+
+  # do what we can to invalidate any nfs caching
+  def uncache file 
+    begin
+      stat = file.stat
+      path = file.path
+      refresh = "%s.%s.%s.%s" % [path, HOSTNAME, $$, Time.now.to_i % 1024] 
+      File.link path, refresh
+      file.chmod stat.mode
+      File.utime stat.atime, stat.mtime, path
+    rescue Exception => e 
+      warn e
+    ensure
+      begin
+        File.unlink refresh if File.exist? refresh
+      rescue Exception => e
+        warn e
+      end
+    end
+  end
+
+
+  def transaction(read_only=false)
+    raise NFSStore::Error, "nested transaction" if @transaction
+    file = nil
+    value = nil
+
+@lockfile.lock do
+      begin
+        @transaction = true
+        backup = @filename+"~"
+        begin
+          file = File::open(@filename, read_only ? "rb" : "rb+")
+          orig = true
+        rescue Errno::ENOENT
+          raise if read_only
+          file = File::open(@filename, "wb+")
+        end
+        #file.flock(read_only ? File::LOCK_SH : File::LOCK_EX)
+        uncache file
+        file.rewind
+        if read_only
+          @table = Marshal::load(file)
+        elsif orig and (content = file.read) != ""
+          @table = Marshal::load(content)
+          size = content.size
+          md5 = Digest::MD5.digest(content)
+          content = nil		# unreference huge data
+        else
+          @table = {}
+        end
+        begin
+          catch(:pstore_abort_transaction) do
+            value = yield(self)
+          end
+        rescue Exception
+          @abort = true
+          raise
+        ensure
+          if !read_only and !@abort
+            file.rewind
+            content = Marshal::dump(@table)
+            if !md5 || size != content.size || md5 != Digest::MD5.digest(content)
+              File::copy @filename, backup
+              begin
+                file.write(content)
+                file.truncate(file.pos)
+                content = nil		# unreference huge data
+              rescue
+                File::rename backup, @filename if File::exist?(backup)
+                raise
+              end
+            end
+          end
+          if @abort and !orig
+            File.unlink(@filename)
+          end
+          @abort = false
+        end
+      ensure
+        @table = nil
+        @transaction = false
+        file.close if file
+      end
+end
+      value
+  end
+end
+
+
+
+
+
+
+
+
+
+if __FILE__ == $0
+  db = NFSStore.new("/tmp/foo")
+  db.transaction do
+    p db.roots
+    ary = db["root"] = [1,2,3,4]
+    ary[1] = [1,1.5]
+  end
+
+  1000.times do
+    db.transaction do
+      db["root"][0] += 1
+      p db["root"][0]
+    end
+  end
+
+  db.transaction(true) do
+    p db["root"]
+  end
+end

data/samples/out

@@ -0,0 +1,80 @@
+lock_id <
+{"pid"=>"15681", "time"=>"2004-11-16 17:08:42.931418", "host"=>"jib.ngdc.noaa.gov", "ppid"=>"15674"}
+>
+attempting to lock <./lockfile>...
+polling attempt <0>...
+aquired lock <./lockfile>
+touched <./lockfile> @ <1100650122.93628>
+loaded <
+{"pid"=>"15681", "time"=>"2004-11-16 17:08:42.931418", "host"=>"jib.ngdc.noaa.gov", "ppid"=>"15674"}
+>
+
+
+
+15682 aquired lock @ Tue Nov 16 17:08:43 MST 2004
+
+
+lock_id <
+{"pid"=>"15685", "time"=>"2004-11-16 17:08:43.962744", "host"=>"jib.ngdc.noaa.gov", "ppid"=>"15676"}
+>
+attempting to lock <./lockfile>...
+polling attempt <0>...
+poll sleep <0.08>...
+lock_id <
+{"pid"=>"15684", "time"=>"2004-11-16 17:08:43.964636", "host"=>"jib.ngdc.noaa.gov", "ppid"=>"15672"}
+>
+attempting to lock <./lockfile>...
+polling attempt <0>...
+poll sleep <0.08>...
+polling attempt <1>...polling attempt <1>...
+
+aquired lock <./lockfile>
+poll sleep <0.08>...
+touched <./lockfile> @ <1100650124.04751>
+loaded <
+{"pid"=>"15685", "time"=>"2004-11-16 17:08:43.962744", "host"=>"jib.ngdc.noaa.gov", "ppid"=>"15676"}
+>
+polling attempt <2>...
+poll sleep <0.08>...
+polling attempt <3>...
+poll sleep <0.08>...
+polling attempt <4>...
+poll sleep <0.08>...
+polling attempt <5>...
+poll sleep <0.08>...
+polling attempt <6>...
+poll sleep <0.08>...
+polling attempt <7>...
+poll sleep <0.08>...
+polling attempt <8>...
+poll sleep <0.08>...
+polling attempt <9>...
+poll sleep <0.08>...
+polling attempt <10>...
+poll sleep <0.08>...
+polling attempt <11>...
+poll sleep <0.08>...
+polling attempt <12>...
+poll sleep <0.08>...
+polling attempt <13>...
+poll sleep <0.08>...
+
+
+
+15690 aquired lock @ Tue Nov 16 17:08:45 MST 2004
+
+
+polling attempt <14>...
+poll sleep <0.08>...
+polling attempt <15>...
+aquired lock <./lockfile>
+touched <./lockfile> @ <1100650125.16655>
+loaded <
+{"pid"=>"15684", "time"=>"2004-11-16 17:08:43.964636", "host"=>"jib.ngdc.noaa.gov", "ppid"=>"15672"}
+>
+
+
+
+15694 aquired lock @ Tue Nov 16 17:08:46 MST 2004
+
+

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: lockfile
 version: !ruby/object:Gem::Version 
-  version: 1.4.0
-date: 2005-11-10 00:00:00.000000 -07:00
+  version: 1.4.1
+date: 2007-01-04 00:00:00.000000 -07:00
 summary: lockfile
 require_paths: 
   - lib
@@ -29,14 +29,31 @@ cert_chain:
 authors: 
   - Ara T. Howard
 files: 
+  - install.rb
+  - README
+  - rlock
+  - lib
+  - bin
+  - samples
+  - doc
+  - gemspec.rb
   - lib/lockfile.rb
-  - lib/lockfile-1.4.0.rb
+  - lib/lockfile-1.4.1.rb
   - bin/rlock
-  - bin/rlock-1.3.0
+  - bin/rlock-1.4.1
+  - samples/a.rb
+  - samples/nfsstore.rb
+  - samples/out
+  - samples/lock.sh
+  - samples/lock
+  - samples/lockfile
+  - doc/rlock.help
 test_files: []
 rdoc_options: []
 extra_rdoc_files: []
-executables: []
+executables: 
+  - rlock
+  - rlock-1.4.1
 extensions: []
 requirements: []
 dependencies: []