Debian Codegraph @

README

raw
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