Lockfile is a project mainly written in RUBY and SHELL, it's free.
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
AUTHOR
Ara T. Howard
BUGS
bugno > 1 && bugno < 42
HISTORY
1.4.3:
fixed a small non-critical bug in the require gaurd
1.4.2:
tweaked a few things to play nice with rubygems
1.4.1:
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:
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: