NAME¶
File::NFSLock - perl module to do NFS (or not) locking
SYNOPSIS¶
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]";
}
DESCRIPTION¶
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.
unlock¶
$lock->unlock;
This method may be used to explicitly release a lock that is acquired. In most
cases, it is not necessary to call unlock directly since it will implicitly be
called when the object leaves whatever scope it is in.
uncache¶
$lock->uncache;
$lock->uncache("otherfile1");
uncache("otherfile2");
This method is used to freshen up the contents of a file across NFS, ignoring
what is contained in the NFS client cache. It is always called from within the
new constructor on the file that the lock is being attempted. uncache may be
used as either an object method or as a stand alone subroutine.
newpid¶
my $pid = fork;
if (defined $pid) {
# Fork Failed
} elsif ($pid) {
$lock->newpid; # Parent
} else {
$lock->newpid; # Child
}
If
fork() is called after a lock has been acquired, then when the lock
object leaves scope in either the parent or child, it will be released. This
behavior may be inappropriate for your application. To delegate ownership of
the lock from the parent to the child, both the parent and child process must
call the
newpid() method after a successful
fork() call. This
will prevent the parent from releasing the lock when unlock is called or when
the lock object leaves scope. This is also useful to allow the parent to fail
on subsequent lock attempts if the child lock is still acquired.
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).
BUGS¶
Notify paul@seamons.com or bbb@cpan.org if you spot anything.
FIFO¶
Locks are not necessarily obtained on a first come first serve basis. Not only
does this not seem fair to new processes trying to obtain a lock, but it may
cause a process starvation condition on heavily locked files.
DIRECTORIES¶
Locks cannot be obtained on directory nodes, nor can a directory node be
uncached with the uncache routine because hard links do not work with
directory nodes. Some other algorithm might be used to uncache a directory,
but I am unaware of the best way to do it. The biggest use I can see would be
to avoid NFS cache of directory modified and last accessed timestamps.
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
AUTHORS¶
Paul T Seamons (paul@seamons.com) - Performed majority of the programming with
copious amounts of input from Rob Brown.
Rob B Brown (bbb@cpan.org) - In addition to helping in the programming, Rob
Brown provided most of the core testing to make sure implementation worked
properly. He is now the current maintainer.
Also Mark Overmeer (mark@overmeer.net) - Author of Mail::Box::Locker, from which
some key concepts for File::NFSLock were taken.
Also Kevin Johnson (kjj@pobox.com) - Author of Mail::Folder::Maildir, from which
Mark Overmeer based Mail::Box::Locker.
COPYRIGHT¶
Copyright (C) 2001
Paul T Seamons
paul@seamons.com
http://seamons.com/
Copyright (C) 2002-2003,
Rob B Brown
bbb@cpan.org
This package may be distributed under the terms of either the
GNU General Public License
or the
Perl Artistic License
All rights reserved.