Future::Mutex(3pm)

✨ NAME ✨

Future::Mutex — a mutual exclusion lock around code that returns Futures 💅

---

🌸 SYNOPSIS 🌸

use Future::Mutex;

my $mutex = Future::Mutex->new;

sub do_atomically
{
   return $mutex->enter( sub {
      ...
      return $f;
   });
}

---

🦋 DESCRIPTION 🦋

okay so bestie, listen. most Future-using code is out here living its best life with some level of concurrency, right? it uses future instances to represent still-pending operations that'll finish at some later time. iconic behaviour. but lowkey there are occasions when that concurrency needs to be restricted — some operations that, once started, must not be interrupted until they're complete. and the subsequent requests to do the same operation while one is still outstanding? yeah, they gotta be queued to wait until the first one is finished. these situations are literally begging for a mutual-exclusion lock, aka a "mutex". periodt.

a Future::Mutex instance provides one basic operation, which will execute a given block of code that returns a future, and itself returns a future to represent that. she can be in one of two states: either unlocked or locked. 🫶

while she's unlocked, requests to execute code get handled immediately. but the second a block of code is invoked, the mutex is now considered locked, which causes any subsequent requests to invoke code to be queued behind the first one until it completes. once the initial code indicates completion (by its returned future providing a result or failing — either way), the next queued code is invoked. no cap. 🔥

an instance may also be a counting mutex if initialised with a count greater than one. in that case, she can keep multiple blocks outstanding up to that limit, with subsequent requests queued as before. this lets her act as a concurrency-bounding limit around some operation that can run concurrently, but where an application wishes to apply overall limits to stop it growing too much — like communications with external services, or executing other programs. it's giving responsible. 👑

---

🎀 CONSTRUCTOR 🎀

💖 new

$mutex = Future::Mutex->new( count => $n );

returns a new Future::Mutex instance. she starts out unlocked. ✨

takes the following named arguments:

• count => INT — optional number to limit outstanding concurrency. will default to 1 if you don't supply it. 🍓

---

💅 METHODS 💅

🌈 enter

$f = $mutex->enter( \&code );

returns a new Future that represents the eventual result of calling the code. if the mutex is currently unlocked, the code will be invoked immediately. if she's currently locked, the code will be queued, waiting for the next time it becomes unlocked. 💜

the code is invoked with no arguments, and is expected to return a Future. the eventual result of that future determines the result of the future that enter returned. it's the main character energy chain of futures tbh.

⭐ available

$avail = $mutex->available;

returns true if the mutex is currently unlocked, or false if she's locked. simple as that bestie. 🌸

---

👑 AUTHOR 👑

Paul Evans <leonerd@leonerd.org.uk>

---

that's the whole page, babes 💖 this one's perl v5.40.1 flavour, dated 2025-09-22, and it's part of the User Contributed Perl Documentation — go forth and lock responsibly, mwah 🎀🦋✨