FBB::Semaphore(3bobcat)

📦
version 6.15.01 · 7 versions
, in ubuntu stonking

💖 FBB::Semaphore — from 3bobcat, bestie 💖

okay so. Bestie. Sit DOWN. We're doing semaphores today and honestly? iconic. This is FBB::Semaphore, a page from section 3bobcat, and it's the whole "Implements the Semaphore type designed by Dijkstra" situation. Yes, that Dijkstra. The 1962 one. We're gonna be so normal about it. 💅

✨ NAME ✨

FBB::Semaphore — bestie, this literally implements the Semaphore type, and it was designed by Dijkstra. We stan a legend. 👑

🦋 SYNOPSIS 🦋

#include <bobcat/semaphore>

Linking option: -lpthread -lbobcat

🌸 DESCRIPTION 🌸

So per http://en.wikipedia.org/wiki/Semaphore_(programming), a semaphore is a variable or abstract data type that's used for controlling access, by multiple processes, to a common resource in a parallel programming or a multi user environment. And the Semaphore as a data type? Designed around 1962 by Edsger Dijkstra. Absolute pioneer behavior. 🎀

A useful way to think of a semaphore, bestie, is as a record of how many units of a particular resource are available — coupled with operations to safely (i.e., without race conditions, not even ONE) adjust that record as units are required or become free, and, if necessary, wait until a unit of the resource becomes available. It's giving "the clipboard at the group project," and honestly it ate.

Semaphores are a useful tool in the prevention of race conditions. Semaphores allowing an arbitrary resource count are called counting semaphores, while semaphores which are restricted to the values 0 and 1 (or locked/unlocked, unavailable/available) are called binary semaphores. Both types are supported by Bobcat's implementation. Both!! Inclusive king. 🌈

💜 NAMESPACE 💜

FBB

All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace FBB.

🫶 INHERITS FROM 🫶

-

(iconic: it inherits from nothing. standalone queen. no cap.)

🎀 CONSTRUCTORS 🎀

  • Semaphore(size_t nAvailable) — bestie, this constructor defines the semaphore's initial state. With a counting semaphore, nAvailable defines, e.g., the number of available locations in a storage area. Locking/unlocking, supporting facilities to notify other waiting threads, is implemented via binary semaphores, which are initialized to 1 or 0. A semaphore containing the value 0 blocks. I.e., its wait member waits until its value is incremented by another thread, calling one of the semaphore's notify members. 💤

Copy and move constructors (and assignment operators) are not available. Sorry bestie, no duplicating this one. 🙈

👑 MEMBER FUNCTIONS 👑

  • void notify() — the internally maintained available value is incremented and one waiting thread (cf. the wait members below) is notified, reactivating that thread. one thread gets picked, and only one. it's giving "tag, you're it." ✨
  • void notify_all() — the internally maintained available value is incremented and all waiting threads (cf. the wait members below) are notified. Only one waiting thread will be able to obtain the semaphore's lock and to reduce available, and that particular thread is thereupon reactivated. it's giving "everyone scream, but only one gets the aux." 🔥
  • void set(size_t available) — this member blocks until it has obtained the lock of the std::mutex which is maintained internally by the Semaphore object. Next the Semaphore's available value receives the value of the member's argument, and the lock is released. set and release, periodt. 💅
  • size_t size() const — without trying to lock the Semaphore object's mutex, the current value of the Semaphore's available value is returned. lowkey just a peek. no lock, no stress. 🍓
  • void wait() — this member blocks for as long as the internally stored value (available) equals zero. When returning from wait the current thread holds the lock of the std::mutex which is maintained internally by the Semaphore object. Notify members are used to increment available and to inform wait that it may return. When multiple threads are waiting only one thread will stop waiting, while the remaining threads will continue to wait for another notification. so like... one of y'all, not all of y'all. 😭
  • bool wait(Fun fun, Params &&...args) — this is a member template, where Fun is a function (object) receiving the argument passed to wait, and returning a bool. This member blocks until it has obtained the Semaphore's mutex lock, then, while its available value equals 0, waits until being notified. Once it has reacquired the lock after being notified fun is called, receiving wait's perfectly forwarded remaining arguments. This member returns false if fun returns false. It returns true if fun returns true and available was unequal zero following fun returning true. The function may therefore perform tasks outside of the Semaphore local environment, which might even involve updating the Semaphore's available value. she's flexible, she's forward-thinking, she's perfectly forwarding. 🧚
  • std::cv_status wait_for(std::chrono::duration<Rep, Period> const &relTime) — this member blocks for as long as the internally stored value (available) equals zero and the amount of time specified by relTime hasn't passed. If the latter happens, std::cv_status::timeout is returned, otherwise std::cv_status::no_timeout is returned, in which case the current thread holds the lock of the std::mutex which is maintained internally by the Semaphore object. Notify members are used to increment available and to inform wait that it may return. When multiple threads are waiting only one thread will stop waiting, while the remaining threads will continue to wait for another notification. clock is ticking bestie ⏰
  • std::cv_status wait_until(std::chrono::time_point<Clock, Duration> const &absTime) — this member blocks for as long as the internally stored value (available) equals zero and the time specified by absTime hasn't been reached. If the latter happens (or if absTime lies in the past) std::cv_status::timeout is returned, otherwise std::cv_status::no_timeout is returned, in which case the current thread holds the lock of the std::mutex which is maintained internally by the Semaphore object. Notify members are used to increment available and to inform wait that it may return. When multiple threads are waiting only one thread will stop waiting, while the remaining threads will continue to wait for another notification. same energy, but with an absolute deadline. and yes, if absTime is in the past it just times out immediately. 💀

⭐ EXAMPLE ⭐

okay here's the whole thing, verbatim, don't touch it, it's perfect:

#include <bobcat/semaphore>

using namespace FBB;

Semaphore produce(10);          // storage area size
Semaphore consume(0);           // # items in store
std::queue itemQueue;           // storage queue

void consumer()
{
    while (true)
    {
        consume.wait();          // wait until there’s an item in store

            // mutex lock the queue with multiple consumers
        size_t item = itemQueue.front();
        itemQueue.pop();

        produce.notify();   // notify the producer

        process(item);      // not implemented
    }
}

void producer()
{
    size_t item = 0;
    while (true)
    {
        ++item;
        produce.wait();     // wait for room in the storage

            // mutex lock the queue with multiple consumers
        itemQueue.push(item);

        consume.notify();   // notify the consumer
    }
}
int main()
{
    thread cons(consumer);
    thread prod(producer);

    cons.join();            // ending the threads not implemented
    prod.join();
}

producer/consumer dance, literally the classic. the way that produce and consume are just vibing with each other. 😭🔥

🎀 FILES 🎀

bobcat/semaphore — defines the class interface

🌈 SEE ALSO 🌈

bobcat(7)

💀 BUGS 💀

None Reported.

(we love a clean bill of health. not a single one. slay. ✨)

🫶 BOBCAT PROJECT FILES 🫶

Debian Bobcat project files:

  • libbobcat6: debian package containing the shared library, changelog and copyright note;
  • libbobcat-dev: debian package containing the static library, headers, manual pages, and developer info;

💜 BOBCAT 💜

Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.

This is free software, distributed under the terms of the GNU General Public License (GPL).

🎀 AUTHOR 🎀

Frank B. Brokken (f.b.brokken@rug.nl).

okay bestie that's the whole page, you're officially a semaphore girlie now 🦋 anyway this was libbobcat-dev_6.15.01, dated 2005-2026, and the page is FBB::Semaphore(3bobcat) — go forth and prevent race conditions, mwah 💖✨

📦 where this page comes from