PMDK C++ bindings  1.9
This is the C++ bindings documentation for PMDK's libpmemobj.
Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Private Member Functions | List of all members
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...
 
struct  tx_data
 This data is stored along with the pmemobj transaction data using pmemobj_tx_set_data(). More...
 

Public Types

enum  stage
 Possible stages of a transaction, for every stage one or more callbacks can be registered.
 

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 run (pool_base &pool, std::function< void()> tx, Locks &... locks)
 Execute a closure-like transaction and lock locks. More...
 
template<typename T , typename std::enable_if< LIBPMEMOBJ_CPP_IS_TRIVIALLY_COPYABLE(T), 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...
 

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.
 
static void c_callback (PMEMobjpool *pop, enum pobj_tx_stage obj_stage, void *arg)
 C-style function which is passed as callback to pmemobj_begin. More...
 
static tx_dataget_tx_data ()
 Gets tx user data from pmemobj or creates it if this is a first call to this function inside a transaction.
 

Detailed Description

C++ transaction handler class.

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

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

This API should NOT be mixed with C transactions API. One issue is that C++ callbacks registered using transaction::register_callback() would not be called if C++ transaction is created inside C transaction. The same is true if user calls pmemobj_tx_set_user_data() inside a C++ transaction.

The typical usage example would be:

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.root();
// typical usage schemes
try {
// take locks and start a transaction
pop,
[&]() {
// atomically allocate objects
proot->another_root = make_persistent<root>();
// atomically modify objects
proot->count++;
},
proot->pmutex, proot->shared_pmutex);
// 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 ( )
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()

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

Manually abort the current transaction.

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

Parameters
[in]errthe error to be reported as the reason of the abort.
Exceptions
transaction_errorif the transaction is in an invalid state.
manual_tx_abortthis 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 
)
inlinestaticprivatenoexcept

Recursively add locks to the active transaction.

The locks are taken in the provided order.

Parameters
[in,out]lockthe lock to add.
[in,out]locksthe rest of the locks to be added to the active transaction.
Returns
error number if adding any of the locks failed, 0 otherwise.

◆ c_callback()

static void pmem::obj::transaction::c_callback ( PMEMobjpool *  pop,
enum pobj_tx_stage  obj_stage,
void *  arg 
)
inlinestaticprivate

C-style function which is passed as callback to pmemobj_begin.

It executes previously registered callbacks for all stages.

◆ commit()

static void pmem::obj::transaction::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_erroron any errors with ending the transaction.

◆ register_callback()

static void pmem::obj::transaction::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_errorwhen called outside of a transaction scope

The typical usage example would be:

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::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
// an internal transaction error occurred, tx aborted
// reacquire locks if necessary
} catch (...) {
// some other exception thrown, tx aborted
// reacquire locks if necessary
}
}

◆ run()

template<typename... Locks>
static void pmem::obj::transaction::run ( pool_base pool,
std::function< void()>  tx,
Locks &...  locks 
)
inlinestatic

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]poolthe pool in which the transaction will take place.
[in]txan std::function<void ()> which will perform operations within this transaction.
[in,out]lockslocks to be taken for the duration of the transaction.
Exceptions
transaction_erroron any error pertaining the execution of the transaction.
manual_tx_aborton manual transaction abort.

◆ snapshot()

template<typename T , typename std::enable_if< LIBPMEMOBJ_CPP_IS_TRIVIALLY_COPYABLE(T), T >::type * = nullptr>
static void pmem::obj::transaction::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 satisfies requirements of LIBPMEMOBJ_CPP_IS_TRIVIALLY_COPYABLE macro.

Parameters
[in]addrpointer to the first object to be snapshotted.
[in]numnumber of elements to be snapshotted.
Precondition
this function must be called during transaction.
Exceptions
transaction_errorwhen snapshotting failed or if function wasn't called during transaction.

The documentation for this class was generated from the following file:
pmem::obj::transaction::register_callback
static void register_callback(stage stg, std::function< void()> cb)
Registers callback to be called on specified stage for the transaction.
Definition: transaction.hpp:557
pmem::obj::mutex
Persistent memory resident mutex implementation.
Definition: mutex.hpp:60
pmem::obj::pool::create
static pool< T > create(const std::string &path, const std::string &layout, std::size_t size=PMEMOBJ_MIN_POOL, mode_t mode=DEFAULT_MODE)
Creates a new transactional object store pool.
Definition: pool.hpp:701
pmem::transaction_error
Custom transaction error class.
Definition: pexceptions.hpp:92
pmem::obj::p
Resides on pmem class.
Definition: p.hpp:64
pmem::obj::pool::root
persistent_ptr< T > root()
Retrieves pool's root object.
Definition: pool.hpp:651
pool.hpp
C++ pmemobj pool.
make_persistent.hpp
Persistent_ptr transactional allocation functions for objects.
pmem::obj::transaction::run
static void run(pool_base &pool, std::function< void()> tx, Locks &... locks)
Execute a closure-like transaction and lock locks.
Definition: transaction.hpp:422
pmem::obj
Main libpmemobj namespace.
Definition: allocation_flag.hpp:47
transaction.hpp
C++ pmemobj transactions.
pmem::obj::persistent_ptr
Persistent pointer class.
Definition: persistent_ptr.hpp:212
shared_mutex.hpp
Pmem-resident shared mutex.
pext.hpp
Convenience extensions for the resides on pmem property template.
persistent_ptr.hpp
Persistent smart pointer.
pmem::obj::shared_mutex
Persistent memory resident shared_mutex implementation.
Definition: shared_mutex.hpp:59
mutex.hpp
Pmem-resident mutex.