lockfile 1.4.3 → 2.0.1

data/lockfile.gemspec

@@ -0,0 +1,46 @@
+## lockfile.gemspec
+#
+
+Gem::Specification::new do |spec|
+  spec.name = "lockfile"
+  spec.version = "2.0.1"
+  spec.platform = Gem::Platform::RUBY
+  spec.summary = "lockfile"
+  spec.description = "a ruby library for creating perfect and NFS safe lockfiles"
+  spec.license = "same as ruby's"
+
+  spec.files =
+["README",
+ "bin",
+ "bin/rlock",
+ "doc",
+ "doc/rlock.help",
+ "lib",
+ "lib/lockfile.rb",
+ "lockfile.gemspec",
+ "rakefile",
+ "readme.erb",
+ "samples",
+ "samples/a.rb",
+ "samples/lock",
+ "samples/lock.sh",
+ "samples/lockfile",
+ "samples/nfsstore.rb",
+ "samples/out"]
+
+  spec.executables = ["rlock"]
+  
+  spec.require_path = "lib"
+
+  spec.test_files = nil
+
+### spec.add_dependency 'lib', '>= version'
+#### spec.add_dependency 'map'
+
+  spec.extensions.push(*[])
+
+  spec.rubyforge_project = "codeforpeople"
+  spec.author = "Ara T. Howard"
+  spec.email = "ara.t.howard@gmail.com"
+  spec.homepage = "https://github.com/ahoward/lockfile"
+end

data/rakefile

