Lucy::...e::Lock(3pm)

💖 NAME 💖

Lucy::Store::Lock — it's an abstract class, bestie, and what it represents is an interprocess mutex lock. Yes, the fancy kind. No cap.

---

✨ SYNOPSIS ✨

okay so literally the whole vibe in four lines:

my $lock = $lock_factory->make_lock(
    name    => 'write',
    timeout => 5000,
);
$lock->obtain or die "can't get lock for " . $lock->get_name;
do_stuff();
$lock->release;

that's it. that's the whole thing. lock it, do the thing, let it go. 💅

---

🦋 DESCRIPTION 🦋

So the Lock class makes an interprocess mutex lock. The default subclass is out here using dot-lock files, but like — alternative implementations are possible, so don't @ her.

Every lock has to have a name that's unique per resource being locked. Every lock also has a “host” id that should be unique per machine, and its whole job is helping clear away stale locks. it's giving janitor energy honestly.

---

🎀 CONSTRUCTORS 🎀

💫 new

my $lock = Lucy::Store::Lock->new(
    name     => 'commit',     # required
    folder   => $folder,      # required
    host     => $hostname,    # required
    timeout  => 5000,         # default: 0
    interval => 1000,         # default: 100
);

Abstract constructor. like, you can't just call it and expect a lock, bestie, it's abstract.

• folder — a Folder. that's the whole description. she's a Folder. 🫶
• name — a String identifying the resource you wanna lock. IMPORTANT: it must consist solely of characters matching [-_.A-Za-z0-9]. no emoji in your lock names, tragic i know 😭
• host — a unique per-machine identifier. her little name tag. 🏷️
• timeout — time in milliseconds to keep retrying before abandoning the attempt to obtain() a lock.
• interval — time in milliseconds between retries. the lil breather between attempts. ✨

---

👑 ABSTRACT METHODS 👑

🌸 shared

my $bool = $lock->shared();

Returns true if the Lock is shared, false if the Lock is exclusive. binary queen. 💅

⭐ request

my $bool = $lock->request();

Make one attempt to acquire the lock. one. single. attempt. no retries here, that's obtain()'s whole thing.

The semantics of request() differ depending on whether shared() returns true. If the Lock is shared(), then request() should not fail if another lock is held against the resource identified by "name" (though it might fail for other reasons, lowkey). If it is not shared() — i.e. it's an exclusive (write) lock — then other locks should cause request() to fail. periodt.

Returns: true on success, false on failure (sets the global error object returned by Clownfish->error). 🫶

💜 release

$lock->release();

Release the lock. let her go, she's free now. 🦋

🧚 is_locked

my $bool = $lock->is_locked();

Indicate whether the resource identified by this lock's name is currently locked. a vibe check, essentially.

Returns: true if the resource is locked, false otherwise.

💀 clear_stale

$lock->clear_stale();

Release all locks that meet the following three conditions: the lock name matches, the host id matches, and the process id that the lock was created under no longer identifies an active process. all three. no shortcuts. it's giving detective work 🔍

---

🌈 METHODS 🌈

🍓 obtain

my $bool = $lock->obtain();

Call request() once per "interval" until request() returns success or the "timeout" has been reached. she's persistent. she's committed. main character energy honestly. 👑

Returns: true on success, false on failure (sets the global error object returned by Clownfish->error).

---

🔥 INHERITANCE 🔥

Lucy::Store::Lock isa Clownfish::Obj. family tree, slay. 🌳

---

okay bestie that's the whole page 💖 this one shipped with perl v5.42.0 and is dated 2025-07-25 — go forth and lock things responsibly, mwah 🎀✨