| 1 |
NAME |
| 2 |
File::NFSLock - perl module to do NFS (or not) locking |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
use File::NFSLock qw(uncache); |
| 6 |
use Fcntl qw(LOCK_EX LOCK_NB); |
| 7 |
|
| 8 |
my $file = "somefile"; |
| 9 |
|
| 10 |
### set up a lock - lasts until object looses scope |
| 11 |
if (my $lock = new File::NFSLock { |
| 12 |
file => $file, |
| 13 |
lock_type => LOCK_EX|LOCK_NB, |
| 14 |
blocking_timeout => 10, # 10 sec |
| 15 |
stale_lock_timeout => 30 * 60, # 30 min |
| 16 |
}) { |
| 17 |
|
| 18 |
### OR |
| 19 |
### my $lock = File::NFSLock->new($file,LOCK_EX|LOCK_NB,10,30*60); |
| 20 |
|
| 21 |
### do write protected stuff on $file |
| 22 |
### at this point $file is uncached from NFS (most recent) |
| 23 |
open(FILE, "+<$file") || die $!; |
| 24 |
|
| 25 |
### or open it any way you like |
| 26 |
### my $fh = IO::File->open( $file, 'w' ) || die $! |
| 27 |
|
| 28 |
### update (uncache across NFS) other files |
| 29 |
uncache("someotherfile1"); |
| 30 |
uncache("someotherfile2"); |
| 31 |
# open(FILE2,"someotherfile1"); |
| 32 |
|
| 33 |
### unlock it |
| 34 |
$lock->unlock(); |
| 35 |
### OR |
| 36 |
### undef $lock; |
| 37 |
### OR let $lock go out of scope |
| 38 |
}else{ |
| 39 |
die "I couldn't lock the file [$File::NFSLock::errstr]"; |
| 40 |
} |
| 41 |
|
| 42 |
DESCRIPTION |
| 43 |
Program based of concept of hard linking of files being atomic across |
| 44 |
NFS. This concept was mentioned in Mail::Box::Locker (which was |
| 45 |
originally presented in Mail::Folder::Maildir). Some routine flow is |
| 46 |
taken from there -- particularly the idea of creating a random local |
| 47 |
file, hard linking a common file to the local file, and then checking |
| 48 |
the nlink status. Some ideologies were not complete (uncache mechanism, |
| 49 |
shared locking) and some coding was even incorrect (wrong stat index). |
| 50 |
File::NFSLock was written to be light, generic, and fast. |
| 51 |
|
| 52 |
USAGE |
| 53 |
Locking occurs by creating a File::NFSLock object. If the object is |
| 54 |
created successfully, a lock is currently in place and remains in place |
| 55 |
until the lock object goes out of scope (or calls the unlock method). |
| 56 |
|
| 57 |
A lock object is created by calling the new method and passing two to |
| 58 |
four parameters in the following manner: |
| 59 |
|
| 60 |
my $lock = File::NFSLock->new($file, |
| 61 |
$lock_type, |
| 62 |
$blocking_timeout, |
| 63 |
$stale_lock_timeout, |
| 64 |
); |
| 65 |
|
| 66 |
Additionally, parameters may be passed as a hashref: |
| 67 |
|
| 68 |
my $lock = File::NFSLock->new({ |
| 69 |
file => $file, |
| 70 |
lock_type => $lock_type, |
| 71 |
blocking_timeout => $blocking_timeout, |
| 72 |
stale_lock_timeout => $stale_lock_timeout, |
| 73 |
}); |
| 74 |
|
| 75 |
PARAMETERS |
| 76 |
Parameter 1: file |
| 77 |
Filename of the file upon which it is anticipated that a write will |
| 78 |
happen to. Locking will provide the most recent version (uncached) |
| 79 |
of this file upon a successful file lock. It is not necessary for |
| 80 |
this file to exist. |
| 81 |
|
| 82 |
Parameter 2: lock_type |
| 83 |
Lock type must be one of the following: |
| 84 |
|
| 85 |
BLOCKING |
| 86 |
BL |
| 87 |
EXCLUSIVE (BLOCKING) |
| 88 |
EX |
| 89 |
NONBLOCKING |
| 90 |
NB |
| 91 |
SHARED |
| 92 |
SH |
| 93 |
|
| 94 |
Or else one or more of the following joined with '|': |
| 95 |
|
| 96 |
Fcntl::LOCK_EX() (BLOCKING) |
| 97 |
Fcntl::LOCK_NB() (NONBLOCKING) |
| 98 |
Fcntl::LOCK_SH() (SHARED) |
| 99 |
|
| 100 |
Lock type determines whether the lock will be blocking, non |
| 101 |
blocking, or shared. Blocking locks will wait until other locks are |
| 102 |
removed before the process continues. Non blocking locks will return |
| 103 |
undef if another process currently has the lock. Shared will allow |
| 104 |
other process to do a shared lock at the same time as long as there |
| 105 |
is not already an exclusive lock obtained. |
| 106 |
|
| 107 |
Parameter 3: blocking_timeout (optional) |
| 108 |
Timeout is used in conjunction with a blocking timeout. If |
| 109 |
specified, File::NFSLock will block up to the number of seconds |
| 110 |
specified in timeout before returning undef (could not get a lock). |
| 111 |
|
| 112 |
Parameter 4: stale_lock_timeout (optional) |
| 113 |
Timeout is used to see if an existing lock file is older than the |
| 114 |
stale lock timeout. If do_lock fails to get a lock, the modified |
| 115 |
time is checked and do_lock is attempted again. If the |
| 116 |
stale_lock_timeout is set to low, a recursion load could exist so |
| 117 |
do_lock will only recurse 10 times (this is only a problem if the |
| 118 |
stale_lock_timeout is set too low -- on the order of one or two |
| 119 |
seconds). |
| 120 |
|
| 121 |
METHODS |
| 122 |
After the $lock object is instantiated with new, as outlined above, some |
| 123 |
methods may be used for additional functionality. |
| 124 |
|
| 125 |
unlock |
| 126 |
$lock->unlock; |
| 127 |
|
| 128 |
This method may be used to explicitly release a lock that is acquired. |
| 129 |
In most cases, it is not necessary to call unlock directly since it will |
| 130 |
implicitly be called when the object leaves whatever scope it is in. |
| 131 |
|
| 132 |
uncache |
| 133 |
$lock->uncache; |
| 134 |
$lock->uncache("otherfile1"); |
| 135 |
uncache("otherfile2"); |
| 136 |
|
| 137 |
This method is used to freshen up the contents of a file across NFS, |
| 138 |
ignoring what is contained in the NFS client cache. It is always called |
| 139 |
from within the new constructor on the file that the lock is being |
| 140 |
attempted. uncache may be used as either an object method or as a stand |
| 141 |
alone subroutine. |
| 142 |
|
| 143 |
fork |
| 144 |
my $pid = $lock->fork; |
| 145 |
if (!defined $pid) { |
| 146 |
# Fork Failed |
| 147 |
} elsif ($pid) { |
| 148 |
# Parent ... |
| 149 |
} else { |
| 150 |
# Child ... |
| 151 |
} |
| 152 |
|
| 153 |
fork() is a convenience method that acts just like the normal |
| 154 |
CORE::fork() except it safely ensures the lock is retained within both |
| 155 |
parent and child processes. WITHOUT this, then when either the parent or |
| 156 |
child process releases the lock, then the entire lock will be lost, |
| 157 |
allowing external processes to re-acquire a lock on the same file, even |
| 158 |
if the other process still has the lock object in scope. This can cause |
| 159 |
corruption since both processes might think they have exclusive access |
| 160 |
to the file. |
| 161 |
|
| 162 |
newpid |
| 163 |
my $pid = fork; |
| 164 |
if (!defined $pid) { |
| 165 |
# Fork Failed |
| 166 |
} elsif ($pid) { |
| 167 |
$lock->newpid; |
| 168 |
# Parent ... |
| 169 |
} else { |
| 170 |
$lock->newpid; |
| 171 |
# Child ... |
| 172 |
} |
| 173 |
|
| 174 |
The newpid() synopsis shown above is equivalent to the one used for the |
| 175 |
fork() method, but it's not intended to be called directly. It is called |
| 176 |
internally by the fork() method. To be safe, it is recommended to use |
| 177 |
$lock->fork() from now on. |
| 178 |
|
| 179 |
FAILURE |
| 180 |
On failure, a global variable, $File::NFSLock::errstr, should be set and |
| 181 |
should contain the cause for the failure to get a lock. Useful primarily |
| 182 |
for debugging. |
| 183 |
|
| 184 |
LOCK_EXTENSION |
| 185 |
By default File::NFSLock will use a lock file extension of ".NFSLock". |
| 186 |
This is in a global variable $File::NFSLock::LOCK_EXTENSION that may be |
| 187 |
changed to suit other purposes (such as compatibility in mail systems). |
| 188 |
|
| 189 |
REPO |
| 190 |
The source is now on github: |
| 191 |
|
| 192 |
git clone https://github.com/hookbot/File-NFSLock |
| 193 |
|
| 194 |
BUGS |
| 195 |
If you spot anything, please submit a pull request on github and/or |
| 196 |
submit a ticket with RT: |
| 197 |
https://rt.cpan.org/Dist/Display.html?Queue=File-NFSLock |
| 198 |
|
| 199 |
FIFO |
| 200 |
Locks are not necessarily obtained on a first come first serve basis. |
| 201 |
Not only does this not seem fair to new processes trying to obtain a |
| 202 |
lock, but it may cause a process starvation condition on heavily locked |
| 203 |
files. |
| 204 |
|
| 205 |
DIRECTORIES |
| 206 |
Locks cannot be obtained on directory nodes, nor can a directory node be |
| 207 |
uncached with the uncache routine because hard links do not work with |
| 208 |
directory nodes. Some other algorithm might be used to uncache a |
| 209 |
directory, but I am unaware of the best way to do it. The biggest use I |
| 210 |
can see would be to avoid NFS cache of directory modified and last |
| 211 |
accessed timestamps. |
| 212 |
|
| 213 |
INSTALL |
| 214 |
Download and extract tarball before running these commands in its base |
| 215 |
directory: |
| 216 |
|
| 217 |
perl Makefile.PL |
| 218 |
make |
| 219 |
make test |
| 220 |
make install |
| 221 |
|
| 222 |
For RPM installation, download tarball before running these commands in |
| 223 |
your _topdir: |
| 224 |
|
| 225 |
rpm -ta SOURCES/File-NFSLock-*.tar.gz |
| 226 |
rpm -ih RPMS/noarch/perl-File-NFSLock-*.rpm |
| 227 |
|
| 228 |
AUTHORS |
| 229 |
Paul T Seamons ([email protected]) - Performed majority of the |
| 230 |
programming with copious amounts of input from Rob Brown. |
| 231 |
|
| 232 |
Rob B Brown ([email protected]) - In addition to helping in the programming, |
| 233 |
Rob Brown provided most of the core testing to make sure implementation |
| 234 |
worked properly. He is now the current maintainer. |
| 235 |
|
| 236 |
Also Mark Overmeer ([email protected]) - Author of Mail::Box::Locker, |
| 237 |
from which some key concepts for File::NFSLock were taken. |
| 238 |
|
| 239 |
Also Kevin Johnson ([email protected]) - Author of Mail::Folder::Maildir, |
| 240 |
from which Mark Overmeer based Mail::Box::Locker. |
| 241 |
|
| 242 |
COPYRIGHT |
| 243 |
Copyright (C) 2001 |
| 244 |
Paul T Seamons |
| 245 |
[email protected] |
| 246 |
http://seamons.com/ |
| 247 |
|
| 248 |
Copyright (C) 2002-2018, |
| 249 |
Rob B Brown |
| 250 |
[email protected] |
| 251 |
|
| 252 |
This package may be distributed under the terms of either the |
| 253 |
GNU General Public License |
| 254 |
or the |
| 255 |
Perl Artistic License |
| 256 |
|
| 257 |
All rights reserved. |
| 258 |
|