File::NFSLock3pm

Usage

  use File::NFSLock qw(uncache);
  use Fcntl qw(LOCK_EX LOCK_NB);
  my $file = "somefile";
  ### set up a lock - lasts until object looses scope
  if (my $lock = new File::NFSLock {
    file      => $file,
    lock_type => LOCK_EX|LOCK_NB,
    blocking_timeout   => 10,      # 10 sec
    stale_lock_timeout => 30 * 60, # 30 min
  }) {
    ### OR
    ### my $lock = File::NFSLock->new($file,LOCK_EX|LOCK_NB,10,30*60);
    ### do write protected stuff on $file
    ### at this point $file is uncached from NFS (most recent)
    open(FILE, "+<$file") || die $!;
    ### or open it any way you like
    ### my $fh = IO::File->open( $file, 'w' ) || die $!
    ### update (uncache across NFS) other files
    uncache("someotherfile1");
    uncache("someotherfile2");
    # open(FILE2,"someotherfile1");
    ### unlock it
    $lock->unlock();
    ### OR
    ### undef $lock;
    ### OR let $lock go out of scope
  }else{
    die "I couldn't lock the file [$File::NFSLock::errstr]";
  }

Overview

Program based of concept of hard linking of files being atomic across NFS. This concept was mentioned in Mail::Box::Locker (which was originally presented in Mail::Folder::Maildir). Some routine flow is taken from there -- particularly the idea of creating a random local file, hard linking a common file to the local file, and then checking the nlink status. Some ideologies were not complete (uncache mechanism, shared locking) and some coding was even incorrect (wrong stat index). File::NFSLock was written to be light, generic, and fast.

Usage

Locking occurs by creating a File::NFSLock object. If the object is created successfully, a lock is currently in place and remains in place until the lock object goes out of scope (or calls the unlock method).

A lock object is created by calling the new method and passing two to four parameters in the following manner:

  my $lock = File::NFSLock->new($file,
                                $lock_type,
                                $blocking_timeout,
                                $stale_lock_timeout,
                                );

Additionally, parameters may be passed as a hashref:

  my $lock = File::NFSLock->new({
    file               => $file,
    lock_type          => $lock_type,
    blocking_timeout   => $blocking_timeout,
    stale_lock_timeout => $stale_lock_timeout,
  });

Parameters

Parameter 1: file

Filename of the file upon which it is anticipated that a write will happen to. Locking will provide the most recent version (uncached) of this file upon a successful file lock. It is not necessary for this file to exist.

Parameter 2: lock_type

Lock type must be one of the following:

  BLOCKING
  BL
  EXCLUSIVE (BLOCKING)
  EX
  NONBLOCKING
  NB
  SHARED
  SH

Or else one or more of the following joined with '|':

  Fcntl::LOCK_EX() (BLOCKING)
  Fcntl::LOCK_NB() (NONBLOCKING)
  Fcntl::LOCK_SH() (SHARED)

Lock type determines whether the lock will be blocking, non blocking, or shared. Blocking locks will wait until other locks are removed before the process continues. Non blocking locks will return undef if another process currently has the lock. Shared will allow other process to do a shared lock at the same time as long as there is not already an exclusive lock obtained.

Parameter 3: blocking_timeout (optional)

Timeout is used in conjunction with a blocking timeout. If specified, File::NFSLock will block up to the number of seconds specified in timeout before returning undef (could not get a lock).

Parameter 4: stale_lock_timeout (optional)

Timeout is used to see if an existing lock file is older than the stale lock timeout. If do_lock fails to get a lock, the modified time is checked and do_lock is attempted again. If the stale_lock_timeout is set to low, a recursion load could exist so do_lock will only recurse 10 times (this is only a problem if the stale_lock_timeout is set too low -- on the order of one or two seconds).

Methods

After the $lock object is instantiated with new, as outlined above, some methods may be used for additional functionality.

  $lock->unlock;

  $lock->uncache;
  $lock->uncache("otherfile1");
  uncache("otherfile2");

  my $pid = $lock->fork;
  if (!defined $pid) {
    # Fork Failed
  } elsif ($pid) {
    # Parent ...
  } else {
    # Child ...
  }

  my $pid = fork;
  if (!defined $pid) {
    # Fork Failed
  } elsif ($pid) {
    $lock->newpid;
    # Parent ...
  } else {
    $lock->newpid;
    # Child ...
  }

Failure

On failure, a global variable, $File::NFSLock::errstr, should be set and should contain the cause for the failure to get a lock. Useful primarily for debugging.

Lock_extension

By default File::NFSLock will use a lock file extension of ".NFSLock". This is in a global variable $File::NFSLock::LOCK_EXTENSION that may be changed to suit other purposes (such as compatibility in mail systems).

Repo

The source is now on github:

git clone https://github.com/hookbot/File-NFSLock

Install

Download and extract tarball before running these commands in its base directory:

  perl Makefile.PL
  make
  make test
  make install

For RPM installation, download tarball before running these commands in your _topdir:

  rpm -ta SOURCES/File-NFSLock-*.tar.gz
  rpm -ih RPMS/noarch/perl-File-NFSLock-*.rpm