pmem::detail::transaction_base< is_flat > Class Template Reference

Common functionality for basic_transaction and flat_transaction. More...

#include <libpmemobj++/transaction.hpp>

Public Types
enum class	stage { work = TX_STAGE_WORK , oncommit = TX_STAGE_ONCOMMIT , onabort = TX_STAGE_ONABORT , finally = TX_STAGE_FINALLY }
	Possible stages of a transaction. More...

Public Member Functions
	~transaction_base () 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...
static int	error () noexcept
static POBJ_CPP_DEPRECATED int	get_last_tx_error () noexcept
template<typename... Locks>
static void	run (obj::pool_base &pool, std::function< void()> tx, Locks &... locks)
	Execute a closure-like transaction and lock locks. More...
template<typename... Locks>
static POBJ_CPP_DEPRECATED void	exec_tx (obj::pool_base &pool, std::function< void()> tx, Locks &... locks)
template<typename T , typename std::enable_if< detail::can_do_snapshot< T >::value, T >::type * = nullptr>
static void	snapshot (const T *addr, size_t num=1)
	Takes a “snapshot” of given elements of type T number (1 by default), located at the given address ptr in the virtual memory space and saves it to the undo log. More...
static void	register_callback (stage stg, std::function< void()> cb)
	Registers callback to be called on specified stage for the transaction. More...

Detailed Description

template<bool is_flat>
class pmem::detail::transaction_base< is_flat >

Common functionality for basic_transaction and flat_transaction.

Member Enumeration Documentation

stage

template<bool is_flat>

enum pmem::detail::transaction_base::stage

strong

Possible stages of a transaction.

For every stage one or more callbacks can be registered (see transaction::register_callback()).

To read more about PMDK's transactions and their stages, see manpage pmemobj_tx_begin(3): https://pmem.io/pmdk/manpages/linux/master/libpmemobj/pmemobj_tx_begin.3

Enumerator
work	transaction in progress
oncommit	successfully committed
onabort	tx_begin failed or transaction aborted
finally	ready for cleanup

Constructor & Destructor Documentation

~transaction_base()

template<bool is_flat>

pmem::detail::transaction_base< is_flat >::~transaction_base ( )

deletenoexcept

Default destructor.

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

Member Function Documentation

abort()

template<bool is_flat>

static void pmem::detail::transaction_base< is_flat >::abort ( int  err )

inlinestatic

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.

commit()

template<bool is_flat>

static void pmem::detail::transaction_base< is_flat >::commit ( )

inlinestatic

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.

register_callback()

template<bool is_flat>

static void pmem::detail::transaction_base< is_flat >::register_callback ( stage  stg, std::function< void()>  cb  )

inlinestatic

Registers callback to be called on specified stage for the transaction.

In case of nested transactions those callbacks are called when the outer most transaction enters a specified stage.

Precondition

this function must be called during a transaction.

Exceptions

transaction_scope_error

when called outside of a transaction scope

The typical usage example would be:

#include <libpmemobj++/make_persistent.hpp>
#include <libpmemobj++/persistent_ptr.hpp>
#include <libpmemobj++/pext.hpp>
#include <libpmemobj++/pool.hpp>
#include <libpmemobj++/transaction.hpp>
 
using namespace pmem::obj;
 
void
tx_callback_example()
{
    /* pool root structure */
    struct root {
        p<int> count;
    };
 
    /* create a pmemobj pool */
    auto pop = pool<root>::create("poolfile", "layout", PMEMOBJ_MIN_POOL);
 
    bool cb_called = false;
    auto internal_tx_function = [&] {
        /* callbacks can be registered even in inner transaction but
         * will be called when outer transaction ends */
        transaction::run(pop, [&] {
            transaction::register_callback(
                transaction::stage::oncommit,
                [&] { cb_called = true; });
        });
 
        /* cb_called is false here if internal_tx_function is called
         * inside another transaction */
    };
 
    try {
        transaction::run(pop, [&] { internal_tx_function(); });
 
        /* cb_called == true if transaction ended successfully */
    } catch (pmem::transaction_error &) {
        /* an internal transaction error occurred, tx aborted
         * reacquire locks if necessary */
    } catch (...) {
        /* some other exception thrown, tx aborted
         * reacquire locks if necessary */
    }
}

run()

template<bool is_flat>

template<typename... Locks>

static void pmem::detail::transaction_base< is_flat >::run ( obj::pool_base &  pool, std::function< void()>  tx, Locks &...  locks  )

inlinestatic

Execute a closure-like transaction and lock locks.

Starts new transaction (nested, if inside another transaction) and executes passed tx function transactionally. Transaction can only start when stage is WORK or NONE.

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.

snapshot()

template<bool is_flat>

template<typename T , typename std::enable_if< detail::can_do_snapshot< T >::value, T >::type * = nullptr>

static void pmem::detail::transaction_base< is_flat >::snapshot ( const T *  addr, size_t  num = 1  )

inlinestatic

Takes a “snapshot” of given elements of type T number (1 by default), located at the given address ptr in the virtual memory space and saves it to the undo log.

The application is then free to directly modify the object in that memory range. In case of a failure or abort, all the changes within this range will be rolled back. The supplied block of memory has to be within the pool registered in the transaction. This function must be called during transaction. This overload only participates in overload resolution of function template if T is either a trivially copyable type or some PMDK provided type.

Parameters

[in]	addr	pointer to the first object to be snapshotted.
[in]	num	number of elements to be snapshotted.

Precondition

this function must be called during transaction.

Exceptions

transaction_error

when snapshotting failed or if function wasn't called during transaction.

---

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

• libpmemobj++/transaction.hpp