104
• TX_PARAM_RWLOCK is followed by one value, a pmem-resident
PMEMrwlock.
• TX_PARAM_CB is followed by two values: a callback function of type
pmemobj_tx_callback and a void pointer.
Using TX_PARAM_MUTEX or TX_PARAM_RWLOCK causes the specified lock to be acquired
at the beginning of the transaction. TX_PARAM_RWLOCK acquires the lock for writing.
It is guaranteed that pmemobj_tx_begin() will acquire all locks prior to successful
completion, and they will be held by the current thread until the outermost transaction
is finished. Locks are taken in order from left to right. To avoid deadlocks, you are
responsible for proper lock ordering.
TX_PARAM_CB registers the specified callback function to be executed at each
transaction stage. For TX_STAGE_WORK, the callback is executed prior to commit. For all
other stages, the callback is executed as the first operation after a stage change. It will
also be called after each transaction.
Optional Flags
Many of the functions discussed for the atomic, reserve/publish, and transactional APIs
have a variant with a "flags" argument that accepts these values:
• POBJ_XALLOC_ZERO zeroes the object allocated.
• POBJ_XALLOC_NO_FLUSH suppresses automatic flushing. It is expected
that you flush the data in some way; otherwise, it may not be durable
in case of an unexpected power loss.
Persisting Data Summary
The atomic, reserve/publish, and transactional APIs have different strengths:
• Atomic allocations are the simplest and fastest, but their use is
limited to allocating and initializing wholly new blocks.
• The reserve/publish API can be as fast as atomic allocations when
all operations involve either allocating or deallocating whole objects
or modifying scalar values. However, being able to read the data you
have just written may be desirable.
Chapter 7 libpmemobj: a Native traNsaCtioNal objeCt store
• TX_PARAM_RWLOCK is followed by one value, a pmem-resident
PMEMrwlock.
• TX_PARAM_CB is followed by two values: a callback function of type
pmemobj_tx_callback and a void pointer.
Using TX_PARAM_MUTEX or TX_PARAM_RWLOCK causes the specified lock to be acquired
at the beginning of the transaction. TX_PARAM_RWLOCK acquires the lock for writing.
It is guaranteed that pmemobj_tx_begin() will acquire all locks prior to successful
completion, and they will be held by the current thread until the outermost transaction
is finished. Locks are taken in order from left to right. To avoid deadlocks, you are
responsible for proper lock ordering.
TX_PARAM_CB registers the specified callback function to be executed at each
transaction stage. For TX_STAGE_WORK, the callback is executed prior to commit. For all
other stages, the callback is executed as the first operation after a stage change. It will
also be called after each transaction.
Optional Flags
Many of the functions discussed for the atomic, reserve/publish, and transactional APIs
have a variant with a "flags" argument that accepts these values:
• POBJ_XALLOC_ZERO zeroes the object allocated.
• POBJ_XALLOC_NO_FLUSH suppresses automatic flushing. It is expected
that you flush the data in some way; otherwise, it may not be durable
in case of an unexpected power loss.
Persisting Data Summary
The atomic, reserve/publish, and transactional APIs have different strengths:
• Atomic allocations are the simplest and fastest, but their use is
limited to allocating and initializing wholly new blocks.
• The reserve/publish API can be as fast as atomic allocations when
all operations involve either allocating or deallocating whole objects
or modifying scalar values. However, being able to read the data you
have just written may be desirable.
Chapter 7 libpmemobj: a Native traNsaCtioNal objeCt store