Provided by: libpmemobj-dev_1.6.1-1ubuntu1_amd64 bug

NAME

       pmemobj_tx_stage(),

       pmemobj_tx_begin(),     pmemobj_tx_lock(),     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 -
       transactional object manipulation

SYNOPSIS

              #include <libpmemobj.h>

              enum 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);
              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

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.

       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.

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_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.

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
       <http://pmem.io>