Semaphore(3pm)

💖 Semaphore(3pm) — the counting semaphores page, but make it cute 💖

okay bestie, welcome to the Semaphore manual page from the User Contributed Perl Documentation collection. she's a Perl module page, she's iconic, and she's about to teach you semaphores with zero gatekeeping. pull up a chair 🪑✨

---

🌸 NAME 🌸

Coro::Semaphore — counting semaphores, periodt 💅

---

✨ SYNOPSIS ✨

use Coro;

$sig = new Coro::Semaphore [initial value];

$sig->down; # wait for signal

# ... some other "thread"

$sig->up;

---

🦋 DESCRIPTION 🦋

okay so. this module implements counting semaphores. you can initialize a mutex with any level of parallel users — like, you can set up a semaphore that can be "down"ed more than once until it finally blocks. that's the whole vibe.

and listen: there is no owner associated with semaphores. none. so one thread can "down" it while another thread "ups" it (or the other way around, whatever, it's not that deep), "up" can be called before "down", and honestly the semaphore is really just an integer counter that optionally blocks when it is 0. that's her. that's the whole personality. 🔢

counting semaphores are typically used to coordinate access to resources, with the semaphore count initialized to the number of free resources. then threads increment the count when resources are added and decrement the count when resources are removed. chef's kiss, very demure, very mindful 🍓

you don't have to load Coro::Semaphore manually, bestie — it will be loaded automatically when you use Coro and call the new constructor. the module does the work, you just live your life 💅

---

👑 the methods (aka the main characters) 👑

• new [initial count] — creates a new semaphore object with the given initial lock count. the default lock count is 1, which means it is unlocked by default. zero (or negative values) are also allowed, in which case the semaphore is locked by default. yes, you can start locked. she's born that way 🙈
• $sem->count — returns the current semaphore count. the semaphore can be down'ed without blocking when the count is strictly higher than 0. so, like, count > 0 = go off, count <= 0 = wait your turn ✨
• $sem->adjust ($diff) — atomically adds the amount given to the current semaphore count. if the count becomes positive, it wakes up any waiters. does not block if the count becomes negative, however. so don't expect it to politely pause for you 😭
• $sem->down — decrement the counter, therefore "locking" the semaphore. this method waits until the semaphore is available if the counter is zero or less. it's giving patience, it's giving queue 💀
• $sem->wait — similar to down, but does not actually decrement the counter. instead, when this function returns, a following call to down or try is guaranteed to succeed without blocking, until the next thread switch (cede etc.). lowkey handy, highkey inefficient ⚠️

note that using wait is much less efficient than using down, so try to prefer down whenever possible. fr fr, listen to the manpage.

• $sem->wait ($callback) — if you pass a callback argument to wait, it will not wait, but immediately return. the callback will be called as soon as the semaphore becomes available (which might be instantly), and gets passed the semaphore as first argument. 🎀

the callback might "down" the semaphore exactly once, might wake up other threads, but is NOT allowed to block (switch to other threads). do not do it. the vibes will be ruined. 💀

• $sem->up — unlock the semaphore again. the reverse girlie. 🫶
• $sem->try — try to "down" the semaphore. returns true when this was possible, otherwise returns false and leaves the semaphore unchanged. no blocking, just a yes or a no, very honest of her 💖
• $sem->waiters — in scalar context, returns the number of threads waiting for this semaphore. might accidentally cause WW3 if called in other contexts, so don't use these. not me warning you about the apocalypse in a perl manpage 😭🌍
• $guard = $sem->guard — this method calls down and then creates a guard object. when the guard object is destroyed it automatically calls up. self-cleaning, iconic, main character energy 👑

---

🌈 AUTHOR/SUPPORT/CONTACT 🌈

Marc A. Lehmann <schmorp@schmorp.de> <http://software.schmorp.de/pkg/Coro.html>

---

and that's the page, bestie! 💜 this lil' gem was built by the perl v5.40.1 toolchain and dated 2025-03-21, and the manual page itself is filed under Semaphore(3pm). now go forth and semaphore responsibly. mwah 💋🎀🦋