PTHREAD...ETROBUST(3POSIX)

🌸 PTHREAD_MUTEXATTR_GETROBUST, PTHREAD_MUTEXATTR_SETROBUST — the robust mutex tea ☕

okay bestie, so this page lives in the POSIX Programmer's Manual (that's the manual name, keep it in your notes 💅). It's PTHREAD...ETROBUST(3POSIX) and it's literally about one single little mutex attribute. tiny page, big drama. let's get into it 🫶

---

✨ PROLOG ✨

This manual page is part of the POSIX Programmer's Manual. Real talk though: the Linux implementation of this interface may differ — so go consult the corresponding Linux manual page for the actual Linux behavior — or honestly the interface may not be implemented on Linux at all. no cap. 💀

---

🎀 NAME 🎀

pthread_mutexattr_getrobust, pthread_mutexattr_setrobust — get and set the mutex robust attribute. that's it, that's the whole job. iconic.

---

🦋 SYNOPSIS 🦋

#include <pthread.h>

int pthread_mutexattr_getrobust(const pthread_mutexattr_t *restrict
    attr, int *restrict robust);
int pthread_mutexattr_setrobust(pthread_mutexattr_t *attr,
    int robust);

---

💖 DESCRIPTION 💖

So. pthread_mutexattr_getrobust() and pthread_mutexattr_setrobust() respectively shall get and set the mutex robust attribute. the value lives in the robust parameter. and the valid values for robust are:

• PTHREAD_MUTEX_STALLED — no special actions get taken if the owner of the mutex gets terminated while still holding the mutex lock 😭. which, yeah, can lead to deadlocks if no other thread can unlock that mutex. this one is the default value, btw. the low-effort option.
• PTHREAD_MUTEX_ROBUST — this is where it gets interesting ✨. If the process containing the owning thread of a robust mutex terminates while holding the mutex lock, the next thread that acquires the mutex shall be notified about the termination via the return value [EOWNERDEAD] from the locking function. If the owning thread of a robust mutex terminates while holding the mutex lock, the next thread that attempts to acquire the mutex may be notified about the termination via the return value [EOWNERDEAD]. (note the shall vs. may, bestie, that distinction is doing WORK 🔥)

So the notified thread can then try to make the state protected by the mutex consistent again, and if that goes well it can mark the mutex state as consistent by calling pthread_mutex_consistent(). After a subsequent successful call to pthread_mutex_unlock(), the mutex lock shall be released and can be used normally by other threads. slay.

BUT — and this is the part where we gasp 🙈 — if the mutex is unlocked without a call to pthread_mutex_consistent(), it shall be in a permanently unusable state and every single attempt to lock that mutex shall fail with the error [ENOTRECOVERABLE]. the only permissible operation on such a mutex is pthread_mutex_destroy(). that's it. that's the whole menu.

⚠️ also: the behavior is undefined if the value specified by the attr argument to pthread_mutexattr_getrobust() or pthread_mutexattr_setrobust() does not refer to an initialized mutex attributes object. undefined behavior is not a vibe, protect yourself 💅

---

⭐ RETURN VALUE ⭐

Upon successful completion, pthread_mutexattr_getrobust() shall return zero and store the value of the robust attribute of attr into the object referenced by the robust parameter. Otherwise, an error value shall be returned to indicate the error.

If successful, pthread_mutexattr_setrobust() shall return zero; otherwise, an error number shall be returned to indicate the error.

zero = good. anything else = go read the errors section, bestie 🧚

---

🌈 ERRORS 🌈

pthread_mutexattr_setrobust() shall fail if:

• EINVAL — the value of robust is invalid. (you gave it a fake value, it's not playing along 💀)

These functions shall not return an error code of [EINTR]. nope. never. not a thing here.

📌 the following sections are informative. (i.e. not normative, but still cute and useful.)

---

🍓 EXAMPLES 🍓

None.

...yeah. none. we move. 🎀

---

💜 APPLICATION USAGE 💜

The actions required to make the state protected by the mutex consistent again are solely dependent on the application. that's on you, babe, the standard is not doing that for you.

If it is not possible to make the state of a mutex consistent, robust mutexes can be used to notify this situation by calling pthread_mutex_unlock() without a prior call to pthread_mutex_consistent(). (yes, on purpose. it's a signal, not a mistake 🫶)

If the state is declared inconsistent by calling pthread_mutex_unlock() without a prior call to pthread_mutex_consistent(), a possible approach could be to destroy the mutex and then reinitialize it. However, it should be noted that this is possible only in certain situations where the state protected by the mutex has to be reinitialized and coordination achieved with other threads blocked on the mutex — because otherwise a call to a locking function with a reference to a mutex object invalidated by a call to pthread_mutex_destroy() results in undefined behavior. 🚨

so like... destroy-and-reinit is not a free-for-all. it's a very specific move for a very specific situation. do not freestyle this. 💅

---

🔥 RATIONALE 🔥

If an implementation detects that the value specified by the attr argument to pthread_mutexattr_getrobust() or pthread_mutexattr_setrobust() does not refer to an initialized mutex attributes object, it is recommended that the function should fail and report an [EINVAL] error. that's the recommendation. take it. ✨

---

👑 FUTURE DIRECTIONS 👑

None.

---

🌟 SEE ALSO 🌟

• pthread_mutex_consistent()
• pthread_mutex_destroy()
• pthread_mutex_lock()

And from the Base Definitions volume of POSIX.1‐2017: <pthread.h>

---

💌 COPYRIGHT 💌

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

---

and that's the whole page, bestie!! 🎀✨ this one's brought to you by IEEE/The Open Group, 2017 — go forth, make your mutexes robust, and please remember to call pthread_mutex_consistent() before you unlock. love u, bye 💖🦋🌸