File::NFSLock(3pm)

💖 File::NFSLock — the perl module that does NFS (or not) locking 💖

okay bestie, gather round, because this is the perl module that handles locking over NFS and it is lowkey iconic. it's part of the User Contributed Perl Documentation, iykyk. 🎀

---

✨ NAME ✨

File::NFSLock — a perl module to do NFS (or not) locking. yes that's the actual vibe. 🦋

---

🌸 SYNOPSIS 🌸

use File::NFSLock qw(uncache);
use Fcntl qw(LOCK_EX LOCK_NB);

my $file = "somefile";

### set up a lock - lasts until object looses scope
if (my $lock = new File::NFSLock {
  file      => $file,
  lock_type => LOCK_EX|LOCK_NB,
  blocking_timeout   => 10,      # 10 sec
  stale_lock_timeout => 30 * 60, # 30 min
}) {

  ### OR
  ### my $lock = File::NFSLock->new($file,LOCK_EX|LOCK_NB,10,30*60);

  ### do write protected stuff on $file
  ### at this point $file is uncached from NFS (most recent)
  open(FILE, "+<$file") || die $!;

  ### or open it any way you like
  ### my $fh = IO::File->open( $file, 'w' ) || die $!

  ### update (uncache across NFS) other files
  uncache("someotherfile1");
  uncache("someotherfile2");
  # open(FILE2,"someotherfile1");

  ### unlock it
  $lock->unlock();
  ### OR
  ### undef $lock;
  ### OR let $lock go out of scope
}else{
  die "I couldn't lock the file [$File::NFSLock::errstr]";
}

like, that's the whole flow. set it up, do your little write, uncache your other files, unlock, boom. 💅

---

🦋 DESCRIPTION 🦋

so this program is built off the concept that hard linking files is atomic across NFS. that idea got mentioned in Mail::Box::Locker (which was originally presented in Mail::Folder::Maildir). some of the routine flow got borrowed from there too — specifically the whole "make a random local file, hard link a common file to that local file, then check the nlink status" situation. but ngl, some of those ideologies were not complete (the uncache mechanism, shared locking) and some of the coding was even incorrect (wrong stat index). so File::NFSLock got written to be light, generic, and fast. periodt. ✨

---

👑 USAGE 👑

locking happens by creating a File::NFSLock object. if that object gets created successfully, congrats, a lock is currently in place — and it stays in place until the lock object goes out of scope (or you call the unlock method). no cap.

a lock object gets created by calling the new method and passing two to four parameters like this:

my $lock = File::NFSLock->new($file,
                              $lock_type,
                              $blocking_timeout,
                              $stale_lock_timeout,
                              );

and also, parameters can be passed as a hashref if that's more your vibe:

my $lock = File::NFSLock->new({
  file               => $file,
  lock_type          => $lock_type,
  blocking_timeout   => $blocking_timeout,
  stale_lock_timeout => $stale_lock_timeout,
});

---

🎀 PARAMETERS 🎀

Parameter 1: file

the filename of the file that you're anticipating a write will happen to. locking will provide the most recent version (uncached) of this file once you've got a successful file lock. and here's the cute part — this file does not need to exist. it's giving manifesting. 💫

Parameter 2: lock_type

the lock type has to be one of these:

BLOCKING
BL
EXCLUSIVE (BLOCKING)
EX
NONBLOCKING
NB
SHARED
SH

or else one or more of these joined with '|':

Fcntl::LOCK_EX() (BLOCKING)
Fcntl::LOCK_NB() (NONBLOCKING)
Fcntl::LOCK_SH() (SHARED)

lock type decides whether the lock is gonna be blocking, non blocking, or shared:

• blocking locks will wait until other locks are removed before the process continues.
• non blocking locks will return undef if another process currently has the lock.
• shared will allow other process to do a shared lock at the same time — as long as there isn't already an exclusive lock obtained.

Parameter 3: blocking_timeout (optional)

timeout is used in conjunction with a blocking timeout. if specified, File::NFSLock will block up to the number of seconds specified in timeout before returning undef (could not get a lock). 🕐

Parameter 4: stale_lock_timeout (optional)

timeout is used to see if an existing lock file is older than the stale lock timeout. if do_lock fails to get a lock, the modified time is checked and do_lock is attempted again. and hmm, if the stale_lock_timeout is set to low, a recursion load could exist so do_lock will only recurse 10 times. heads up: this is only a problem if the stale_lock_timeout is set too low — like on the order of one or two seconds. don't do that bestie. 😭

---

