[ANN] lockfile-1.2.0

Discussion in 'Ruby' started by Ara.T.Howard, Nov 4, 2004.

  1. Ara.T.Howard

    Ara.T.Howard Guest

    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
    and to run arbitrary commands while holding them.

    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



    BUGS

    > 1


    further notifications to email above

    HISTORY

    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

    enjoy.

    -a
    --
    ===============================================================================
    | EMAIL :: Ara [dot] T [dot] Howard [at] noaa [dot] gov
    | PHONE :: 303.497.6469
    | When you do something, you should burn yourself completely, like a good
    | bonfire, leaving no trace of yourself. --Shunryu Suzuki
    ===============================================================================
    Ara.T.Howard, Nov 4, 2004
    #1
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Ara.T.Howard

    [ANN] lockfile-0.0.0

    Ara.T.Howard, May 7, 2004, in forum: Ruby
    Replies:
    2
    Views:
    94
    Ara.T.Howard
    May 8, 2004
  2. Ara.T.Howard

    [ANN] lockfile-0.2.0

    Ara.T.Howard, May 13, 2004, in forum: Ruby
    Replies:
    0
    Views:
    96
    Ara.T.Howard
    May 13, 2004
  3. Ara.T.Howard

    [ANN] lockfile-1.0.0

    Ara.T.Howard, Jun 16, 2004, in forum: Ruby
    Replies:
    0
    Views:
    95
    Ara.T.Howard
    Jun 16, 2004
  4. Ara.T.Howard

    [ANN] lockfile-1.4.0

    Ara.T.Howard, Nov 10, 2005, in forum: Ruby
    Replies:
    0
    Views:
    101
    Ara.T.Howard
    Nov 10, 2005
  5. Ara.T.Howard

    [ANN] lockfile-1.4.1

    Ara.T.Howard, Jan 5, 2007, in forum: Ruby
    Replies:
    2
    Views:
    80
    Michael P. Soulier
    Jan 5, 2007
Loading...

Share This Page