PMEMOBJ_MUTEX_ZERO(3)

💖 PMEMOBJ_COND_BROADCAST(3) 💖

okay bestie, welcome to the PMDK Programmer's Manual ✨ this one is all about pmemobj synchronization primitives, and honestly? it's giving "locks but make them persistent" 👑

---

🌸 NAME 🌸

pmemobj_mutex_zero(), pmemobj_mutex_lock(), pmemobj_mutex_timedlock(), pmemobj_mutex_trylock(), pmemobj_mutex_unlock(),

pmemobj_rwlock_zero(), pmemobj_rwlock_rdlock(), pmemobj_rwlock_wrlock(), pmemobj_rwlock_timedrdlock(), pmemobj_rwlock_timedwrlock(), pmemobj_rwlock_tryrdlock(), pmemobj_rwlock_trywrlock(), pmemobj_rwlock_unlock(),

pmemobj_cond_zero(), pmemobj_cond_broadcast(), pmemobj_cond_signal(), pmemobj_cond_timedwait(), pmemobj_cond_wait() — pmemobj synchronization primitives 🎀

---

✨ SYNOPSIS ✨

#include <libpmemobj.h>

void pmemobj_mutex_zero(PMEMobjpool *pop, PMEMmutex *mutexp);
int pmemobj_mutex_lock(PMEMobjpool *pop, PMEMmutex *mutexp);
int pmemobj_mutex_timedlock(PMEMobjpool *pop, PMEMmutex *restrict mutexp,
    const struct timespec *restrict abs_timeout);
int pmemobj_mutex_trylock(PMEMobjpool *pop, PMEMmutex *mutexp);
int pmemobj_mutex_unlock(PMEMobjpool *pop, PMEMmutex *mutexp);

void pmemobj_rwlock_zero(PMEMobjpool *pop, PMEMrwlock *rwlockp);
int pmemobj_rwlock_rdlock(PMEMobjpool *pop, PMEMrwlock *rwlockp);
int pmemobj_rwlock_wrlock(PMEMobjpool *pop, PMEMrwlock *rwlockp);
int pmemobj_rwlock_timedrdlock(PMEMobjpool *pop, PMEMrwlock *restrict rwlockp,
    const struct timespec *restrict abs_timeout);
int pmemobj_rwlock_timedwrlock(PMEMobjpool *pop, PMEMrwlock *restrict rwlockp,
    const struct timespec *restrict abs_timeout);
int pmemobj_rwlock_tryrdlock(PMEMobjpool *pop, PMEMrwlock *rwlockp);
int pmemobj_rwlock_trywrlock(PMEMobjpool *pop, PMEMrwlock *rwlockp);
int pmemobj_rwlock_unlock(PMEMobjpool *pop, PMEMrwlock *rwlockp);

void pmemobj_cond_zero(PMEMobjpool *pop, PMEMcond *condp);
int pmemobj_cond_broadcast(PMEMobjpool *pop, PMEMcond *condp);
int pmemobj_cond_signal(PMEMobjpool *pop, PMEMcond *condp);
int pmemobj_cond_timedwait(PMEMobjpool *pop, PMEMcond *restrict condp,
    PMEMmutex *restrict mutexp, const struct timespec *restrict abs_timeout);
int pmemobj_cond_wait(PMEMobjpool *pop, PMEMcond *restrict condp,
    PMEMmutex *restrict mutexp);

---

💅 DESCRIPTION 💅

libpmemobj(7) hands you a whole lil squad of synchronization primitives, all built to hang out with persistent memory. The pmem-aware lock implementation is based on the standard POSIX Threads Library, exactly like pthread_mutex_init(3), pthread_rwlock_init(3) and pthread_cond_init(3) describe. 🧚

So here's the tea: pmem-aware locks give you semantics similar to standard pthread locks, except that they're embedded inside pmem-resident objects and they count as initialized just by zeroing them. That means locks you got from pmemobj_zalloc(3) or pmemobj_tx_zalloc(3) need literally no extra init step — slay. 💖 And for performance reasons, they're also padded up to 64 bytes (cache line size). 👑

The fundamental property of pmem-aware locks is their automatic reinitialization every single time the persistent object store pool is opened. So like, all the pmem-aware locks may be considered initialized (unlocked) immediately after the pool is opened, no matter what state they were in when the pool was last closed. iconic behavior fr fr ✨

Pmem-aware mutexes, read/write locks and condition variables must be declared with the PMEMmutex, PMEMrwlock, or PMEMcond type, respectively.

---

🔒 the mutex girlies 🔒

• pmemobj_mutex_zero() — explicitly initializes the pmem-aware mutex mutexp by zeroing it. You don't need to do this if the object containing the mutex was allocated using pmemobj_zalloc(3) or pmemobj_tx_zalloc(3). 💤
• pmemobj_mutex_lock() — locks the pmem-aware mutex mutexp. If the mutex is already locked, the calling thread will block until the mutex becomes available. And if this is the first use of the mutex since the opening of the pool pop, the mutex is automatically reinitialized and then locked. no cap 🫶
• pmemobj_mutex_timedlock() — does the same thing as pmemobj_mutex_lock(), but will not wait beyond abs_timeout to obtain the lock before returning. clock's ticking bestie ⏰
• pmemobj_mutex_trylock() — locks pmem-aware mutex mutexp. If the mutex is already locked, pthread_mutex_trylock() will not block waiting for the mutex, but will return an error. If this is the first use of the mutex since the opening of the pool pop, the mutex is automatically reinitialized and then locked. lowkey impatient energy, love that 💅
• pmemobj_mutex_unlock() — unlocks the pmem-aware mutex mutexp.