💅 METHODS 💅

once your $lock object is instantiated with new, as outlined above, some methods may be used for additional functionality. obsessed.

unlock

$lock->unlock;

this method may be used to explicitly release a lock that is acquired. in most cases though, it is not necessary to call unlock directly, since it will implicitly be called when the object leaves whatever scope it's in. it just handles itself. 🫶

uncache

$lock->uncache;
$lock->uncache("otherfile1");
uncache("otherfile2");

this method is used to freshen up the contents of a file across NFS, ignoring what is contained in the NFS client cache. it's always called from within the new constructor on the file that the lock is being attempted. uncache may be used as either an object method or as a stand alone subroutine. versatile queen. ✨

fork

my $pid = $lock->fork;
if (!defined $pid) {
  # Fork Failed
} elsif ($pid) {
  # Parent ...
} else {
  # Child ...
}

fork() is a convenience method that acts just like the normal CORE::fork() except it safely ensures the lock is retained within both parent and child processes. WITHOUT this, then when either the parent or child process releases the lock, then the entire lock will be lost, allowing external processes to re-acquire a lock on the same file, even if the other process still has the lock object in scope. and that can cause corruption since both processes might think they have exclusive access to the file. so yeah, use fork(). fr fr. 💀

newpid

my $pid = fork;
if (!defined $pid) {
  # Fork Failed
} elsif ($pid) {
  $lock->newpid;
  # Parent ...
} else {
  $lock->newpid;
  # Child ...
}

the newpid() synopsis shown above is equivalent to the one used for the fork() method, but it's not intended to be called directly. it gets called internally by the fork() method. to be safe, it is recommended to use $lock->fork() from now on. like, just trust the process. 🌸

---

💀 FAILURE 💀

on failure, a global variable, $File::NFSLock::errstr, should be set and should contain the cause for the failure to get a lock. useful primarily for debugging. so when it dies, you can read the receipts. 🔍

---

🌈 LOCK_EXTENSION 🌈

by default File::NFSLock will use a lock file extension of ".NFSLock". this is in a global variable $File::NFSLock::LOCK_EXTENSION that may be changed to suit other purposes (such as compatibility in mail systems). customize away. 💅

---

⭐ REPO ⭐

the source is now on github:

git clone https://github.com/hookbot/File-NFSLock

---

🙈 BUGS 🙈

if you spot anything, please submit a pull request on github and/or submit a ticket with RT:

https://rt.cpan.org/Dist/Display.html?Queue=File-NFSLock

FIFO

locks are not necessarily obtained on a first come first serve basis. not only does this not seem fair to new processes trying to obtain a lock, but it may cause a process starvation condition on heavily locked files. sad but true. 😔

DIRECTORIES

locks cannot be obtained on directory nodes, nor can a directory node be uncached with the uncache routine — because hard links do not work with directory nodes. some other algorithm might be used to uncache a directory, but I am unaware of the best way to do it. the biggest use I can see would be to avoid NFS cache of directory modified and last accessed timestamps. so like, directories are just out here living their own life. 🦋

---

🧚 INSTALL 🧚

download and extract tarball before running these commands in its base directory:

perl Makefile.PL
make
make test
make install

for RPM installation, download tarball before running these commands in your _topdir:

rpm -ta SOURCES/File-NFSLock-*.tar.gz
rpm -ih RPMS/noarch/perl-File-NFSLock-*.rpm

---

💖 AUTHORS 💖

Paul T Seamons (paul@seamons.com) — performed majority of the programming with copious amounts of input from Rob Brown.

Rob B Brown (bbb@cpan.org) — in addition to helping in the programming, Rob Brown provided most of the core testing to make sure implementation worked properly. he is now the current maintainer. 👑

also Mark Overmeer (mark@overmeer.net) — author of Mail::Box::Locker, from which some key concepts for File::NFSLock were taken.

also Kevin Johnson (kjj@pobox.com) — author of Mail::Folder::Maildir, from which Mark Overmeer based Mail::Box::Locker.

---

🎀 COPYRIGHT 🎀

Copyright (C) 2001
Paul T Seamons
paul@seamons.com
http://seamons.com/

Copyright (C) 2002-2018,
Rob B Brown
bbb@cpan.org

This package may be distributed under the terms of either the
GNU General Public License
  or the
Perl Artistic License

All rights reserved.

---

okay that's the whole thing, bestie. this page ships with perl v5.36.0 and it's dated 2022-12-04. thanks for coming to my ted talk, go lock some files responsibly 💖✨🎀🦋🌸💅🫶