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