1PMEMOBJ_MUTEX_ZERO(3)      PMDK Programmer's Manual      PMEMOBJ_MUTEX_ZERO(3)
2
3
4

NAME

6       pmemobj_mutex_zero(),  pmemobj_mutex_lock(), pmemobj_mutex_timedlock(),
7       pmemobj_mutex_trylock(), pmemobj_mutex_unlock(),
8
9       pmemobj_rwlock_zero(),   pmemobj_rwlock_rdlock(),    pmemobj_rwlock_wr‐
10       lock(),   pmemobj_rwlock_timedrdlock(),   pmemobj_rwlock_timedwrlock(),
11       pmemobj_rwlock_tryrdlock(),     pmemobj_rwlock_trywrlock(),      pmemo‐
12       bj_rwlock_unlock(),
13
14       pmemobj_cond_zero(),  pmemobj_cond_broadcast(),  pmemobj_cond_signal(),
15       pmemobj_cond_timedwait(), pmemobj_cond_wait() --  pmemobj  synchroniza‐
16       tion primitives
17

SYNOPSIS

19              #include <libpmemobj.h>
20
21              void pmemobj_mutex_zero(PMEMobjpool *pop, PMEMmutex *mutexp);
22              int pmemobj_mutex_lock(PMEMobjpool *pop, PMEMmutex *mutexp);
23              int pmemobj_mutex_timedlock(PMEMobjpool *pop, PMEMmutex *restrict mutexp,
24                  const struct timespec *restrict abs_timeout);
25              int pmemobj_mutex_trylock(PMEMobjpool *pop, PMEMmutex *mutexp);
26              int pmemobj_mutex_unlock(PMEMobjpool *pop, PMEMmutex *mutexp);
27
28              void pmemobj_rwlock_zero(PMEMobjpool *pop, PMEMrwlock *rwlockp);
29              int pmemobj_rwlock_rdlock(PMEMobjpool *pop, PMEMrwlock *rwlockp);
30              int pmemobj_rwlock_wrlock(PMEMobjpool *pop, PMEMrwlock *rwlockp);
31              int pmemobj_rwlock_timedrdlock(PMEMobjpool *pop, PMEMrwlock *restrict rwlockp,
32                  const struct timespec *restrict abs_timeout);
33              int pmemobj_rwlock_timedwrlock(PMEMobjpool *pop, PMEMrwlock *restrict rwlockp,
34                  const struct timespec *restrict abs_timeout);
35              int pmemobj_rwlock_tryrdlock(PMEMobjpool *pop, PMEMrwlock *rwlockp);
36              int pmemobj_rwlock_trywrlock(PMEMobjpool *pop, PMEMrwlock *rwlockp);
37              int pmemobj_rwlock_unlock(PMEMobjpool *pop, PMEMrwlock *rwlockp);
38
39              void pmemobj_cond_zero(PMEMobjpool *pop, PMEMcond *condp);
40              int pmemobj_cond_broadcast(PMEMobjpool *pop, PMEMcond *condp);
41              int pmemobj_cond_signal(PMEMobjpool *pop, PMEMcond *condp);
42              int pmemobj_cond_timedwait(PMEMobjpool *pop, PMEMcond *restrict condp,
43                  PMEMmutex *restrict mutexp, const struct timespec *restrict abs_timeout);
44              int pmemobj_cond_wait(PMEMobjpool *pop, PMEMcond *restrict condp,
45                  PMEMmutex *restrict mutexp);
46

DESCRIPTION

