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 num