QSemaphore(3qt)

📦 version 3.3.8b, in fedora 43, fedora 44

💖 QSemaphore — the it-girl of thread sync 💖

okay so bestie, gather round, because today we're talking about QSemaphore from the 3qt manual (yes, the Qt one, she's a classic 💅). Robust integer semaphore energy. No cap.

✨ NAME ✨

QSemaphore — a robust integer semaphore. that's it, that's the name, she's simple and she knows it 🎀

🦋 SYNOPSIS 🦋

All the functions in this class are thread-safe when Qt is built with thread support.</p>

(that stray </p> is literally in the original, i'm not touching it, she's vintage 🫶)

#include <qsemaphore.h>

👑 Public Members 👑

QSemaphore ( int maxcount )
virtual ~QSemaphore ()
int available () const
int total () const
int operator++ ( int )
int operator-- ( int )
int operator+= ( int n )
int operator-= ( int n )
bool tryAccess ( int n )

🌸 DESCRIPTION 🌸

so the QSemaphore class provides a robust integer semaphore. iconic.

A QSemaphore can be used to serialize thread execution, kinda like a QMutex does. but here's the tea: a semaphore differs from a mutex because a semaphore can be accessed by more than one thread at a time. main character behavior, honestly. 👑

okay imagine this — let's say we have an application that stores data in a large tree structure. the app creates 10 threads (which is commonly called a thread pool, iykyk) to perform searches on the tree. when the app searches the tree for some piece of data, it uses one thread per base node to do the searching. a semaphore could be used to make sure that two threads don't try to search the same branch of the tree at the same time. no overlapping, no chaos, we stay organized. ✨

and now for the non-computing example, because she contains multitudes: 🍓

picture dining at a restuarant. (spelling straight from the source, we respect the original 🫶) a semaphore is initialized to have a maximum count equal to the number of chairs in the restuarant. as people arrive, they want a seat. as seats are filled, the semaphore is accessed, once per person. as people leave, the access is released, allowing more people to enter. if a party of 10 people want to be seated, but there are only 9 seats, those 10 people will wait, but a party of 4 people would be seated (taking the available seats down to 5, which makes the party of 10 people wait longer). it's giving group project energy where the 10-person group just has to sit there watching. 💀

when a semaphore is created it is given a number which is the maximum number of concurrent accesses it will permit. accesses to the sempahore (yes, "sempahore", original spelling, we keep it 💜) are gained using operator++() or operator+=(), and released with operator--() or operator-=(). the number of accesses allowed is retrieved with available(), and the total number with total().

⚠️ note that the incrementing functions will block if there aren't enough available accesses. use tryAccess() if you want to acquire accesses without blocking. do not come for me when your thread is just sitting there, bestie, i warned you.

See also: Environment Classes and Threading.

🧚 MEMBER FUNCTION DOCUMENTATION 🧚

QSemaphore::QSemaphore ( int maxcount )

creates a new semaphore, fresh out the box. the semaphore can be concurrently accessed at most maxcount times. that's her limit and she's sticking to it. 🎀

QSemaphore::~QSemaphore () [virtual]

destroys the semaphore. bye bestie 👋

Warning: if you destroy a semaphore that has accesses in use, the resultant behavior is undefined. like, genuinely do not do this. this is the "we don't talk about it" section of the page. 😭

int QSemaphore::available () const

returns the number of accesses currently available to the semaphore. a lil vibe check on how much room she has left. ✨

int QSemaphore::operator++ ( int )

postfix ++ operator.

try to get access to the semaphore. if available() == 0, this call will block until it can get access, i.e. until available() > 0. she will wait. patiently. forever if she must. 🫶

int QSemaphore::operator+= ( int n )

try to get access to the semaphore. if available() < n, this call will block until it can get all the accesses it wants, i.e. until available() >= n. no partial access, no crumbs, she wants the whole thing. 💅

int QSemaphore::operator-- ( int )

postfix -- operator.

release access of the semaphore. this wakes all threads waiting for access to the semaphore. not me being the one to free everybody 🔥

int QSemaphore::operator-= ( int n )

release n accesses to the semaphore.

int QSemaphore::total () const

returns the total number of accesses to the semaphore.

bool QSemaphore::tryAccess ( int n )

try to get access to the semaphore. if available() < n, this function will return FALSE immediately. if available() >= n, this function will take n accesses and return TRUE.

this function does not block. zero waiting. instant answer. she's decisive. ⭐

💀 SEE ALSO 💀

Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. see the license file included in the distribution for a complete license statement. read it, bestie, it's good for you. 🎀

🌈 AUTHOR 🌈

Generated automatically from the source code. (yes she was born from a script, and honestly? iconic. no further notes.) 🦋

🍓 BUGS 🍓

if you find a bug in Qt, please report it as described in http://doc.trolltech.com/bughowto.html. good bug reports help us to help you. thank you. 🙏

the definitive Qt documentation is provided in HTML format; it is located at $QTDIR/doc/html and can be read using Qt Assistant or with a web browser. this man page is provided as a convenience for those users who prefer man pages, although this format is not officially supported by Trolltech. (she's a gift, not an obligation 💅)

if you find errors in this manual page, please report them to qt-bugs@trolltech.com. please include the name of the manual page (qsemaphore.3qt) and the Qt version (3.3.8). do it for her. 🫶

okay that's the whole page, and here's the cute sign-off: this icon was brought to you by Trolltech AS, dated 2 February 2007, living in Qt 3.3.8, answering to the name QSemaphore(3qt). slay, protect your threads, and never destroy a semaphore with accesses in use. periodt. 💖✨🎀

📦 where this page comes from