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]	key	record's key; record will be put into database under its name
[in]	value	data 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]

key

record'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:

• /pmemkv/src/libpmemkv.hpp