qthread_empty/fill(3)

👑 qthread_empty/fill(3) — the libqthread glow-up 💅

okay bestie sit DOWN because we're doing libqthread today and honestly? this one's short and sweet, main character energy, no notes. 🎀

✨ NAME ✨

qthread_empty, qthread_fill — sets the given address to either "empty" or "full"

like literally that's the whole job. setting a vibe. empty or full. that's it. 🦋

🌸 SYNOPSIS 🌸

#include <qthread.h>

int
qthread_empty (const aligned_t *dest);

int
qthread_fill (const aligned_t *dest);

💖 DESCRIPTION 💖

so the qthread_empty() and qthread_fill() functions assert the empty or full state of the given dest addresses. and like, the way that they do not wait for the addresses to be in any particular state?? iconic. they just say the thing and move on. no blocking, no waiting, no drama. ⭐

the me argument is used for memory pooling purposes. memory is allocated on a per-shepherd basis (to avoid needing to protect the memory pool), so it needs to know which shepherd it is currently on. HOWEVER — and this is the important part bestie — this argument is merely an optimization; these functions CAN figure out which pools to use without this information (i.e. if the me argument is NULL). so it's giving optional. it's giving nice-to-have. 🫶

note that

qthread_empty( addr )

is slightly faster than

qthread_empty( addr )

😭 bestie this is fr fr what the page says, word for word — qthread_empty( addr ) versus qthread_empty( addr ). almost certainly a lil copy-paste moment in the original where the second one was meant to be a different function, but your girl does not invent details, so here it is exactly as written. iykyk 🙈

🔥 RETURN VALUE 🔥

on success, the full/empty bits are modified and 0 is returned. on error, a non-zero error code is returned. so like, 0 = slay, anything else = not slay. 💀

🎀 ERRORS 🎀

• ENOMEM — not enough memory could be allocated. this may be because a temporary thread needed to be created, or because a management structure needed to be created. (translation: the system ran out of room to do the thing, either for a temp thread or for a management structure. sad but real.) 😭

🌈 SEE ALSO 🌈

• qthread_writeF(3)
• qthread_writeEF(3)
• qthread_readFF(3)
• qthread_readFE(3)
• qthread_lock(3)
• qthread_unlock(3)

and that's the whole page bestie, we ate and left no crumbs 💅

libqthread · APRIL 2011 — mwah, xoxo, go forth and assert your full/empty bits 🧚💜