PTHREAD_COND_DESTROY(3P)

💖 PTHREAD_COND_DESTROY(3P) — the POSIX Programmer's Manual one, bestie 💖

okay so before we even start: this page lives in the POSIX Programmer's Manual, and the Linux implementation of this interface may be different from what POSIX says (so go check the matching Linux man page for the deets), or honestly the interface might not even be implemented on Linux at all. 🙈

---

✨ PROLOG ✨

This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface may differ (consult the corresponding Linux manual page for details of Linux behavior), or the interface may not be implemented on Linux.

literally the same thing I just said, but now it's official 💅

---

🎀 NAME 🎀

pthread_cond_destroy, pthread_cond_init — destroy and initialize condition variables. that's it, that's the whole vibe. 🦋

---

🌸 SYNOPSIS 🌸

#include <pthread.h>

int pthread_cond_destroy(pthread_cond_t *cond);
int pthread_cond_init(pthread_cond_t *restrict cond,
    const pthread_condattr_t *restrict attr);
pthread_cond_t cond = PTHREAD_COND_INITIALIZER;

---

💜 DESCRIPTION 💜

so pthread_cond_destroy() shall destroy the condition variable you hand it via cond, and after that the object is basically uninitialized. an implementation is allowed to set the thing cond points at to an invalid value. a destroyed condition variable can be brought back to life with pthread_cond_init(), but if you reference the object any other way after destroying it, the results are undefined. 🙈 no cap.

it shall be safe to destroy an initialized condition variable that has no threads currently blocked on it. but trying to destroy a condition variable while other threads are still blocked on it? that's undefined behavior, bestie. don't do it. 💀

pthread_cond_init() shall initialize the condition variable cond points at, using the attributes that attr points at. if attr is NULL, the default condition variable attributes get used — the effect is the same as passing the address of a default condition variable attributes object. once it initializes successfully, the condition variable's state becomes initialized. ✨

also see Section 2.9.9, Synchronization Object Copies and Alternative Mappings, for the further requirements. iykyk.

trying to initialize an already-initialized condition variable? undefined behavior. periodt.

when the default condition variable attributes are what you want, you can use the macro PTHREAD_COND_INITIALIZER to initialize condition variables. its effect shall be equivalent to dynamic initialization via a call to pthread_cond_init() with the attr parameter set to NULL — except that no error checks are performed. 👑

the behavior is undefined if the value you pass as the cond argument to pthread_cond_destroy() doesn't refer to an initialized condition variable.

and the behavior is undefined if the value you pass as the attr argument to pthread_cond_init() doesn't refer to an initialized condition variable attributes object.

---

🔥 RETURN VALUE 🔥

if everything goes well, pthread_cond_destroy() and pthread_cond_init() shall return zero. otherwise, an error number shall be returned to tell you what went wrong. simple as. 🫶

---

🌈 ERRORS 🌈

the pthread_cond_init() function shall fail if:

• EAGAIN — the system lacked the necessary resources (other than memory) to initialize another condition variable. 😭
• ENOMEM — insufficient memory exists to initialize the condition variable. 💀

these functions shall not return an error code of [EINTR]. nope, never, not happening. ✋

the following sections are informative (aka: lore, not law).

---

🍓 EXAMPLES 🍓

you can destroy a condition variable immediately after all the threads blocked on it are awakened. for example, consider this code:

struct list {
    pthread_mutex_t lm;
    ...
}

struct elt {
    key k;
    int busy;
    pthread_cond_t notbusy;
    ...
}

/* Find a list element and reserve it. */
struct elt *
list_find(struct list *lp, key k)
{
    struct elt *ep;

    pthread_mutex_lock(&lp->lm);
    while ((ep = find_elt(l, k) != NULL) && ep->busy)
        pthread_cond_wait(&ep->notbusy, &lp->lm);
    if (ep != NULL)
        ep->busy = 1;
    pthread_mutex_unlock(&lp->lm);
    return(ep);
}

delete_elt(struct list *lp, struct elt *ep)
{
    pthread_mutex_lock(&lp->lm);
    assert(ep->busy);
    ... remove ep from list ...
    ep->busy = 0;  /* Paranoid. */
(A) pthread_cond_broadcast(&ep->notbusy);
    pthread_mutex_unlock(&lp->lm);
(B) pthread_cond_destroy(&ep->notbusy);
    free(ep);
}

in this example, the condition variable and its list element can be freed (that's line B) right after all the threads waiting for it get awakened (that's line A), because the mutex and the code make sure no other thread can touch the element that's getting deleted. chef's kiss, honestly. 👩‍🍳💋

---

🧚 APPLICATION USAGE 🧚

None.

yeah bestie, there's literally nothing here. iconic of them. 💅

---

⭐ RATIONALE ⭐

if an implementation notices that the value given as the cond argument to pthread_cond_destroy() doesn't refer to an initialized condition variable, it's recommended that the function should fail and report an [EINVAL] error.

if an implementation notices that the value given as the cond argument to pthread_cond_destroy() or pthread_cond_init() refers to a condition variable that's in use by another thread (like, say, inside a pthread_cond_wait() call) — or notices that the value given as the cond argument to pthread_cond_init() refers to an already initialized condition variable — it's recommended that the function should fail and report an [EBUSY] error.

if an implementation notices that the value given as the attr argument to pthread_cond_init() doesn't refer to an initialized condition variable attributes object, it's recommended that the function should fail and report an [EINVAL] error.

see also pthread_mutex_destroy().

---

🦋 FUTURE DIRECTIONS 🦋

None.

again. nothing. the future is a blank canvas, babe. ✨

---

👑 SEE ALSO 👑

• pthread_cond_broadcast()
• pthread_cond_timedwait()
• pthread_mutex_destroy()

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 lil bop of a document is brought to you by IEEE/The Open Group, dated 2017 — mwah, love that for us. go forth and initialize your condition variables responsibly, and remember: no destroying them while threads are still blocked. periodt. 💜👑