rtapi_mutex(3rtapi)

🎀 NAME 🎀

okay so bestie, we're reading rtapi_mutex(3rtapi) — straight out of the RTAPI manual section, three-point-r-t-a-p-i, no cap. It's the page for mutex-related functions, and honestly it's short, it's sweet, and it's giving "small but mighty" 💅

rtapi_mutex — mutex-related functions. that's it, that's the name. iconic.

---

✨ SYNTAX ✨

bestie, here's the vibe, verbatim, do not touch:

#include <rtapi_mutex.h>

int rtapi_mutex_try(unsigned long *mutex);
int rtapi_mutex_get(unsigned long *mutex);
int rtapi_mutex_give(unsigned long *mutex);

three little functions, all of them returning int, all of them taking one pointer. slay 🌸

---

🫶 ARGUMENTS 🫶

• mutex — a pointer to the mutex. that's the whole thing. just a pointer to it. lowkey the most straightforward argument in the whole library 🦋

---

💖 DESCRIPTION 💖

rtapi_mutex_try makes a non-blocking attempt to get the mutex. so it's like, hey, is the mutex free? If the mutex is available, it returns 0, and the mutex is no longer available — meaning you got it, congrats, it's yours now 👑. Otherwise, it returns a nonzero value, which is the polite Unix way of saying "nope, somebody else is holding it, try again later" 🙈

rtapi_mutex_get blocks until the mutex is available. so it just sits there, patiently, waiting for its turn, no drama, until the mutex frees up. main character energy but make it patient ✨

rtapi_mutex_give releases a mutex acquired by rtapi_mutex_try or rtapi_mutex_get. it's the "okay bestie, I'm done, it's all yours" move. please actually call it, the mutex will not release itself and we've all seen that movie 💀

---

🔥 REALTIME CONSIDERATIONS 🔥

this part is important, so listen up fr fr:

• rtapi_mutex_give and rtapi_mutex_try may be used from non-realtime, init/cleanup, and realtime code. flexible queens, we love them 🌈
• rtapi_mutex_get may not be used from realtime code.

okay so the get thing? that one is a hard no for realtime. it blocks, and blocking in realtime code is not the vibe. do not do it. the manpage says so, I say so, everybody says so 😭

---

🌟 RETURN VALUE 🌟

• rtapi_mutex_try returns 0 if the mutex was claimed, and nonzero otherwise. (yes, the original prose literally says "returns 0 for if the mutex was claimed" — we're keeping the wording energy, it's cute, it stays 🎀)
• rtapi_mutex_get and rtapi_mutex_gif have no return value.

not me pointing out that the original page says rtapi_mutex_gif there 😭 that's a typo bestie, it means rtapi_mutex_give, but we're reporting it exactly as written because facts are facts. iykyk.

---

and that's the whole page, babe. nothing hidden, nothing skipped, every last line accounted for 💜

signing off with the receipts: this one's from the LinuxCNC Documentation, dated 2006-10-12 — and the page is rtapi_mutex(3rtapi). go forth and lock responsibly, bestie 🫶✨