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