plucky (3) File::NFSLock.3pm.gz
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.
fork
my $pid = $lock->fork;
if (!defined $pid) {
# Fork Failed
} elsif ($pid) {
# Parent ...
} else {
# Child ...
}
fork() is a convenience method that acts just like the normal CORE::fork() except it safely ensures the
lock is retained within both parent and child processes. WITHOUT this, then when either the parent or
child process releases the lock, then the entire lock will be lost, allowing external processes to re-
acquire a lock on the same file, even if the other process still has the lock object in scope. This can
cause corruption since both processes might think they have exclusive access to the file.
newpid
my $pid = fork;
if (!defined $pid) {
# Fork Failed
} elsif ($pid) {
$lock->newpid;
# Parent ...
} else {
$lock->newpid;
# Child ...
}
The newpid() synopsis shown above is equivalent to the one used for the fork() method, but it's not
intended to be called directly. It is called internally by the fork() method. To be safe, it is
recommended to use $lock->fork() from now on.
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
BUGS
If you spot anything, please submit a pull request on github and/or submit a ticket with RT:
https://rt.cpan.org/Dist/Display.html?Queue=File-NFSLock
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-2018,
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.