⚠️ undefined behavior alert: if a thread tries to unlock a mutex that has not been locked by it, or if a thread tries to release a mutex that is already unlocked or has not been initialized, that's UB territory. don't do it 💀

---

🦋 the read/write lock girlies 🦋

• pmemobj_rwlock_zero() — explicitly initializes the pmem-aware read/write lock rwlockp by zeroing it. Again, no initialization needed if the object containing the lock was allocated using pmemobj_zalloc(3) or pmemobj_tx_zalloc(3). ✨
• pmemobj_rwlock_rdlock() — acquires a read lock on rwlockp, provided the lock isn't presently held for writing and no writer threads are presently blocked on the lock. If the read lock can't be acquired immediately, the calling thread blocks until it can acquire the lock. If this is the first use of the lock since the opening of the pool pop, the lock is automatically reinitialized and then acquired. 🌸
• pmemobj_rwlock_timedrdlock() — same action as pmemobj_rwlock_rdlock(), but will not wait beyond abs_timeout to obtain the lock before returning. A thread may hold multiple concurrent read locks. If so, pmemobj_rwlock_unlock() must be called once for each lock obtained. The results of acquiring a read lock while the calling thread holds a write lock are undefined. 🙈
• pmemobj_rwlock_wrlock() — blocks until a write lock can be acquired against read/write lock rwlockp. If this is the first use of the lock since the opening of the pool pop, the lock is automatically reinitialized and then acquired. 🔥
• pmemobj_rwlock_timedwrlock() — same action, but will not wait beyond abs_timeout to obtain the lock before returning. ⏳
• pmemobj_rwlock_tryrdlock() — same action as pmemobj_rwlock_rdlock(), but does not block if the lock cannot be immediately obtained. The results are undefined if the calling thread already holds the lock at the time the call is made. 💀
• pmemobj_rwlock_trywrlock() — same action as pmemobj_rwlock_wrlock(), but does not block if the lock cannot be immediately obtained. The results are undefined if the calling thread already holds the lock at the time the call is made. 💀
• pmemobj_rwlock_unlock() — releases the read/write lock previously obtained by pmemobj_rwlock_rdlock(), pmemobj_rwlock_wrlock(), pthread_rwlock_tryrdlock(), or pmemobj_rwlock_trywrlock(). bye bye lock 👋

---

🎀 the condition variable girlies (yes this is the main character of this page) 🎀

• pmemobj_cond_zero() — explicitly initializes the pmem-aware condition variable condp by zeroing it. Initialization is not necessary if the object containing the condition variable was allocated using pmemobj_zalloc(3) or pmemobj_tx_zalloc(3). 🧚
• pmemobj_cond_broadcast() vs pmemobj_cond_signal() — the difference between them is that the former unblocks all threads waiting for the condition variable, whereas the latter only unblocks one waiting thread. If no threads are waiting on condp, neither function has any effect. If more than one thread is blocked on a condition variable, the used scheduling policy determines the order in which threads are unblocked. The same mutex used for waiting must be held while calling either function.

⚠️ neither function strictly enforces that "hold the mutex" requirement, but undefined behavior may follow if the mutex is not held. so like... hold it bestie 💅

• pmemobj_cond_timedwait() and pmemobj_cond_wait() — these block on a condition variable. They must be called with mutex mutexp locked by the calling thread, or undefined behavior results. 😭 These functions atomically release mutex mutexp and cause the calling thread to block on the condition variable condp; "atomically" here means "atomically with respect to access by another thread to the mutex and then the condition variable". That is, if another thread is able to acquire the mutex after the about-to-block thread has released it, then a subsequent call to pmemobj_cond_broadcast() or pmemobj_cond_signal() in that thread will behave as if it were issued after the about-to-block thread has blocked. Upon successful return, the mutex will be locked and owned by the calling thread. 👑

---

🌈 RETURN VALUE 🌈

pmemobj_mutex_zero(), pmemobj_rwlock_zero() and pmemobj_cond_zero() return no value. nothing. silence. 💤

All the other locking functions return 0 on success. Otherwise, an error number will be returned to indicate the error. ⭐

---

👑 SEE ALSO 👑

pmemobj_tx_zalloc(3), pmemobj_zalloc(3), pthread_cond_init(3), pthread_mutex_init(3), pthread_rwlock_init(3), libpmem(7), libpmemobj(7) and https://pmem.io 🫶

---

and that's the whole page bestie, you ate it fr fr 💖 this one's from the PMDK crew, dated 2025-07-24 — go forth and lock responsibly, mwah 💅✨🌸