1File::NFSLock(3)      User Contributed Perl Documentation     File::NFSLock(3)
2
3
4

NAME

6       File::NFSLock - perl module to do NFS (or not) locking
7

SYNOPSIS

9         use File::NFSLock qw(uncache);
10         use Fcntl qw(LOCK_EX LOCK_NB);
11
12         my $file = "somefile";
13
14         ### 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
22           ### OR
23           ### my $lock = File::NFSLock->new($file,LOCK_EX|LOCK_NB,10,30*60);
24
25           ### do write protected stuff on $file
26           ### at this point $file is uncached from NFS (most recent)
27           open(FILE, "+<$file") || die $!;
28
29           ### or open it any way you like
30           ### my $fh = IO::File->open( $file, 'w' ) || die $!
31
32           ### update (uncache across NFS) other files
33           uncache("someotherfile1");
34           uncache("someotherfile2");
35           # open(FILE2,"someotherfile1");
36
37           ### 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

DESCRIPTION

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

USAGE

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
61       A lock object is created by calling the new method and passing two to
62       four parameters in the following manner:
63
64         my $lock = File::NFSLock->new($file,
65                                       $lock_type,
66                                       $blocking_timeout,
67                                       $stale_lock_timeout,
68                                       );
69
70       Additionally, parameters may be passed as a hashref:
71
72         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

PARAMETERS

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
86       Parameter 2: lock_type
87           Lock type must be one of the following:
88
89             BLOCKING
90             BL
91             EXCLUSIVE (BLOCKING)
92             EX
93             NONBLOCKING
94             NB
95             SHARED
96             SH
97
98           Or else one or more of the following joined with '|':
99
100             Fcntl::LOCK_EX() (BLOCKING)
101             Fcntl::LOCK_NB() (NONBLOCKING)
102             Fcntl::LOCK_SH() (SHARED)
103
104           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
111       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
116       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

METHODS

126       After the $lock object is instantiated with new, as outlined above,
127       some methods may be used for additional functionality.
128
129   unlock
130         $lock->unlock;
131
132       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
137   uncache
138         $lock->uncache;
139         $lock->uncache("otherfile1");
140         uncache("otherfile2");
141
142       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
148   fork
149         my $pid = $lock->fork;
150         if (!defined $pid) {
151           # Fork Failed
152         } elsif ($pid) {
153           # Parent ...
154         } else {
155           # Child ...
156         }
157
158       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
167   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
179       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

FAILURE

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

LOCK_EXTENSION

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

REPO

195       The source is now on github:
196
197       git clone https://github.com/hookbot/File-NFSLock
198

BUGS

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
204   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
210   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

INSTALL

219       Download and extract tarball before running these commands in its base
220       directory:
221
222         perl Makefile.PL
223         make
224         make test
225         make install
226
227       For RPM installation, download tarball before running these commands in
228       your _topdir:
229
230         rpm -ta SOURCES/File-NFSLock-*.tar.gz
231         rpm -ih RPMS/noarch/perl-File-NFSLock-*.rpm
232

AUTHORS

234       Paul T Seamons (paul@seamons.com) - Performed majority of the
235       programming with copious amounts of input from Rob Brown.
236
237       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
241       Also Mark Overmeer (mark@overmeer.net) - Author of Mail::Box::Locker,
242       from which some key concepts for File::NFSLock were taken.
243
244       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
253         Copyright (C) 2002-2018,
254         Rob B Brown
255         bbb@cpan.org
256
257         This package may be distributed under the terms of either the
258         GNU General Public License
259           or the
260         Perl Artistic License
261
262         All rights reserved.
263
264
265
266perl v5.36.0                      2022-07-22                  File::NFSLock(3)
Impressum