PMEMKV  1.4-git51.gf1d6e36
This is the C++ documentation for PMEMKV.
Public Member Functions | Private Attributes | List of all members
pmem::kv::tx Class Reference

Pmemkv transaction handle. More...

#include <libpmemkv.hpp>

Public Member Functions

 tx (pmemkv_tx *tx_) noexcept
 Constructs C++ tx object from a C pmemkv_tx pointer. More...
 
status put (string_view key, string_view value) noexcept
 Inserts a key-value pair into pmemkv database. More...
 
status remove (string_view key) noexcept
 Removes from database record with given key. More...
 
status commit () noexcept
 Commits the transaction. More...
 
void abort () noexcept
 Aborts the transaction. More...
 

Private Attributes

std::unique_ptr< pmemkv_tx, decltype(&pmemkv_tx_end)> tx_
 

Detailed Description

Pmemkv transaction handle.

This API is EXPERIMENTAL and might change.

The tx class allows grouping put and remove operations into a single atomic action (with respect to persistence and concurrency). Concurrent engines provide transactions with ACID (atomicity, consistency, isolation, durability) properties. Transactions for single threaded engines provide atomicity, consistency and durability. Actions in a transaction are executed in the order in which they were called.

Example usage:

int main(int argc, char *argv[])
{
if (argc < 2) {
std::cerr << "Usage: " << argv[0] << " pool\n";
exit(1);
}
/* See libpmemkv_config(3) for more detailed example of creating a config */
LOG("Creating config");
config cfg;
status s = cfg.put_path(argv[1]);
ASSERT(s == status::OK);
LOG("Opening pmemkv database with 'radix' engine");
db kv;
s = kv.open("radix", std::move(cfg));
ASSERT(s == status::OK);
LOG("Putting new key");
s = kv.put("key1", "value1");
ASSERT(s == status::OK);
auto result_tx = kv.tx_begin();
ASSERT(result_tx.is_ok());
/* This function is guaranteed to not throw if is_ok is true */
auto &tx = result_tx.get_value();
s = tx.remove("key1");
s = tx.put("key2", "value2");
s = tx.put("key3", "value3");
/* Until transaction is committed, changes are not visible */
ASSERT(kv.exists("key1") == status::OK);
ASSERT(kv.exists("key2") == status::NOT_FOUND);
ASSERT(kv.exists("key3") == status::NOT_FOUND);
s = tx.commit();
ASSERT(s == status::OK);
ASSERT(kv.exists("key1") == status::NOT_FOUND);
ASSERT(kv.exists("key2") == status::OK);
ASSERT(kv.exists("key3") == status::OK);
{
/* Alternative method of obtaining tx object. This line can throw if
* tx_begin() fails. */
auto tx = kv.tx_begin().get_value();
s = tx.put("key4", "value4");
s = tx.put("key5", "value5");
}
/* The second tx was not commited, so the changes are not visible. */
ASSERT(kv.exists("key4") == status::NOT_FOUND);
ASSERT(kv.exists("key5") == status::NOT_FOUND);
return 0;
}

Constructor & Destructor Documentation

◆ tx()

pmem::kv::tx::tx ( pmemkv_tx *  tx_)
inlinenoexcept

Constructs C++ tx object from a C pmemkv_tx pointer.

Member Function Documentation

◆ abort()

void pmem::kv::tx::abort ( )
inlinenoexcept

Aborts the transaction.

The tx object can be safely used after abort.

◆ commit()

status pmem::kv::tx::commit ( )
inlinenoexcept

Commits the transaction.

All operations of this transaction are applied as a single power fail-safe atomic action. The tx object can be safely used after commit.

Returns
pmem::kv::status

◆ put()

status pmem::kv::tx::put ( string_view  key,
string_view  value 
)
inlinenoexcept

Inserts a key-value pair into pmemkv database.

The inserted elements are not visible (not even in the same thread) until commit.

Parameters
[in]keyrecord's key; record will be put into database under its name
[in]valuedata to be inserted into this new database record
Returns
pmem::kv::status

◆ remove()

status pmem::kv::tx::remove ( string_view  key)
inlinenoexcept

Removes from database record with given key.

The removed element is still visible until commit. This function will succeed even if there is no element in the database.

Parameters
[in]keyrecord's key to query for, to be removed
Returns
pmem::kv::status

Member Data Documentation

◆ tx_

std::unique_ptr<pmemkv_tx, decltype(&pmemkv_tx_end)> pmem::kv::tx::tx_
private

The documentation for this class was generated from the following file:
pmem::kv::tx::tx
tx(pmemkv_tx *tx_) noexcept
Constructs C++ tx object from a C pmemkv_tx pointer.
Definition: libpmemkv.hpp:1657
pmem::kv::status
status
Status returned by most of pmemkv functions.
Definition: libpmemkv.hpp:84