Parano...ckfile(3pm)

💖 Paranoid::IO::Lockfile 💖

okay bestie, gather round, because this is Paranoid::IO::Lockfile from the User Contributed Perl Documentation set — yes it's a Perl module, yes it's a (3pm) man page, and yes it's lowkey essential if you've got a bunch of processes all trying to touch the same files at the same time like a group chat with no moderator. 🫶

---

✨ NAME ✨

Paranoid::IO::Lockfile — Paranoid Lockfile support 💅

---

🎀 VERSION 🎀

$Id: lib/Paranoid/IO/Lockfile.pm, 2.10 2022/03/08 00:01:04 acorliss Exp $

she's version 2.10, dated 2022/03/08, and her whole identity is right there in the $Id string, iconic honestly ✨

---

🦋 SYNOPSIS 🦋

the vibe check, in code:

use Paranoid::IO::Lockfile;
use Fcntl qw(:flock);  # only needed if you use plock in lieu
                       # of the other functions

$rv = plock($lockfile);
$rv = plock($lockfile, LOCK_SH | LOCK_NB);
$rv = plock($lockfile, LOCK_SH | LOCK_NB, $mode);

$rv = pexclock($lockfile);
$rv = pshlock($lockfile);
$rv = punlock($lockfile);

ngl that use Fcntl qw(:flock) line is only needed if you're calling plock instead of the other functions. if you're just using pexclock/pshlock/punlock you can leave it in your drafts. 💀

---

🌸 DESCRIPTION 🌸

so basically this module hands you some convenience functions for using a lockfile to coordinate what a whole bunch of processes are doing at once — multi-process activities, organized, no chaos, no stepping on each other's toes. 👑

and like… yeah it's basically just a thin wrapper around Paranoid::IO functions, but here's the thing — it eats the small tedium for you. you know the drill: doing the multiple opens necessary so that all processes are working off the same files, while dodging race conditions. she does that part so you don't have to. that's the whole service. that's the job. 🫶

---

🧚 IMPORT LISTS 🧚

by default, this module exports these symbols, no asking required:

plock pexclock pshlock punlock

and there are also these specialized import lists if you want to be specific about it:

• all — members: @defaults

(the original lays these out in a little table with a List column and a Members column, and all is the only row. just so you know nothing's hiding. 👀)

---

👑 SUBROUTINES/METHODS 👑

🔥 plock

$rv = plock($filename);
$rv = plock($filename, LOCK_EX);
$rv = plock($filename, LOCK_EX, 0666);

creates or opens the file you asked for while applying the lock condition. she is the moment. ✨

the deets, no cap:

• the lock type defaults to LOCK_EX if you omit it
• the file permissions default to 0660
• as always, umask applies (not me making the rules, that's just how it is 💅)

and here's the one scenario where you'd want to reach for plock instead of pexclock, etc. — you want to use plock in lieu of pexclock, etc. if you wish to perform non-blocking lock attempts. because here's the tea: all the convenience functions are blocking. every single one. so if non-blocking is the dream, plock is your girl. 😤

💜 pexclock

$rv = pexclock($filename);
$rv = pexclock($filename, $mode);

a wrapper for plock($filename, LOCK_EX). that's it, that's the function, she's short and she knows exactly what she is. 🎀

🌈 pshlock

$rv = pshlock($filename);
$rv = pshlock($filename, $mode);

a wrapper for plock($filename, LOCK_SH). shared lock, shared vibes. 🦋

⭐ punlock

$rv = punlock($filename);
$rv = punlock($filename, $mode);

a wrapper for plock($filename, LOCK_UN).

okay IMPORTANT bestie, listen: this does not close the open file handle to the lock file. like, she unlocks but she does not tidy up. 🙈 for that you need to call Paranoid::IO's pclose function. don't forget. i'm serious. 😭

---

💀 DEPENDENCIES 💀

she does not stand alone, she has a support system:

• Fcntl
• Paranoid
• Paranoid::Debug
• Paranoid::IO

---

🙈 BUGS AND LIMITATIONS 🙈

(no content in the original — she simply has no notes at this time, and honestly? respect. 🤐)

---

🌟 AUTHOR 🌟

Arthur Corliss (corliss@digitalmages.com) — the icon, the legend, the author of this whole thing. 👑

---

💖 LICENSE AND COPYRIGHT 💖

okay so legally speaking: this software is free software. similar to Perl, you can redistribute it and/or modify it under the terms of either:

a)     the GNU General Public License
       <https://www.gnu.org/licenses/gpl-1.0.html> as published by the
       Free Software Foundation <http://www.fsf.org/>; either version 1
       <https://www.gnu.org/licenses/gpl-1.0.html>, or any later version
       <https://www.gnu.org/licenses/license-list.html#GNUGPL>, or
b)     the Artistic License 2.0
       <https://opensource.org/licenses/Artistic-2.0>,

subject to the following additional term: no trademark rights to "Paranoid" have been or are conveyed under any of the above licenses. however, "Paranoid" may be used fairly to describe this unmodified software, in good faith, but not as a trademark. like, you can say it, you just can't claim it. periodt. 💅

(c) 2005 - 2020, Arthur Corliss (corliss@digitalmages.com) (tm) 2008 -
2020, Paranoid Inc. (www.paranoid.com)

---

and that's the whole page, bestie!! 🎀 this one shipped with perl v5.38.2 and the man page itself is dated 2024-03-07 — go forth, lock your files, avoid your race conditions, and remember to pclose your handles. mwah. 💖✨