@@ -0,0 +1,376 @@
+This.rubyforge_project = 'codeforpeople'
+This.author = "Ara T. Howard"
+This.email = "ara.t.howard@gmail.com"
+This.homepage = "https://github.com/ahoward/#{ This.lib }"
+
+task :license do
+  open('LICENSE', 'w'){|fd| fd.puts "same as ruby's"}
+end
+
+task :default do
+  puts((Rake::Task.tasks.map{|task| task.name.gsub(/::/,':')} - ['default']).sort)
+end
+
+task :test do
+  run_tests!
+end
+
+namespace :test do
+  task(:unit){ run_tests!(:unit) }
+  task(:functional){ run_tests!(:functional) }
+  task(:integration){ run_tests!(:integration) }
+end
+
+def run_tests!(which = nil)
+  which ||= '**'
+  test_dir = File.join(This.dir, "test")
+  test_glob ||= File.join(test_dir, "#{ which }/**_test.rb")
+  test_rbs = Dir.glob(test_glob).sort
+        
+  div = ('=' * 119)
+  line = ('-' * 119)
+
+  test_rbs.each_with_index do |test_rb, index|
+    testno = index + 1
+    command = "#{ This.ruby } -w -I ./lib -I ./test/lib #{ test_rb }"
+
+    puts
+    say(div, :color => :cyan, :bold => true)
+    say("@#{ testno } => ", :bold => true, :method => :print)
+    say(command, :color => :cyan, :bold => true)
+    say(line, :color => :cyan, :bold => true)
+
+    system(command)
+
+    say(line, :color => :cyan, :bold => true)
+
+    status = $?.exitstatus
+
+    if status.zero? 
+      say("@#{ testno } <= ", :bold => true, :color => :white, :method => :print)
+      say("SUCCESS", :color => :green, :bold => true)
+    else
+      say("@#{ testno } <= ", :bold => true, :color => :white, :method => :print)
+      say("FAILURE", :color => :red, :bold => true)
+    end
+    say(line, :color => :cyan, :bold => true)
+
+    exit(status) unless status.zero?
+  end
+end
+
+
+task :gemspec do
+  ignore_extensions = ['git', 'svn', 'tmp', /sw./, 'bak', 'gem']
+  ignore_directories = ['pkg']
+  ignore_files = ['test/log']
+
+  shiteless = 
+    lambda do |list|
+      list.delete_if do |entry|
+        next unless test(?e, entry)
+        extension = File.basename(entry).split(%r/[.]/).last
+        ignore_extensions.any?{|ext| ext === extension}
+      end
+      list.delete_if do |entry|
+        next unless test(?d, entry)
+        dirname = File.expand_path(entry)
+        ignore_directories.any?{|dir| File.expand_path(dir) == dirname}
+      end
+      list.delete_if do |entry|
+        next unless test(?f, entry)
+        filename = File.expand_path(entry)
+        ignore_files.any?{|file| File.expand_path(file) == filename}
+      end
+    end
+
+  lib         = This.lib
+  object      = This.object
+  version     = This.version
+  files       = shiteless[Dir::glob("**/**")]
+  executables = shiteless[Dir::glob("bin/*")].map{|exe| File.basename(exe)}
+  #has_rdoc    = true #File.exist?('doc')
+  test_files  = "test/#{ lib }.rb" if File.file?("test/#{ lib }.rb")
+  summary     = object.respond_to?(:summary) ? object.summary : "summary: #{ lib } kicks the ass"
+  description = object.respond_to?(:description) ? object.description : "description: #{ lib } kicks the ass"
+  license     = object.respond_to?(:license) ? object.license : "same as ruby's"
+
+  if This.extensions.nil?
+    This.extensions = []
+    extensions = This.extensions
+    %w( Makefile configure extconf.rb ).each do |ext|
+      extensions << ext if File.exists?(ext)
+    end
+  end
+  extensions = [extensions].flatten.compact
+
+  template = 
+    if test(?e, 'gemspec.erb')
+      Template{ IO.read('gemspec.erb') }
+    else
+      Template {
+        <<-__
+          ## #{ lib }.gemspec
+          #
+
+          Gem::Specification::new do |spec|
+            spec.name = #{ lib.inspect }
+            spec.version = #{ version.inspect }
+            spec.platform = Gem::Platform::RUBY
+            spec.summary = #{ lib.inspect }
+            spec.description = #{ description.inspect }
+            spec.license = #{ license.inspect }
+
+            spec.files =\n#{ files.sort.pretty_inspect }
+            spec.executables = #{ executables.inspect }
+            
+            spec.require_path = "lib"
+
+            spec.test_files = #{ test_files.inspect }
+
+          ### spec.add_dependency 'lib', '>= version'
+          #### spec.add_dependency 'map'
+
+            spec.extensions.push(*#{ extensions.inspect })
+
+            spec.rubyforge_project = #{ This.rubyforge_project.inspect }
+            spec.author = #{ This.author.inspect }
+            spec.email = #{ This.email.inspect }
+            spec.homepage = #{ This.homepage.inspect }
+          end
+        __
+      }
+    end
+
+  Fu.mkdir_p(This.pkgdir)
+  gemspec = "#{ lib }.gemspec"
+  open(gemspec, "w"){|fd| fd.puts(template)}
+  This.gemspec = gemspec
+end
+
+task :gem => [:clean, :gemspec] do
+  Fu.mkdir_p(This.pkgdir)
+  before = Dir['*.gem']
+  cmd = "gem build #{ This.gemspec }"
+  `#{ cmd }`
+  after = Dir['*.gem']
+  gem = ((after - before).first || after.first) or abort('no gem!')
+  Fu.mv(gem, This.pkgdir)
+  This.gem = File.join(This.pkgdir, File.basename(gem))
+end
+
+task :readme do
+  samples = ''
+  prompt = '~ > '
+  lib = This.lib
+  version = This.version
+
+  Dir['sample*/*'].sort.each do |sample|
+    samples << "\n" << "  <========< #{ sample } >========>" << "\n\n"
+
+    cmd = "cat #{ sample }"
+    samples << Util.indent(prompt + cmd, 2) << "\n\n"
+    samples << Util.indent(`#{ cmd }`, 4) << "\n"
+
+    cmd = "ruby #{ sample }"
+    samples << Util.indent(prompt + cmd, 2) << "\n\n"
+
+    cmd = "ruby -e'STDOUT.sync=true; exec %(ruby -I ./lib #{ sample })'"
+    samples << Util.indent(`#{ cmd } 2>&1`, 4) << "\n"
+  end
+
+  template = 
+    if test(?e, 'README.erb')
+      Template{ IO.read('README.erb') }
+    else
+      Template {
+        <<-__
+          NAME
+            #{ lib }
+
+          DESCRIPTION
+
+          INSTALL
+            gem install #{ lib }
+
+          SAMPLES
+            #{ samples }
+        __
+      }
+    end
+
+  open("README", "w"){|fd| fd.puts template}
+end
+
+
+task :clean do
+  Dir[File.join(This.pkgdir, '**/**')].each{|entry| Fu.rm_rf(entry)}
+end
+
+
+task :release => [:clean, :gemspec, :gem] do
+  gems = Dir[File.join(This.pkgdir, '*.gem')].flatten
+  raise "which one? : #{ gems.inspect }" if gems.size > 1
+  raise "no gems?" if gems.size < 1
+
+  cmd = "gem push #{ This.gem }"
+  puts cmd
+  puts
+  system(cmd)
+  abort("cmd(#{ cmd }) failed with (#{ $?.inspect })") unless $?.exitstatus.zero?
+
+  cmd = "rubyforge login && rubyforge add_release #{ This.rubyforge_project } #{ This.lib } #{ This.version } #{ This.gem }"
+  puts cmd
+  puts
+  system(cmd)
+  abort("cmd(#{ cmd }) failed with (#{ $?.inspect })") unless $?.exitstatus.zero?
+end
+
+
+
+
+
+BEGIN {
+# support for this rakefile
+#
+  $VERBOSE = nil
+
+  require 'ostruct'
+  require 'erb'
+  require 'fileutils'
+  require 'rbconfig'
+  require 'pp'
+
+# fu shortcut
+#
+  Fu = FileUtils
+
+# cache a bunch of stuff about this rakefile/environment
+#
+  This = OpenStruct.new
+
+  This.file = File.expand_path(__FILE__)
+  This.dir = File.dirname(This.file)
+  This.pkgdir = File.join(This.dir, 'pkg')
+
+# grok lib
+#
+  lib = ENV['LIB']
+  unless lib
+    lib = File.basename(Dir.pwd).sub(/[-].*$/, '')
+  end
+  This.lib = lib
+
+# grok version
+#
+  version = ENV['VERSION']
+  unless version
+    require "./lib/#{ This.lib }"
+    This.name = lib.capitalize
+    This.object = eval(This.name)
+    version = This.object.send(:version)
+  end
+  This.version = version
+
+# we need to know the name of the lib an it's version
+#
+  abort('no lib') unless This.lib
+  abort('no version') unless This.version
+
+# discover full path to this ruby executable
+#
+  c = Config::CONFIG
+  bindir = c["bindir"] || c['BINDIR']
+  ruby_install_name = c['ruby_install_name'] || c['RUBY_INSTALL_NAME'] || 'ruby'
+  ruby_ext = c['EXEEXT'] || ''
+  ruby = File.join(bindir, (ruby_install_name + ruby_ext))
+  This.ruby = ruby
+
+# some utils
+#
+  module Util
+    def indent(s, n = 2)
+      s = unindent(s)
+      ws = ' ' * n
+      s.gsub(%r/^/, ws)
+    end
+
+    def unindent(s)
+      indent = nil
+      s.each_line do |line|
+      next if line =~ %r/^\s*$/
+      indent = line[%r/^\s*/] and break
+    end
+    indent ? s.gsub(%r/^#{ indent }/, "") : s
+  end
+    extend self
+  end
+
+# template support
+#
+  class Template
+    def initialize(&block)
+      @block = block
+      @template = block.call.to_s
+    end
+    def expand(b=nil)
+      ERB.new(Util.unindent(@template)).result((b||@block).binding)
+    end
+    alias_method 'to_s', 'expand'
+  end
+  def Template(*args, &block) Template.new(*args, &block) end
+
+# colored console output support
+#
+  This.ansi = {
+    :clear      => "\e[0m",
+    :reset      => "\e[0m",
+    :erase_line => "\e[K",
+    :erase_char => "\e[P",
+    :bold       => "\e[1m",
+    :dark       => "\e[2m",
+    :underline  => "\e[4m",
+    :underscore => "\e[4m",
+    :blink      => "\e[5m",
+    :reverse    => "\e[7m",
+    :concealed  => "\e[8m",
+    :black      => "\e[30m",
+    :red        => "\e[31m",
+    :green      => "\e[32m",
+    :yellow     => "\e[33m",
+    :blue       => "\e[34m",
+    :magenta    => "\e[35m",
+    :cyan       => "\e[36m",
+    :white      => "\e[37m",
+    :on_black   => "\e[40m",
+    :on_red     => "\e[41m",
+    :on_green   => "\e[42m",
+    :on_yellow  => "\e[43m",
+    :on_blue    => "\e[44m",
+    :on_magenta => "\e[45m",
+    :on_cyan    => "\e[46m",
+    :on_white   => "\e[47m"
+  }
+  def say(phrase, *args)
+    options = args.last.is_a?(Hash) ? args.pop : {}
+    options[:color] = args.shift.to_s.to_sym unless args.empty?
+    keys = options.keys
+    keys.each{|key| options[key.to_s.to_sym] = options.delete(key)}
+
+    color = options[:color]
+    bold = options.has_key?(:bold)
+
+    parts = [phrase]
+    parts.unshift(This.ansi[color]) if color
+    parts.unshift(This.ansi[:bold]) if bold
+    parts.push(This.ansi[:clear]) if parts.size > 1
+
+    method = options[:method] || :puts
+
+    Kernel.send(method, parts.join)
+  end
+
+# always run out of the project dir
+#
+  Dir.chdir(This.dir)
+}

data/readme.erb

@@ -0,0 +1,227 @@
+URLS
+
+  http://rubyforge.org/projects/codeforpeople/
+  http://codeforpeople.com/lib/ruby/
+
+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        => 3600,  # we will blow away any files found to be older
+                                # than this (lockfile.thief? #=> true)
+
+      :suspend        => 1800,  # 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@gmail.com
+
+BUGS
+
+  bugno > 1 && bugno < 42
+
+HISTORY
+
+  1.4.3:
+    - fixed a small non-critical bug in the require gaurd
+
+  1.4.2:
+    - upped defaults for max_age to 3600 and suspend to 1800.
+    - tweaked a few things to play nice with rubygems
+
+  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