std::counti...acquire_for(3)

okay so bestie, you opened the std::counti...acquire_for(3) page from the C++ Standard Libary manual, and we are about to get into semaphore business 💖✨ This is try_acquire_for: atomic counter decrementing with a timeout, and yes, it's giving "I'll wait, but only for a little bit" energy. 🫶

💖 NAME 💖

• std::counting_semaphore::try_acquire_for — the function in question.
• std::counting_semaphore::try_acquire_for — yeah, it's listed again after the dash in the original NAME line, and honestly? iconic. The full NAME line is std::counting_semaphore::try_acquire_for - std::counting_semaphore::try_acquire_for.

✨ Synopsis ✨

Here's the signature exactly as the page lays it out (and yes, the (since C++20) bit is chilling in the middle because that's where it landed on the page — it's the version tag, not an argument 💅):

template< class Rep, class Period >
bool try_acquire_for( const std::chrono::duration<Rep, Period>&
(since C++20)
rel_time );

What it does: it tries to atomically decrement the internal counter by 1 if it is greater than 0. Otherwise it blocks until it is greater than 0 and can successfully decrement the internal counter, or the rel_time duration has been exceeded. Periodt. 🫶

🫶 Preconditions 🫶

(none) — literally none, bestie. No preconditions, no little checklist, no vibe check before the call.

🎀 Parameters 🎀

• rel_time — the minimum duration the function must wait for it to fail. Yes, the original says fail; that's the spec, not me being shady 😭.

🌸 Return value 🌸

true if it decremented the internal counter, otherwise false. That's it, that's the booleans, no cap.

💀 Exceptions 💀

May throw std::system_error or a timeout-related exception. So that's the exception menu, bestie — keep it in mind.

🧚 Notes 🧚

In practice the function may take longer than rel_time to fail. So don't treat rel_time like a perfectly exact little timer; the page literally says it may take longer, fr fr.

👑 See also 👑

• release — increments the internal counter and unblocks acquirers (public member function).
• acquire — decrements the internal counter or blocks until it can (public member function).
• try_acquire — tries to decrement the internal counter without blocking (public member function).
• try_acquire_until — tries to decrement the internal counter, blocking until a point in time (public member function).

xoxo, your semaphore bestie 💅 — this page is from the C++ Standard Libary manual (yeah, that's the manual name), sourced from http://cppreference.com, dated 2024.06.10, and it's the std::counti...acquire_for(3) page. periodt. 🦋