1PMEMOBJ_MUTEX_ZERO(3) PMDK Programmer's Manual PMEMOBJ_MUTEX_ZERO(3)
2
6 pmemobj_mutex_zero(), pmemobj_mutex_lock(), pmemobj_mutex_timedlock(),
7 pmemobj_mutex_trylock(), pmemobj_mutex_unlock(),
8 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 pmemobj_cond_zero(), pmemobj_cond_broadcast(), pmemobj_cond_signal(),
15 pmemobj_cond_timedwait(), pmemobj_cond_wait() - pmemobj synchronization
16 primitives
17
19 #include <libpmemobj.h>
20 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 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 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
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 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 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 Pmem-aware mutexes, read/write locks and condition variables must be
72 declared with the PMEMmutex, PMEMrwlock, or PMEMcond type, respective‐
73 ly.
74 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 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 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 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 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 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 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 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 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 pmemobj_rwlock_timedwrlock() performs the same action, but will not
127 wait beyond abs_timeout to obtain the lock before returning.
128 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 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 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 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 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 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
172 The pmemobj_mutex_zero(), pmemobj_rwlock_zero() and pmemobj_cond_zero()
173 functions return no value.
174 Other locking functions return 0 on success. Otherwise, an error num‐
176 ber will be returned to indicate the error.
177
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 <https://pmem.io>
182PMDK - pmemobj API version 2.3 2022-05-24 PMEMOBJ_MUTEX_ZERO(3)