pmem::obj::transaction Class Reference

C++ transaction handler class. More...

`#include <libpmemobj++/transaction.hpp>`

## Classes

class | automatic
| C++ automatic scope transaction class. More...
class | manual
| C++ manual scope transaction class. More...

## Public Member Functions

| ~transaction () noexcept=delete
| Default destructor. More...

## Static Public Member Functions

static void | abort (int err)
| Manually abort the current transaction. More...
static void | commit ()
| Manually commit a transaction. More...
template<typename... Locks>
static void | exec_tx (pool_base &pool, std::function< void()> tx, Locks &... locks)
| Execute a closure-like transaction and lock `locks`. More...

## Static Private Member Functions

template<typename L , typename... Locks>
static int | add_lock (L &lock, Locks &... locks) noexcept
| Recursively add locks to the active transaction. More...
static int | add_lock () noexcept
| Method ending the recursive algorithm.

## Detailed Description

C++ transaction handler class.

This class is the pmemobj transaction handler. Scoped transactions are handled through two internal classes: manual and automatic.

- manual transactions need to be committed manually, otherwise they will be aborted on object destruction.
- automatic transactions are only available in C++17. They handle transaction commit/abort automatically.

This class also exposes a closure-like transaction API, which is the preferred way of handling transactions.

The typical usage example would be:

#include <libpmemobj++/make_persistent.hpp>
#include <libpmemobj++/mutex.hpp>
#include <libpmemobj++/persistent_ptr.hpp>
#include <libpmemobj++/pext.hpp>
#include <libpmemobj++/pool.hpp>
#include <libpmemobj++/shared_mutex.hpp>
#include <libpmemobj++/transaction.hpp>
using namespace pmem::obj;
void
general_tx_example()
{
// pool root structure
struct root {
mutex pmutex;
shared_mutex shared_pmutex;
p<int> count;
persistent_ptr<root> another_root;
};
// create a pmemobj pool
auto pop = pool<root>::create("poolfile", "layout", PMEMOBJ_MIN_POOL);
auto proot = pop.get_root();
// typical usage schemes
try {
// take locks and start a transaction
transaction::exec_tx(pop,
[&]() {
// atomically allocate objects
proot->another_root =
make_persistent<root>();
// atomically modify objects
proot->count++;
},
proot->pmutex, proot->shared_pmutex);
} catch (pmem::transaction_error &te) {
// a transaction error occurred, transaction got aborted
// reacquire locks if necessary
} catch (...) {
// some other exception got propagated from within the tx
// reacquire locks if necessary
}
}

## Constructor & Destructor Documentation

## ~transaction()

pmem::obj::transaction::~transaction | ( |  | ) |

delete noexcept

Default destructor.

End pmemobj transaction. If the transaction has not been committed before object destruction, an abort will be issued.

## Member Function Documentation

## abort()

static void pmem::obj::transaction::abort | ( | int | err | ) |

inline static

Manually abort the current transaction.

If called within an inner transaction, the outer transactions will also be aborted.

Parameters

  [in] | err | the error to be reported as the reason of the abort.

Exceptions

  transaction_error | if the transaction is in an invalid state.
  manual_tx_abort | this exception is thrown to signify a transaction abort.

## add_lock()

template<typename L , typename... Locks>

static int pmem::obj::transaction::add_lock | ( | L & | lock,
|  | Locks &... | locks
| ) |  |

inline static private noexcept

Recursively add locks to the active transaction.

The locks are taken in the provided order.

Parameters

  [in,out] | lock | the lock to add.
  [in,out] | locks | the rest of the locks to be added to the active transaction.

Returns
  error number if adding any of the locks failed, 0 otherwise.

## commit()

static void pmem::obj::transaction::commit | ( |  | ) |

inline static

Manually commit a transaction.

It is the sole responsibility of the caller, that after the call to transaction::commit() no other operations are done within the transaction.

Exceptions

  transaction_error | on any errors with ending the transaction.

## exec_tx()

template<typename... Locks>

static void pmem::obj::transaction::exec_tx | ( | pool_base & | pool,
|  | std::function< void()> | tx,
|  | Locks &... | locks
| ) |  |

inline static

Execute a closure-like transaction and lock `locks`.

The locks have to be persistent memory resident locks. An attempt to lock the locks will be made. If any of the specified locks is already locked, the method will block. The locks are held until the end of the transaction. The transaction does not have to be committed manually. Manual aborts will end the transaction with an active exception.

If an exception is thrown within the transaction, it gets aborted and the exception is rethrown. Therefore extra care has to be taken with proper error handling.

The locks are held for the entire duration of the transaction. They are released at the end of the scope, so within the `catch` block, they are already unlocked. If the cleanup action requires access to data within a critical section, the locks have to be manually acquired once again.

Parameters

  [in,out] | pool | the pool in which the transaction will take place.
  [in] | tx | an std::function<void ()> which will perform operations within this transaction.
  [in,out] | locks | locks to be taken for the duration of the transaction.

Exceptions

  transaction_error | on any error pertaining the execution of the transaction.
  manual_tx_abort | on manual transaction abort.

The documentation for this class was generated from the following file:

- pmdk-1.4.1/src/include/libpmemobj++/transaction.hpp