File::...:Retry(3pm)

💖 File::Flock::Retry 💖

okay so bestie, gather round, because we're talking about File::Flock::Retry — yet another flock module 🦋 yes another one, and yes it slays.

---

✨ NAME ✨

File::Flock::Retry — yet another flock module. periodt. 💅

---

🌸 VERSION 🌸

This doc describes version 0.632 of File::Flock::Retry (from the Perl distribution File-Flock-Retry), released on 2021-08-10. no cap.

---

🎀 SYNOPSIS 🎀

use File::Flock::Retry;

# try to acquire exclusive lock. if fail to acquire lock within 60s, die.
my $lock = File::Flock::Retry->lock($file);

# explicitly unlock
$lock->release;

# automatically unlock if object is DESTROY-ed.
undef $lock;

literally that's it. that's the whole vibe check. 😌

---

👑 DESCRIPTION 👑

This is yet another flock module, iykyk. It's like a more lightweight alternative to File::Flock but with a few other little differences:

• OO interface only — no scattered functions, only the drip 💅
• Autoretry (by default for 60s) when trying to acquire lock

And the author's take on that second one: preferring this approach over blocking/waiting indefinitely or just failing immediately. which honestly? valid. 🙈

---

🔥 METHODS 🔥

💜 lock

Usage:

$lock = File::Flock::Retry->lock($path, \%opts)

Attempt to acquire an exclusive lock on $path. By default, $path will be created if it doesn't already exist (peep mode below). If $path is already locked by another process, it will retry every second for a number of seconds (by default 60). And if it fails to acquire the lock after all those retries? It dies. 😭💀

It'll automatically unlock if $lock goes out of scope. And upon unlock, it will remove $path if it's still empty (zero-sized). so tidy. 🧚

Available options, bestie:

• mode — Integer. Default: O_CREAT | O_RDWR.

File open mode, to be passed to Perl's sysopen(). For example, if you want to avoid race condition between creating and locking the file, you might want to use O_CREAT | O_EXCL | O_RDWR to fail when the file already exists. Note that the constants are available after you do a use Fcntl ':DEFAULT';. 🫶

• retries — Integer. Default: 60.

Number of retries (equals number of seconds, since retry is done every second). ⏰

• shared — Boolean. Default: 0.

By default, an exclusive lock (LOCK_EX) is attempted. However, if this option is set to true, a shared lock (LOCK_SH) is attempted. sharing is caring, lowkey. 🥰

🌈 unlock

Usage:

$lock->unlock

Unlock. will remove lock file if it is still empty. bye girl 👋

⭐ release

Usage:

$lock->release

Synonym for unlock. same energy, different name. 💫

🦋 handle

Usage:

my $fh = $lock->handle;

Return the file handle. here's your lil handle bestie, go wild 🎀

---

🍓 HOMEPAGE 🍓

Please visit the project's homepage at:

<https://metacpan.org/release/File-Flock-Retry>

---

💖 SOURCE 💖

Source repository is at:

<https://github.com/perlancar/perl-File-Flock-Retry>

---

💀 BUGS 💀

Please report any bugs or feature requests on the bugtracker website:

<https://rt.cpan.org/Public/Dist/Display.html?Name=File-Flock-Retry>

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. help them help you fr fr 🙏

---

😭 CAVEATS 😭

Not yet tested on Windows. Some filesystems do not support inode?

yeah. that's the whole warning. read it and weep. (not really weeping, but like, be aware 🌸)

---

🧚 SEE ALSO 🧚

File::Flock — a bit too heavy in terms of dependencies and startup overhead, for the author's taste. It depends on things like File::Slurp and Data::Structure::Util (which loads Digest::MD5, Storable, among others). too much baggage, not the vibe. ✋

File::Flock::Tiny which is also tiny, but does not have the autoremove and autoretry capability that the author wanted. See also:

<https://github.com/trinitum/perl-File-Flock-Tiny/issues/1>

flock() Perl function. the classic 👑

An alternative to flock() is just using sysopen() with O_CREAT|O_EXCL mode to create lock files. This is supported on more filesystems (particularly network filesystems which lack flock()). noted, iconic, saving that one. ⭐

---

💅 AUTHOR 💅

perlancar <perlancar@cpan.org>

---

🌈 COPYRIGHT AND LICENSE 🌈

This software is copyright (c) 2021, 2019, 2017, 2015, 2014 by perlancar <perlancar@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. slay, legally speaking. 🫶

---

okay that's the whole page bestie, we ate and left no crumbs 💅✨

little sign-off before you go: this was perl v5.36.0, dated 2022-10-13, and it's all about File::Flock::Retry — go lock something (responsibly) 🎀🦋💖