1NAME 2 File::NFSLock - perl module to do NFS (or not) locking 3 4SYNOPSIS 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 42DESCRIPTION 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 52USAGE 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 75PARAMETERS 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 121METHODS 122 After the $lock object is instantiated with new, as outlined above, 123 some methods may be used for additional functionality. 124 125 unlock 126 127 $lock->unlock; 128 129 This method may be used to explicitly release a lock that is 130 aquired. In most cases, it is not necessary to call unlock directly 131 since it will implicitly be called when the object leaves whatever 132 scope it is in. 133 134 uncache 135 136 $lock->uncache; 137 $lock->uncache("otherfile1"); 138 uncache("otherfile2"); 139 140 This method is used to freshen up the contents of a file across NFS, 141 ignoring what is contained in the NFS client cache. It is always 142 called from within the new constructor on the file that the lock is 143 being attempted. uncache may be used as either an object method or 144 as a stand alone subroutine. 145 146 newpid 147 148 my $pid = fork; 149 if (defined $pid) { 150 # Fork Failed 151 } elsif ($pid) { 152 $lock->newpid; # Parent 153 } else { 154 $lock->newpid; # Child 155 } 156 157 If fork() is called after a lock has been aquired, then when the 158 lock object leaves scope in either the parent or child, it will be 159 released. This behavior may be inappropriate for your application. 160 To delegate ownership of the lock from the parent to the child, both 161 the parent and child process must call the newpid() method after a 162 successful fork() call. This will prevent the parent from releasing 163 the lock when unlock is called or when the lock object leaves scope. 164 This is also useful to allow the parent to fail on subsequent lock 165 attempts if the child lock is still aquired. 166 167FAILURE 168 On failure, a global variable, $File::NFSLock::errstr, should be set 169 and should contain the cause for the failure to get a lock. Useful 170 primarily for debugging. 171 172LOCK_EXTENSION 173 By default File::NFSLock will use a lock file extenstion of 174 ".NFSLock". This is in a global variable 175 $File::NFSLock::LOCK_EXTENSION that may be changed to suit other 176 purposes (such as compatibility in mail systems). 177 178BUGS 179 Notify paul@seamons.com or bbb@cpan.org if you spot anything. 180 181 FIFO 182 183 Locks are not necessarily obtained on a first come first serve 184 basis. Not only does this not seem fair to new processes trying to 185 obtain a lock, but it may cause a process starvation condition on 186 heavily locked files. 187 188 DIRECTORIES 189 190 Locks cannot be obtained on directory nodes, nor can a directory 191 node be uncached with the uncache routine because hard links do not 192 work with directory nodes. Some other algorithm might be used to 193 uncache a directory, but I am unaware of the best way to do it. The 194 biggest use I can see would be to avoid NFS cache of directory 195 modified and last accessed timestamps. 196 197INSTALL 198 Download and extract tarball before running these commands in its 199 base directory: 200 201 perl Makefile.PL 202 make 203 make test 204 make install 205 206 For RPM installation, download tarball before running these commands 207 in your _topdir: 208 209 rpm -ta SOURCES/File-NFSLock-*.tar.gz 210 rpm -ih RPMS/noarch/perl-File-NFSLock-*.rpm 211 212AUTHORS 213 Paul T Seamons (paul@seamons.com) - Performed majority of the 214 programming with copious amounts of input from Rob Brown. 215 216 Rob B Brown (bbb@cpan.org) - In addition to helping in the 217 programming, Rob Brown provided most of the core testing to make 218 sure implementation worked properly. He is now the current 219 maintainer. 220 221 Also Mark Overmeer (mark@overmeer.net) - Author of 222 Mail::Box::Locker, from which some key concepts for File::NFSLock 223 were taken. 224 225 Also Kevin Johnson (kjj@pobox.com) - Author of 226 Mail::Folder::Maildir, from which Mark Overmeer based 227 Mail::Box::Locker. 228 229COPYRIGHT 230 Copyright (C) 2001 231 Paul T Seamons 232 paul@seamons.com 233 http://seamons.com/ 234 235 Copyright (C) 2002-2003, 236 Rob B Brown 237 bbb@cpan.org 238 239 This package may be distributed under the terms of either the 240 GNU General Public License 241 or the 242 Perl Artistic License 243 244 All rights reserved. 245 246