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

  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 

      :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

      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


SAMPLES

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

AUTHOR

  -a

EMAIL

  Ara.T.Howard@noaa.gov

BUGS

  > 1

  further notifications to email above

HISTORY

  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