[ANN] lockfile-0.2.0

ruby-talk
1

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

lockfile = Lockfile.new 'file.lock'
begin
  lockfile.lock
  p 42
ensure
  lockfile.unlock
end

require 'pstore'           # which is NOT nfs safe on it's own

opts = {                   # the keys can be symbols or strings

  :retries        => 42,   # we will try 42 times to aquire the lock

  :sleep_inc      => 2,    # we will sleep 2 seconds longer than the
                           # previous sleep after each retry

  :max_sleep      => 30,   # we will never sleep longer than 30 seconds
                           # however

  :max_age        => 3600, # we will blow away any files found to be older
                           # than this (this sets lockfile.thief? == true)

  :suspend        => 16,   # 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 - a race condition

  :timeout        => 300,  # we simply will not wait longer than five
                           # minutes

  :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.42, # when polling a very brief sleep is issued
                           # between attempts, this is the upper limit of
                           # that sleep timeout 
}

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
  1. same as 1 above - Lockfile.new takes a block and ensures unlock is called
Lockfile.new('file.lock') do
  p 42
end

  1. 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

SAMPLES

  • see samples/a.rb
  • see samples/nfsstore.rb
  • see bin/rlock

enjoy.

-a

···

–

EMAIL :: Ara [dot] T [dot] Howard [at] noaa [dot] gov
PHONE :: 303.497.6469
ADDRESS :: E/GC2 325 Broadway, Boulder, CO 80305-3328
URL :: Solar-Terrestrial Physics Data | NCEI
TRY :: for l in ruby perl;do $l -e “print "\x3a\x2d\x29\x0a"”;done
===============================================================================