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