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)  provides  several  types of synchronization primitives designed to be used with persistent
       memory.  The pmem-aware lock implementation is based on the standard POSIX Threads Library, as  described
       in  pthread_mutex_init(3),  pthread_rwlock_init(3)  and  pthread_cond_init(3).   Pmem-aware locks provide
       semantics similar to standard pthread locks, except that they are embedded in pmem-resident  objects  and
       are  considered  initialized  by  zeroing  them.   Therefore,  locks  allocated with pmemobj_zalloc(3) or
       pmemobj_tx_zalloc(3) do not require another initialization step.  For performance reasons, they are  also
       padded up to 64 bytes (cache line size).

       On  FreeBSD,  since all pthread locks are dynamically allocated, while the lock object is still padded up
       to 64 bytes for consistency with Linux, only the pointer to the lock is  embedded  in  the  pmem-resident
       object.  libpmemobj(7) transparently manages freeing of the locks when the pool is closed.

       The  fundamental  property  of  pmem-aware  locks  is  their  automatic  reinitialization  every time the
       persistent object store pool is opened.  Thus, all the pmem-aware locks  may  be  considered  initialized
       (unlocked)  immediately  after  the  pool  is  opened, regardless of their state at the time the pool was
       closed for the last time.

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

       The  pmemobj_mutex_zero()  function  explicitly  initializes  the  pmem-aware mutex mutexp by zeroing it.
       Initialization  is  not  necessary  if  the  object  containing  the  mutex  has  been  allocated   using
       pmemobj_zalloc(3) or pmemobj_tx_zalloc(3).

       The pmemobj_mutex_lock() function locks the pmem-aware mutex mutexp.  If the mutex is already locked, the
       calling thread will block until the mutex becomes available.  If this is the first use of the mutex since
       the opening of the pool pop, the mutex is automatically reinitialized and then locked.

       pmemobj_mutex_timedlock()  performs  the  same  action  as pmemobj_mutex_lock(), but will not wait beyond
       abs_timeout to obtain the lock before returning.

       The pmemobj_mutex_trylock() function 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.

       The pmemobj_mutex_unlock() function unlocks the pmem-aware mutex mutexp.  Undefined behavior follows 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.

       The  pmemobj_rwlock_zero()  function  is  used  to  explicitly  initialize the pmem-aware read/write lock
       rwlockp by zeroing it.  Initialization is not necessary if  the  object  containing  the  lock  has  been
       allocated using pmemobj_zalloc(3) or pmemobj_tx_zalloc(3).

       The  pmemobj_rwlock_rdlock()  function  acquires  a  read  lock on rwlockp, provided that the lock is not
       presently held for writing and no writer threads are presently blocked on the lock.   If  the  read  lock
       cannot  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()  performs  the  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.

       The pmemobj_rwlock_wrlock() function 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() performs the same action, but will not wait beyond abs_timeout to obtain the
       lock before returning.

       The pmemobj_rwlock_tryrdlock() function performs the 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.

       The pmemobj_rwlock_trywrlock() function performs the 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.

       The  pmemobj_rwlock_unlock()  function  is  used  to  release  the read/write lock previously obtained by
       pmemobj_rwlock_rdlock(),         pmemobj_rwlock_wrlock(),         pthread_rwlock_tryrdlock(),          or
       pmemobj_rwlock_trywrlock().

       The  pmemobj_cond_zero()  function  explicitly  initializes  the  pmem-aware  condition variable condp by
       zeroing it.  Initialization is not necessary if the object containing the  condition  variable  has  been
       allocated using pmemobj_zalloc(3) or pmemobj_tx_zalloc(3).

       The difference between pmemobj_cond_broadcast() and pmemobj_cond_signal() is that the former unblocks all
       threads waiting for the condition variable, whereas the latter blocks only 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.  Although neither function
       strictly enforces this requirement, undefined behavior may follow if the mutex is not held.

       The pmemobj_cond_timedwait() and pmemobj_cond_wait() functions 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

       The pmemobj_mutex_zero(), pmemobj_rwlock_zero() and pmemobj_cond_zero() functions return no value.

       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>