Provided by: libpmemobj-dev_1.12.1-2_amd64 
NAME
pmemobj_tx_stage(),
pmemobj_tx_begin(), pmemobj_tx_lock(), pmemobj_tx_xlock(), pmemobj_tx_abort(),
pmemobj_tx_commit(), pmemobj_tx_end(), pmemobj_tx_errno(), pmemobj_tx_process(),
TX_BEGIN_PARAM(), TX_BEGIN_CB(), TX_BEGIN(), TX_ONABORT, TX_ONCOMMIT, TX_FINALLY, TX_END,
pmemobj_tx_log_append_buffer(), pmemobj_tx_xlog_append_buffer(),
pmemobj_tx_log_auto_alloc(), pmemobj_tx_log_snapshots_max_size(),
pmemobj_tx_log_intents_max_size(),
pmemobj_tx_set_user_data(), pmemobj_tx_get_user_data(),
pmemobj_tx_set_failure_behavior(), pmemobj_tx_get_failure_behavior() - transactional
object manipulation
SYNOPSIS
#include <libpmemobj.h>
enum pobj_tx_stage pmemobj_tx_stage(void);
int pmemobj_tx_begin(PMEMobjpool *pop, jmp_buf *env, enum pobj_tx_param, ...);
int pmemobj_tx_lock(enum tx_lock lock_type, void *lockp);
int pmemobj_tx_xlock(enum tx_lock lock_type, void *lockp, uint64_t flags);
void pmemobj_tx_abort(int errnum);
void pmemobj_tx_commit(void);
int pmemobj_tx_end(void);
int pmemobj_tx_errno(void);
void pmemobj_tx_process(void);
TX_BEGIN_PARAM(PMEMobjpool *pop, ...)
TX_BEGIN_CB(PMEMobjpool *pop, cb, arg, ...)
TX_BEGIN(PMEMobjpool *pop)
TX_ONABORT
TX_ONCOMMIT
TX_FINALLY
TX_END
int pmemobj_tx_log_append_buffer(enum pobj_log_type type, void *addr, size_t size);
int pmemobj_tx_xlog_append_buffer(enum pobj_log_type type, void *addr, size_t size, uint64_t flags);
int pmemobj_tx_log_auto_alloc(enum pobj_log_type type, int on_off);
size_t pmemobj_tx_log_snapshots_max_size(size_t *sizes, size_t nsizes);
size_t pmemobj_tx_log_intents_max_size(size_t nintents);
void pmemobj_tx_set_user_data(void *data);
void *pmemobj_tx_get_user_data(void);
void pmemobj_tx_set_failure_behavior(enum pobj_tx_failure_behavior behavior);
enum pobj_tx_failure_behavior pmemobj_tx_get_failure_behavior(void);
DESCRIPTION
The non-transactional functions and macros described in pmemobj_alloc(3),
pmemobj_list_insert(3) and POBJ_LIST_HEAD(3) only guarantee the atomicity of a single
operation on an object. In case of more complex changes involving multiple operations on
an object, or allocation and modification of multiple objects, data consistency and
fail-safety may be provided only by using atomic transactions.
A transaction is defined as series of operations on persistent memory objects that either
all occur, or nothing occurs. In particular, if the execution of a transaction is
interrupted by a power failure or a system crash, it is guaranteed that after system
restart, all the changes made as a part of the uncompleted transaction will be rolled
back, restoring the consistent state of the memory pool from the moment when the
transaction was started.
Note that transactions do not provide atomicity with respect to other threads. All the
modifications performed within the transactions are immediately visible to other threads.
Therefore it is the responsibility of the application to implement a proper thread
synchronization mechanism.
Each thread may have only one transaction open at a time, but that transaction may be
nested. Nested transactions are flattened. Committing the nested transaction does not
commit the outer transaction; however, errors in the nested transaction are propagated up
to the outermost level, resulting in the interruption of the entire transaction.
Each transaction is visible only for the thread that started it. No other threads can add
operations, commit or abort the transaction initiated by another thread. Multiple threads
may have transactions open on a given memory pool at the same time.
Please see the CAVEATS section below for known limitations of the transactional API.
The pmemobj_tx_stage() function returns the current transaction stage for a thread.
Stages are changed only by the pmemobj_tx_*() functions. Transaction stages are defined
as follows:
• TX_STAGE_NONE - no open transaction in this thread
• TX_STAGE_WORK - transaction in progress
• TX_STAGE_ONCOMMIT - successfully committed
• TX_STAGE_ONABORT - starting the transaction failed or transaction aborted
• TX_STAGE_FINALLY - ready for clean up
The pmemobj_tx_begin() function starts a new transaction in the current thread. If called
within an open transaction, it starts a nested transaction. The caller may use the env
argument to provide a pointer to a calling environment to be restored in case of
transaction abort. This information must be provided by the caller using the setjmp(3)
macro.
A new transaction may be started only if the current stage is TX_STAGE_NONE or
TX_STAGE_WORK. If successful, the transaction stage changes to TX_STAGE_WORK. Otherwise,
the stage is changed to TX_STAGE_ONABORT.
Optionally, a list of parameters for the transaction may be provided. Each parameter
consists of a type followed by a type-specific number of values. Currently there are 4
types:
• TX_PARAM_NONE, used as a termination marker. No following value.
• TX_PARAM_MUTEX, followed by one value, a pmem-resident PMEMmutex
• TX_PARAM_RWLOCK, followed by one value, a pmem-resident PMEMrwlock
• TX_PARAM_CB, 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, the user is 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; in this case the stage parameter will be set to
TX_STAGE_NONE. pmemobj_tx_callback must be compatible with:
void func(PMEMobjpool *pop, enum pobj_tx_stage stage, void *arg)
pop is a pool identifier used in pmemobj_tx_begin(), stage is a current transaction stage
and arg is the second parameter of TX_PARAM_CB. Without considering transaction nesting,
this mechanism can be considered an alternative method for executing code between stages
(instead of TX_ONCOMMIT, TX_ONABORT, etc). However, there are 2 significant differences
when nested transactions are used:
• The registered function is executed only in the outermost transaction, even if
registered in an inner transaction.
• There can be only one callback in the entire transaction, that is, the callback cannot
be changed in an inner transaction.
Note that TX_PARAM_CB does not replace the TX_ONCOMMIT, TX_ONABORT, etc. macros. They
can be used together: the callback will be executed before a TX_ONCOMMIT, TX_ONABORT, etc.
section.
TX_PARAM_CB can be used when the code dealing with transaction stage changes is shared
between multiple users or when it must be executed only in the outer transaction. For
example it can be very useful when the application must synchronize persistent and
transient state.
The pmemobj_tx_lock() function acquires the lock lockp of type lock_type and adds it to
the current transaction. lock_type may be TX_LOCK_MUTEX or TX_LOCK_RWLOCK; lockp must be
of type PMEMmutex or PMEMrwlock, respectively. If lock_type is TX_LOCK_RWLOCK the lock is
acquired for writing. If the lock is not successfully acquired, the function returns an
error number. This function must be called during TX_STAGE_WORK.
The pmemobj_tx_xlock() function behaves exactly the same as pmemobj_tx_lock() when flags
equals POBJ_XLOCK_NO_ABORT. When flags equals 0 and if the lock is not successfully
acquired,the transaction is aborted. flags is a bitmask of the following values:
• POBJ_XLOCK_NO_ABORT - if the function does not end successfully, do not abort the
transaction.
pmemobj_tx_abort() aborts the current transaction and causes a transition to
TX_STAGE_ONABORT. If errnum is equal to 0, the transaction error code is set to
ECANCELED; otherwise, it is set to errnum. This function must be called during
TX_STAGE_WORK.
The pmemobj_tx_commit() function commits the current open transaction and causes a
transition to TX_STAGE_ONCOMMIT. If called in the context of the outermost transaction,
all the changes may be considered as durably written upon successful completion. This
function must be called during TX_STAGE_WORK.
The pmemobj_tx_end() function performs a cleanup of the current transaction. If called in
the context of the outermost transaction, it releases all the locks acquired by
pmemobj_tx_begin() for outer and nested transactions. If called in the context of a
nested transaction, it returns to the context of the outer transaction in TX_STAGE_WORK,
without releasing any locks. The pmemobj_tx_end() function can be called during
TX_STAGE_NONE if transitioned to this stage using pmemobj_tx_process(). If not already in
TX_STAGE_NONE, it causes the transition to TX_STAGE_NONE. pmemobj_tx_end must always be
called for each pmemobj_tx_begin(), even if starting the transaction failed. This
function must not be called during TX_STAGE_WORK.
The pmemobj_tx_errno() function returns the error code of the last transaction.
The pmemobj_tx_process() function performs the actions associated with the current stage
of the transaction, and makes the transition to the next stage. It must be called in a
transaction. The current stage must always be obtained by a call to pmemobj_tx_stage().
pmemobj_tx_process() performs the following transitions in the transaction stage flow:
• TX_STAGE_WORK -> TX_STAGE_ONCOMMIT
• TX_STAGE_ONABORT -> TX_STAGE_FINALLY
• TX_STAGE_ONCOMMIT -> TX_STAGE_FINALLY
• TX_STAGE_FINALLY -> TX_STAGE_NONE
• TX_STAGE_NONE -> TX_STAGE_NONE
pmemobj_tx_process() must not be called after calling pmemobj_tx_end() for the outermost
transaction.
In addition to the above API, libpmemobj(7) offers a more intuitive method of building
transactions using the set of macros described below. When using these macros, the
complete transaction flow looks like this:
TX_BEGIN(Pop) {
/* the actual transaction code goes here... */
} TX_ONCOMMIT {
/*
* optional - executed only if the above block
* successfully completes
*/
} TX_ONABORT {
/*
* optional - executed only if starting the transaction fails,
* or if transaction is aborted by an error or a call to
* pmemobj_tx_abort()
*/
} TX_FINALLY {
/*
* optional - if exists, it is executed after
* TX_ONCOMMIT or TX_ONABORT block
*/
} TX_END /* mandatory */
TX_BEGIN_PARAM(PMEMobjpool *pop, ...)
TX_BEGIN_CB(PMEMobjpool *pop, cb, arg, ...)
TX_BEGIN(PMEMobjpool *pop)
The TX_BEGIN_PARAM(), TX_BEGIN_CB() and TX_BEGIN() macros start a new transaction in the
same way as pmemobj_tx_begin(), except that instead of the environment buffer provided by
a caller, they set up the local jmp_buf buffer and use it to catch the transaction abort.
The TX_BEGIN() macro starts a transaction without any options. TX_BEGIN_PARAM may be used
when there is a need to acquire locks prior to starting a transaction (such as for a
multi-threaded program) or set up a transaction stage callback. TX_BEGIN_CB is just a
wrapper around TX_BEGIN_PARAM that validates the callback signature. (For compatibility
there is also a TX_BEGIN_LOCK macro, which is an alias for TX_BEGIN_PARAM). Each of these
macros must be followed by a block of code with all the operations that are to be
performed atomically.
The TX_ONABORT macro starts a block of code that will be executed only if starting the
transaction fails due to an error in pmemobj_tx_begin(), or if the transaction is aborted.
This block is optional, but in practice it should not be omitted. If it is desirable to
crash the application when a transaction aborts and there is no TX_ONABORT section, the
application can define the POBJ_TX_CRASH_ON_NO_ONABORT macro before inclusion of
<libpmemobj.h>. This provides a default TX_ONABORT section which just calls abort(3).
The TX_ONCOMMIT macro starts a block of code that will be executed only if the transaction
is successfully committed, which means that the execution of code in the TX_BEGIN() block
has not been interrupted by an error or by a call to pmemobj_tx_abort(). This block is
optional.
The TX_FINALLY macro starts a block of code that will be executed regardless of whether
the transaction is committed or aborted. This block is optional.
The TX_END macro cleans up and closes the transaction started by the TX_BEGIN() /
TX_BEGIN_PARAM() / TX_BEGIN_CB() macros. It is mandatory to terminate each transaction
with this macro. If the transaction was aborted, errno is set appropriately.
TRANSACTION LOG TUNING
From libpmemobj implementation perspective there are two types of operations in a
transaction:
• snapshots, where action must be persisted immediately,
• intents, where action can be persisted at the transaction commit phase
pmemobj_tx_add_range(3) and all its variants belong to the snapshots group.
pmemobj_tx_alloc(3) (with its variants), pmemobj_tx_free(3), pmemobj_tx_realloc(3) (with
its variants) and pmemobj_tx_publish(3) belong to the intents group. Even though
pmemobj_tx_alloc() allocates memory immediately, it modifies only the runtime state and
postpones persistent memory modifications to the commit phase. pmemobj_tx_free(3) cannot
free the object immediately, because of possible transaction rollback, so it postpones
both the action and persistent memory modifications to the commit phase.
pmemobj_tx_realloc(3) is just a combination of those two. pmemobj_tx_publish(3) postpones
reservations and deferred frees to the commit phase.
Those two types of operations (snapshots and intents) require that libpmemobj builds a
persistent log of operations. Intent log (also known as a “redo log”) is applied on
commit and snapshot log (also known as an “undo log”) is applied on abort.
When libpmemobj transaction starts, it's not possible to predict how much persistent
memory space will be needed for those logs. This means that libpmemobj must internally
allocate this space whenever it's needed. This has two downsides:
• when transaction snapshots a lot of memory or does a lot of allocations, libpmemobj may
need to do many internal allocations, which must be freed when transaction ends, adding
time overhead when big transactions are frequent,
• transactions can start to fail due to not enough space for logs - this can be especially
problematic for transactions that want to deallocate objects, as those might also fail
To solve both of these problems libpmemobj exposes the following functions:
• pmemobj_tx_log_append_buffer(),
• pmemobj_tx_xlog_append_buffer(),
• pmemobj_tx_log_auto_alloc()
pmemobj_tx_log_append_buffer() appends a given range of memory [addr, addr + size) to the
log type of the current transaction. type can be one of the two values (with meanings
described above):
• TX_LOG_TYPE_SNAPSHOT,
• TX_LOG_TYPE_INTENT
The range of memory must belong to the same pool the transaction is on and must not be
used by more than one thread at the same time. The latter condition can be verified with
tx.debug.verify_user_buffers ctl (see pmemobj_ctl_get(3)).
The pmemobj_tx_xlog_append_buffer() function behaves exactly the same as
pmemobj_tx_log_append_buffer() when flags equals zero. flags is a bitmask of the
following values:
• POBJ_XLOG_APPEND_BUFFER_NO_ABORT - if the function does not end successfully, do not
abort the transaction.
pmemobj_tx_log_snapshots_max_size calculates the maximum size of a buffer which will be
able to hold nsizes snapshots, each of size sizes[i]. Application should not expect this
function to return the same value between restarts. In future versions of libpmemobj this
function can return smaller (because of better accuracy or space optimizations) or higher
(because of higher alignment required for better performance) value. This function is
independent of transaction stage and can be called both inside and outside of transaction.
If the returned value S is greater than PMEMOBJ_MAX_ALLOC_SIZE, the buffer should be split
into N chunks of size PMEMOBJ_MAX_ALLOC_SIZE, where N is equal to (S /
PMEMOBJ_MAX_ALLOC_SIZE) (rounded down) and the last chunk of size (S - (N *
PMEMOBJ_MAX_ALLOC_SIZE)).
pmemobj_tx_log_intents_max_size calculates the maximum size of a buffer which will be able
to hold nintents intents. Just like with pmemobj_tx_log_snapshots_max_size, application
should not expect this function to return the same value between restarts, for the same
reasons. This function is independent of transaction stage and can be called both inside
and outside of transaction.
pmemobj_tx_log_auto_alloc() disables (on_off set to 0) or enables (on_off set to 1)
automatic allocation of internal logs of given type. It can be used to verify that the
buffer set with pmemobj_tx_log_append_buffer() is big enough to hold the log, without
reaching out-of-space scenario.
The pmemobj_tx_set_user_data() function associates custom volatile state, represented by
pointer data, with the current transaction. This state can later be retrieved using
pmemobj_tx_get_user_data() function. If pmemobj_tx_set_user_data() was not called for a
current transaction, pmemobj_tx_get_user_data() will return NULL. These functions must be
called during TX_STAGE_WORK or TX_STAGE_ONABORT or TX_STAGE_ONCOMMIT or TX_STAGE_FINALLY.
pmemobj_tx_set_failure_behavior() specifies what should happen in case of an error within
the transaction. It only affects functions which take a NO_ABORT flag. If
pmemobj_tx_set_failure_behavior() is called with POBJ_TX_FAILURE_RETURN a NO_ABORT flag is
implicitly passed to all functions which accept this flag. If called with
POBJ_TX_FAILURE_ABORT then all functions abort the transaction (unless NO_ABORT flag is
passed explicitly). This setting is inherited by inner transactions. It does not affect
any of the outer transactions. Aborting on failure is the default behavior.
pmemobj_tx_get_failure_behavior() returns failure behavior for the current transaction.
Both pmemobj_tx_set_failure_behavior() and pmemobj_tx_get_failure_behavior() must be
called during TX_STAGE_WORK.
RETURN VALUE
The pmemobj_tx_stage() function returns the stage of the current transaction stage for a
thread.
On success, pmemobj_tx_begin() returns 0. Otherwise, an error number is returned.
The pmemobj_tx_begin() and pmemobj_tx_lock() functions return zero if lockp is
successfully added to the transaction. Otherwise, an error number is returned.
The pmemobj_tx_xlock() function return zero if lockp is successfully added to the
transaction. Otherwise, the error number is returned, errno is set and when flags do not
contain POBJ_XLOCK_NO_ABORT, the transaction is aborted.
The pmemobj_tx_abort() and pmemobj_tx_commit() functions return no value.
The pmemobj_tx_end() function returns 0 if the transaction was successful. Otherwise it
returns the error code set by pmemobj_tx_abort(). Note that pmemobj_tx_abort() can be
called internally by the library.
The pmemobj_tx_errno() function returns the error code of the last transaction.
The pmemobj_tx_process() function returns no value.
On success, pmemobj_tx_log_append_buffer() returns 0. Otherwise, the stage is changed to
TX_STAGE_ONABORT, errno is set appropriately and transaction is aborted.
On success, pmemobj_tx_xlog_append_buffer() returns 0. Otherwise, the error number is
returned, errno is set and when flags do not contain POBJ_XLOG_NO_ABORT, the transaction
is aborted.
On success, pmemobj_tx_log_auto_alloc() returns 0. Otherwise, the transaction is aborted
and an error number is returned.
On success, pmemobj_tx_log_snapshots_max_size() returns size of the buffer. On failure it
returns SIZE_MAX and sets errno appropriately.
On success, pmemobj_tx_log_intents_max_size() returns size of the buffer. On failure it
returns SIZE_MAX and sets errno appropriately.
CAVEATS
Transaction flow control is governed by the setjmp(3) and longjmp(3) macros, and they are
used in both the macro and function flavors of the API. The transaction will longjmp on
transaction abort. This has one major drawback, which is described in the ISO C standard
subsection 7.13.2.1. It says that the values of objects of automatic storage duration
that are local to the function containing the setjmp invocation that do not have
volatile-qualified type and have been changed between the setjmp invocation and longjmp
call are indeterminate.
The following example illustrates the issue described above.
int *bad_example_1 = (int *)0xBAADF00D;
int *bad_example_2 = (int *)0xBAADF00D;
int *bad_example_3 = (int *)0xBAADF00D;
int * volatile good_example = (int *)0xBAADF00D;
TX_BEGIN(pop) {
bad_example_1 = malloc(sizeof(int));
bad_example_2 = malloc(sizeof(int));
bad_example_3 = malloc(sizeof(int));
good_example = malloc(sizeof(int));
/* manual or library abort called here */
pmemobj_tx_abort(EINVAL);
} TX_ONCOMMIT {
/*
* This section is longjmp-safe
*/
} TX_ONABORT {
/*
* This section is not longjmp-safe
*/
free(good_example); /* OK */
free(bad_example_1); /* undefined behavior */
} TX_FINALLY {
/*
* This section is not longjmp-safe on transaction abort only
*/
free(bad_example_2); /* undefined behavior */
} TX_END
free(bad_example_3); /* undefined behavior */
Objects which are not volatile-qualified, are of automatic storage duration and have been
changed between the invocations of setjmp(3) and longjmp(3) (that also means within the
work section of the transaction after TX_BEGIN()) should not be used after a transaction
abort, or should be used with utmost care. This also includes code after the TX_END
macro.
libpmemobj(7) is not cancellation-safe. The pool will never be corrupted because of a
canceled thread, but other threads may stall waiting on locks taken by that thread. If
the application wants to use pthread_cancel(3), it must disable cancellation before
calling any libpmemobj(7) APIs (see pthread_setcancelstate(3) with
PTHREAD_CANCEL_DISABLE), and re-enable it afterwards. Deferring cancellation
(pthread_setcanceltype(3) with PTHREAD_CANCEL_DEFERRED) is not safe enough, because
libpmemobj(7) internally may call functions that are specified as cancellation points in
POSIX.
libpmemobj(7) relies on the library destructor being called from the main thread. For
this reason, all functions that might trigger destruction (e.g. dlclose(3)) should be
called in the main thread. Otherwise some of the resources associated with that thread
might not be cleaned up properly.
SEE ALSO
dlclose(3), longjmp(3), pmemobj_tx_add_range(3), pmemobj_tx_alloc(3),
pthread_setcancelstate(3), pthread_setcanceltype(3), setjmp(3), libpmemobj(7) and
<https://pmem.io>