48       libpmemobj(7)  provides several types of synchronization primitives de‐
49       signed to be used with persistent memory.  The pmem-aware  lock  imple‐
50       mentation  is based on the standard POSIX Threads Library, as described
51       in       pthread_mutex_init(3),       pthread_rwlock_init(3)        and
52       pthread_cond_init(3).   Pmem-aware  locks  provide semantics similar to
53       standard pthread locks, except that they are embedded in  pmem-resident
54       objects  and  are  considered  initialized by zeroing them.  Therefore,
55       locks allocated with pmemobj_zalloc(3) or pmemobj_tx_zalloc(3)  do  not
56       require another initialization step.  For performance reasons, they are
57       also padded up to 64 bytes (cache line size).
58
59       On FreeBSD, since all pthread locks are  dynamically  allocated,  while
60       the  lock  object  is  still padded up to 64 bytes for consistency with
61       Linux, only the pointer to the lock is embedded  in  the  pmem-resident
62       object.   libpmemobj(7) transparently manages freeing of the locks when
63       the pool is closed.
64
65       The fundamental property of pmem-aware locks is their automatic  reini‐
66       tialization  every  time  the  persistent  object store pool is opened.
67       Thus, all the pmem-aware locks may be considered initialized (unlocked)
68       immediately  after the pool is opened, regardless of their state at the
69       time the pool was closed for the last time.
70
71       Pmem-aware mutexes, read/write locks and condition  variables  must  be
72       declared  with the PMEMmutex, PMEMrwlock, or PMEMcond type, respective‐
73       ly.
74
75       The pmemobj_mutex_zero() function explicitly initializes the pmem-aware
76       mutex mutexp by zeroing it.  Initialization is not necessary if the ob‐
77       ject containing the mutex has been allocated using pmemobj_zalloc(3) or
78       pmemobj_tx_zalloc(3).
79
80       The  pmemobj_mutex_lock()  function  locks the pmem-aware mutex mutexp.
81       If the mutex is already locked, the calling thread will block until the
82       mutex  becomes  available.  If this is the first use of the mutex since
83       the opening of the pool pop, the mutex is  automatically  reinitialized
84       and then locked.
85
86       pmemobj_mutex_timedlock()  performs  the  same  action  as  pmemobj_mu‐
87       tex_lock(), but will not wait beyond abs_timeout to obtain the lock be‐
88       fore returning.
89
90       The pmemobj_mutex_trylock() function locks pmem-aware mutex mutexp.  If
91       the mutex is already locked,  pthread_mutex_trylock()  will  not  block
92       waiting  for the mutex, but will return an error.  If this is the first
93       use of the mutex since the opening of the pool pop, the mutex is  auto‐
94       matically reinitialized and then locked.
95
96       The  pmemobj_mutex_unlock()  function unlocks the pmem-aware mutex mut‐
97       exp.  Undefined behavior follows if a thread tries to  unlock  a  mutex
98       that has not been locked by it, or if a thread tries to release a mutex
99       that is already unlocked or has not been initialized.
100
101       The pmemobj_rwlock_zero() function is used to explicitly initialize the
102       pmem-aware  read/write  lock  rwlockp by zeroing it.  Initialization is
103       not necessary if the object containing the lock has been allocated  us‐
104       ing pmemobj_zalloc(3) or pmemobj_tx_zalloc(3).
105
106       The  pmemobj_rwlock_rdlock()  function acquires a read lock on rwlockp,
107       provided that the lock is not presently held for writing and no  writer
108       threads  are presently blocked on the lock.  If the read lock cannot be
109       acquired immediately, the calling thread blocks until  it  can  acquire
110       the  lock.   If  this is the first use of the lock since the opening of
111       the pool pop, the lock is  automatically  reinitialized  and  then  ac‐
112       quired.
113
114       pmemobj_rwlock_timedrdlock()   performs   the  same  action  as  pmemo‐
115       bj_rwlock_rdlock(), but will not wait beyond abs_timeout to obtain  the
116       lock  before  returning.   A  thread  may hold multiple concurrent read
117       locks.  If so, pmemobj_rwlock_unlock() must be  called  once  for  each
118       lock  obtained.  The results of acquiring a read lock while the calling
119       thread holds a write lock are undefined.
120
121       The pmemobj_rwlock_wrlock() function blocks until a write lock  can  be
122       acquired  against read/write lock rwlockp.  If this is the first use of
123       the lock since the opening of the pool pop, the lock  is  automatically
124       reinitialized and then acquired.
125
126       pmemobj_rwlock_timedwrlock()  performs  the  same  action, but will not
127       wait beyond abs_timeout to obtain the lock before returning.
128
129       The pmemobj_rwlock_tryrdlock() function performs  the  same  action  as
130       pmemobj_rwlock_rdlock(), but does not block if the lock cannot be imme‐
131       diately obtained.  The results are undefined if the calling thread  al‐
132       ready holds the lock at the time the call is made.
133
134       The  pmemobj_rwlock_trywrlock()  function  performs  the same action as
135       pmemobj_rwlock_wrlock(), but does not block if the lock cannot be imme‐
136       diately  obtained.  The results are undefined if the calling thread al‐
137       ready holds the lock at the time the call is made.
138
139       The pmemobj_rwlock_unlock() function is used to release the  read/write
140       lock previously obtained by pmemobj_rwlock_rdlock(), pmemobj_rwlock_wr‐
141       lock(), pthread_rwlock_tryrdlock(), or pmemobj_rwlock_trywrlock().
142
143       The pmemobj_cond_zero() function explicitly initializes the  pmem-aware
144       condition  variable  condp by zeroing it.  Initialization is not neces‐
145       sary if the object containing the condition variable has been allocated
146       using pmemobj_zalloc(3) or pmemobj_tx_zalloc(3).
147
148       The  difference  between pmemobj_cond_broadcast() and pmemobj_cond_sig‐
149       nal() is that the former unblocks all threads waiting for the condition
150       variable,  whereas  the  latter  blocks only one waiting thread.  If no
151       threads are waiting on condp, neither function has any effect.  If more
152       than one thread is blocked on a condition variable, the used scheduling
153       policy determines the order in which threads are unblocked.   The  same
154       mutex used for waiting must be held while calling either function.  Al‐
155       though neither function strictly enforces this  requirement,  undefined
156       behavior may follow if the mutex is not held.
157
158       The pmemobj_cond_timedwait() and pmemobj_cond_wait() functions block on
159       a condition variable.  They must be called with mutex mutexp locked  by
160       the  calling  thread,  or  undefined behavior results.  These functions
161       atomically release mutex mutexp and cause the calling thread  to  block
162       on the condition variable condp; atomically here means "atomically with
163       respect to access by another thread to the mutex and then the condition
164       variable".  That is, if another thread is able to acquire the mutex af‐
165       ter the about-to-block thread has released it, then a  subsequent  call
166       to  pmemobj_cond_broadcast()  or  pmemobj_cond_signal()  in that thread
167       will behave as if it were issued after the  about-to-block  thread  has
168       blocked.  Upon successful return, the mutex will be locked and owned by
169       the calling thread.
170

RETURN VALUE

172       The pmemobj_mutex_zero(), pmemobj_rwlock_zero() and pmemobj_cond_zero()
173       functions return no value.
174
175       Other  locking functions return 0 on success.  Otherwise, an error num‐
176       ber will be returned to indicate the error.
177

SEE ALSO

179       pmemobj_tx_zalloc(3),     pmemobj_zalloc(3),      pthread_cond_init(3),
180       pthread_mutex_init(3),  pthread_rwlock_init(3),  libpmem(7),  libpmemo‐
181       bj(7) and <http://pmem.io>
182
183
184
185PMDK - pmemobj API version 2.3    2018-03-13             PMEMOBJ_MUTEX_ZERO(3)
Impressum