SEMA(9)

✨ SEMA(9) — kernel counting semaphore ✨

okay bestie, we're in the Kernel Developer's Manual today and the topic is sema — the kernel's counting semaphore, plus its whole little friend group: sema_init, sema_destroy, sema_post, sema_wait, sema_timedwait, sema_trywait, and sema_value. 💖

---

🌸 NAME 🌸

sema, sema_init, sema_destroy, sema_post, sema_wait, sema_timedwait, sema_trywait, sema_value — kernel counting semaphore. yes queen, that's the whole roster. 💅

---

✨ SYNOPSIS ✨

#include <sys/types.h>
#include <sys/lock.h>
#include <sys/sema.h>

void
sema_init(struct sema *sema, int value, const char *description);

void
sema_destroy(struct sema *sema);

void
sema_post(struct sema *sema);

void
sema_wait(struct sema *sema);

int
sema_timedwait(struct sema *sema, int timo);

int
sema_trywait(struct sema *sema);

int
sema_value(struct sema *sema);

like. look at that. so organized. 🎀

---

🦋 DESCRIPTION 🦋

okay so counting semaphores are a mechanism for synchronizing access to a pool of resources. and here's the thing that makes them ✨different✨ from mutexes: semaphores do not have the concept of an owner. so they're also useful in situations where one thread needs to acquire a resource and <em>another</em> thread needs to release it. not me being flexible and unbothered. 💅

every semaphore has an integer value attached to it. posting (incrementing) always succeeds — no notes, iconic behavior. but waiting (decrementing) can only successfully complete if the resulting value of the semaphore is greater than or equal to zero. so if it'd go negative? nope. denied. 🙈

lowkey important: semaphores should not be used where mutexes and condition variables will suffice. semaphores are a <em>more complex</em> synchronization mechanism than mutexes and condition variables, and they are <em>not as efficient</em>. bestie I'm just the messenger. 💀

here's the whole lifecycle, step by step:

• semaphores are created with sema_init(), where sema is a pointer to space for a struct sema, value is the initial value of the semaphore, and description is a pointer to a null-terminated character string that describes the semaphore.
• semaphores are destroyed with sema_destroy().
• a semaphore is posted (incremented) with sema_post().
• a semaphore is waited on (decremented) with sema_wait(), sema_timedwait(), or sema_trywait(). the timo argument to sema_timedwait() specifies the minimum time in ticks to wait before returning with failure.
• sema_value() is used to read the current value of the semaphore.

---

💜 RETURN VALUES 💜

the sema_value() function returns the current value of the semaphore. simple. clean. ate. ✨

if decrementing the semaphore would result in its value being negative, sema_trywait() returns 0 to indicate failure. otherwise, a non-zero value is returned to indicate success. (yes bestie, that's backwards from what your gut says. read it again. it's fine. 🫶)

the sema_timedwait() function returns 0 if waiting on the semaphore succeeded; otherwise a non-zero error code is returned.

---

😭 ERRORS 😭

the sema_timedwait() function will fail if:

• [EWOULDBLOCK] — Timeout expired.

that's it. that's the list. one (1) whole error. she's low maintenance. 💅

---

👑 SEE ALSO 👑

condvar(9), locking(9), mtx_pool(9), mutex(9), rwlock(9), sx(9)

go read those too, they're all in the same friend group fr fr 🧚

---

and that's the whole page bestie!! this one came from <strong>Debian</strong>, dated <strong>February 1, 2006</strong> — yes, she's vintage, she's classic, she's still out here synchronizing your kernel. periodt. 💖✨🎀