Thread::Semaphore(3pm)

📦
version 5.42.3 · 9 versions
, in alpine 3.24

💅 Thread::Semaphore

okay so bestie, this is the manual page for Thread::Semaphore — that's the Perl module name, and the manpage lives in section 3pm (Perl Programmers Reference Guide, iykyk). Thread-safe semaphores, babes. Let's get into it ✨

🌸 VERSION

This doc describes Thread::Semaphore version 2.13. That's the number, don't come for me 🎀

✨ SYNOPSIS

use Thread::Semaphore;
my $s = Thread::Semaphore->new();
$s->down();   # Also known as the semaphore P operation.
# The guarded section is here
$s->up();     # Also known as the semaphore V operation.

# Decrement the semaphore only if it would immediately succeed.
if ($s->down_nb()) {
    # The guarded section is here
    $s->up();
}

# Forcefully decrement the semaphore even if its count goes below 0.
$s->down_force();

# The default value for semaphore operations is 1
my $s = Thread::Semaphore->new($initial_value);
$s->down($down_value);
$s->up($up_value);
if ($s->down_nb($down_value)) {
    ...
    $s->up($up_value);
}
$s->down_force($down_value);

🦋 DESCRIPTION

So what even is a semaphore? Glad you asked, bestie 💖 A semaphore is a mechanism to regulate access to resources. And here's the iconic part: unlike locks, semaphores aren't tied to any particular scalars, so you can literally use them to control access to anything you care to use them for. main character energy honestly 👑

Also, semaphores do not limit their values to just zero and one — so they're perfect for controlling access to a resource where there might be more than one of it (e.g., filehandles 🗂️). And the increment/decrement amounts aren't fixed at one either, so threads can reserve or return multiple resources at once. Slay.

💅 METHODS

->new()

->new(NUMBER)

new creates a new semaphore and initializes its count to the specified number (which must be an integer). If you don't give it a number, the semaphore's count defaults to 1. Cute and low-maintenance 🎀

->down()

->down(NUMBER)

The down method decreases the semaphore's count by the specified number (which must be an integer >= 1), or by one if no number is specified.

If the semaphore's count would drop below zero, this method will block until such time as the semaphore's count is greater than or equal to the amount you're downing the semaphore's count by. So like... it just waits. Patient queen behavior 😌

This is the semaphore "P operation" — the name derives from the Dutch word "pak", which means "capture". The semaphore operations were named by the late Dijkstra, who was Dutch. History lesson AND a vibe, we love to see it 📚

->down_nb()

->down_nb(NUMBER)

The down_nb method attempts to decrease the semaphore's count by the specified number (which must be an integer >= 1), or by one if no number is specified. Note the "attempts" — this one isn't about to sit around waiting 🙈

If the semaphore's count would drop below zero, this method will return false, and the semaphore's count remains unchanged. Otherwise, the semaphore's count is decremented and this method returns true. No blocking, no drama.

->down_force()

->down_force(NUMBER)

The down_force method decreases the semaphore's count by the specified number (which must be an integer >= 1), or by one if no number is specified. This method does not block, and — hear me out — it may cause the semaphore's count to drop below zero. Yes, below zero. It's giving "I do what I want" 💀

->down_timed(TIMEOUT)

->down_timed(TIMEOUT, NUMBER)

The down_timed method attempts to decrease the semaphore's count by 1 or by the specified number within the specified timeout period given in seconds (which must be an integer >= 0). Deadline queen ⏰

If the semaphore's count would drop below zero, this method will block until either the semaphore's count is greater than or equal to the amount you're downing the semaphore's count by, or until the timeout is reached.

If the timeout is reached, this method will return false, and the semaphore's count remains unchanged. Otherwise, the semaphore's count is decremented and this method returns true. Best of both worlds, honestly 🫶

->up()

->up(NUMBER)

The up method increases the semaphore's count by the number specified (which must be an integer >= 1), or by one if no number is specified.

This will unblock any thread that is blocked trying to down the semaphore — but only if the up raises the semaphore's count above the amount that the down is trying to decrement it by. Example time, because this one's a little spicy: if three threads are blocked trying to down a semaphore by one, and another thread ups the semaphore by two, then two of the blocked threads will become unblocked. Which two? Indeterminate. We don't know, nobody knows, it's a mystery 🔥

This is the semaphore "V operation" — the name derives from the Dutch word "vrij", which means "release". Iconic etymology moment, part two 🌷

🧚 NOTES

Semaphores created by Thread::Semaphore can be used in both threaded and non-threaded applications. Which means you can write modules and packages that potentially make use of semaphores, and they'll function in either environment. Versatile king 👑✨

🌈 SEE ALSO

💜 MAINTAINER

Jerry D. Hedden, <jdhedden AT cpan DOT org> — thank you for your service bestie 🫡

📜 LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

okay that's the whole page, no cap. every flag, every method, every Dutch etymology — all here, all accounted for 💖

and finally, the cute sign-off: this page is from perl v5.42.3, dated 2026-11-03, and it's Thread::Semaphore(3pm) — that's the footer info, folded in with love 🎀 bye bestie! 🌸

📦 where this page comes from