Main pmemkv class, it provides functions to operate on data in database. More...

#include <libpmemkv.hpp>

Classes
class	iterator
	Iterator provides methods to iterate over records in db. More...

Public Types
using	read_iterator = iterator< true >

using	write_iterator = iterator< false >

Public Member Functions
	db () noexcept
	Default constructor with uninitialized database. More...

status	open (const std::string &engine_name, config &&cfg=config{}) noexcept
	Opens the pmemkv database with specified config. More...

void	close () noexcept
	Closes pmemkv database. More...

status	count_all (std::size_t &cnt) noexcept
	It returns number of currently stored elements in pmem::kv::db. More...

status	count_above (string_view key, std::size_t &cnt) noexcept
	It returns number of currently stored elements in pmem::kv::db, whose keys are greater than the given key. More...

status	count_equal_above (string_view key, std::size_t &cnt) noexcept
	It returns number of currently stored elements in pmem::kv::db, whose keys are greater than or equal to the given key. More...

status	count_equal_below (string_view key, std::size_t &cnt) noexcept
	It returns number of currently stored elements in pmem::kv::db, whose keys are lower than or equal to the given key. More...

status	count_below (string_view key, std::size_t &cnt) noexcept
	It returns number of currently stored elements in pmem::kv::db, whose keys are less than the given key. More...

status	count_between (string_view key1, string_view key2, std::size_t &cnt) noexcept
	It returns number of currently stored elements in pmem::kv::db, whose keys are greater than the key1 and less than the key2. More...

status	get_all (get_kv_callback callback, void arg) noexcept
	Executes (C-like) callback function for every record stored in pmem::kv::db. More...

status	get_all (std::function< get_kv_function > f) noexcept
	Executes function for every record stored in pmem::kv::db. More...

status	get_above (string_view key, get_kv_callback callback, void arg) noexcept
	Executes (C-like) callback function for every record stored in pmem::kv::db, whose keys are greater than the given key. More...

status	get_above (string_view key, std::function< get_kv_function > f) noexcept
	Executes function for every record stored in pmem::kv::db, whose keys are greater than the given key. More...

status	get_equal_above (string_view key, get_kv_callback callback, void arg) noexcept
	Executes (C-like) callback function for every record stored in pmem::kv::db, whose keys are greater than or equal to the given key. More...

status	get_equal_above (string_view key, std::function< get_kv_function > f) noexcept
	Executes function for every record stored in pmem::kv::db, whose keys are greater than or equal to the given key. More...

status	get_equal_below (string_view key, get_kv_callback callback, void arg) noexcept
	Executes (C-like) callback function for every record stored in pmem::kv::db, whose keys are lower than or equal to the given key. More...

status	get_equal_below (string_view key, std::function< get_kv_function > f) noexcept
	Executes function for every record stored in pmem::kv::db, whose keys are lower than or equal to the given key. More...

status	get_below (string_view key, get_kv_callback callback, void arg) noexcept
	Executes (C-like) callback function for every record stored in pmem::kv::db, whose keys are lower than the given key. More...

status	get_below (string_view key, std::function< get_kv_function > f) noexcept
	Executes function for every record stored in pmem::kv::db, whose keys are less than the given key. More...

status	get_between (string_view key1, string_view key2, get_kv_callback callback, void arg) noexcept
	Executes (C-like) callback function for every record stored in pmem::kv::db, whose keys are greater than the key1 and less than the key2. More...

status	get_between (string_view key1, string_view key2, std::function< get_kv_function > f) noexcept
	Executes function for every record stored in pmem::kv::db, whose keys are greater than the key1 and less than the key2. More...

status	exists (string_view key) noexcept
	Checks existence of record with given key. More...

status	get (string_view key, get_v_callback callback, void arg) noexcept
	Executes (C-like) callback function for record with given key. More...

status	get (string_view key, std::function< get_v_function > f) noexcept
	Executes function for record with given key. More...

status	get (string_view key, std::string *value) noexcept
	Gets value copy of record with given key. 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	defrag (double start_percent=0, double amount_percent=100)
	Defragments approximately 'amount_percent' percent of elements in the database starting from 'start_percent' percent of elements. More...

result< tx >	tx_begin () noexcept
	Starts a pmemkv transaction. More...

result< read_iterator >	new_read_iterator ()
	Returns new read iterator in pmem::kv::result. More...

result< write_iterator >	new_write_iterator ()
	Returns new write iterator in pmem::kv::result. More...

std::string	errormsg ()
	Returns a human readable string describing the last error. More...

Private Attributes
std::unique_ptr< pmemkv_db, decltype(&pmemkv_close)>	db_

Detailed Description

Main pmemkv class, it provides functions to operate on data in database.

Database class for creating, opening and closing pmemkv's data file. It provides functions to write, read & remove data, count elements stored and check for existence of an element based on its key.

Note: It does not explicitly provide upper_bound/lower_bound functions. If you want to obtain an element(s) above or below the selected key, you can use pmem::kv::get_above() or pmem::kv::get_below(). See descriptions of these functions for details.

Example of basic usage:

#include <cassert>
#include <cstdlib>
#include <iostream>
#include <libpmemkv.hpp>
#include <sstream>
 
#define ASSERT(expr)                                                                     \
    do {                                                                             \
        if (!(expr))                                                             \
            std::cout << pmemkv_errormsg() << std::endl;                     \
        assert(expr);                                                            \
    } while (0)
#define LOG(msg) std::cout << msg << std::endl
 
using namespace pmem::kv;
 
const uint64_t SIZE = 1024UL * 1024UL * 1024UL;
 
int main(int argc, char *argv[])
{
    if (argc < 2) {
        std::cerr << "Usage: " << argv[0] << " file\n";
        exit(1);
    }
 
    /* See libpmemkv_config(3) for more detailed example of config creation */
    LOG("Creating config");
    config cfg;
 
    status s = cfg.put_path(argv[1]);
    ASSERT(s == status::OK);
    s = cfg.put_size(SIZE);
    ASSERT(s == status::OK);
    s = cfg.put_create_if_missing(true);
    ASSERT(s == status::OK);
 
    /* Alternatively create_or_error_if_exists flag can be set, to fail if file exists
     * For differences between the two flags, see e.g. libpmemkv(7) manpage. */
    /* s = cfg.put_create_or_error_if_exists(true); */
 
    LOG("Opening pmemkv database with 'cmap' engine");
    db kv;
    s = kv.open("cmap", std::move(cfg));
    ASSERT(s == status::OK);
 
    LOG("Putting new key");
    s = kv.put("key1", "value1");
    ASSERT(s == status::OK);
 
    size_t cnt;
    s = kv.count_all(cnt);
    ASSERT(s == status::OK && cnt == 1);
 
    LOG("Reading key back");
    std::string value;
    s = kv.get("key1", &value);
    ASSERT(s == status::OK && value == "value1");
 
    LOG("Iterating existing keys");
    s = kv.put("key2", "value2");
    ASSERT(s == status::OK);
    s = kv.put("key3", "value3");
    ASSERT(s == status::OK);
    kv.get_all([](string_view k, string_view v) {
        LOG("  visited: " << k.data());
        return 0;
    });
 
    LOG("Defragmenting the database");
    s = kv.defrag(0, 100);
    ASSERT(s == status::OK);
 
    LOG("Removing existing key");
    s = kv.remove("key1");
    ASSERT(s == status::OK);
    s = kv.exists("key1");
    ASSERT(s == status::NOT_FOUND);
 
    /* Examples of using pmem:kv:status with std::ostream and operator<<,
     * it's useful for debugging. */
    /* Print status */
    std::cout << s << std::endl;
 
    /* Write status to ostringstream */
    std::ostringstream oss;
    oss << s;
    assert(oss.str() == "NOT_FOUND (2)");
 
    /* 'kv' is closed automatically here, when scope ends.
     * Alternatively kv can be created on heap (see pmemkv_open_cpp example),
     * or using unique_ptr (see pmemkv_iterator_cpp example).
     */
    LOG("Closing database");
    return 0;
}

Example on how to open and re-open an existing database:

/*
 * This example expects a path to already created database pool.
 *
 * Normally you want to re-use a pool, which was created
 * by a previous run of pmemkv application. However, for this example
 * you may want to create pool by hand - use one of the following commands.
 *
 * For regular pools use:
 * pmempool create -l -s 1G "pmemkv" obj path_to_a_pool
 *
 * For poolsets use:
 * pmempool create -l "pmemkv" obj ../examples/example.poolset
 *
 * Word of explanation: "pmemkv" is a pool layout used by cmap engine.
 * For other engines, this may vary, hence it's not advised to create pool manually.
 */
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;
 
    /* Instead of expecting already created database pool, we could simply
     * set 'create_if_missing' flag in the config, to provide a pool if needed. */
    status s = cfg.put_path(argv[1]);
    ASSERT(s == status::OK);
 
    LOG("Opening pmemkv database with 'cmap' engine");
    db *kv = new db();
    ASSERT(kv != nullptr);
    s = kv->open("cmap", std::move(cfg));
    ASSERT(s == status::OK);
 
    LOG("Putting new key");
    s = kv->put("key1", "value1");
    ASSERT(s == status::OK);
 
    size_t cnt;
    s = kv->count_all(cnt);
    ASSERT(s == status::OK && cnt == 1);
 
    LOG("Reading key back");
    std::string value;
    s = kv->get("key1", &value);
    ASSERT(s == status::OK && value == "value1");
 
    LOG("Iterating existing keys");
    s = kv->put("key2", "value2");
    ASSERT(s == status::OK);
    s = kv->put("key3", "value3");
    ASSERT(s == status::OK);
    kv->get_all([](string_view k, string_view v) {
        LOG("  visited: " << k.data());
        return 0;
    });
 
    LOG("Closing database");
    delete kv;
    kv = nullptr;
 
    /* After the db is closed, we can easily reopen it. We have to use
     * the same pool file and the same engine as during the database creation.
     * We could do this with no problem in a different application. */
 
    LOG("Creating config (the first one is not valid anymore)");
    config cfg2;
 
    s = cfg2.put_path(argv[1]);
    ASSERT(s == status::OK);
 
    LOG("Re-opening pmemkv database with 'cmap' engine");
    kv = new db();
    ASSERT(kv != nullptr);
    s = kv->open("cmap", std::move(cfg2));
    ASSERT(s == status::OK);
 
    s = kv->exists("key1");
    ASSERT(s == status::OK);
 
    LOG("Removing existing key");
    s = kv->remove("key1");
    ASSERT(s == status::OK);
    s = kv->exists("key1");
    ASSERT(s == status::NOT_FOUND);
 
    LOG("Closing database");
    delete kv;
 
    return 0;
}

Example for pmemkv's database supporting multiple engines:

#include <cassert>
#include <cstdlib>
#include <iostream>
#include <libpmemkv.hpp>
#include <libpmemobj++/container/string.hpp>
#include <libpmemobj++/container/vector.hpp>
#include <libpmemobj++/make_persistent.hpp>
#include <libpmemobj++/persistent_ptr.hpp>
#include <libpmemobj++/transaction.hpp>
 
#undef LOG
#define ASSERT(expr)                                                                     \
    do {                                                                             \
        if (!(expr))                                                             \
            std::cout << pmemkv_errormsg() << std::endl;                     \
        assert(expr);                                                            \
    } while (0)
#define LOG(msg) std::cout << msg << std::endl
 
using namespace pmem::kv;
using pmemoid_vector = pmem::obj::vector<PMEMoid>;
 
const uint64_t SIZE = 1024UL * 1024UL * 1024UL;
 
struct Root {
    pmem::obj::persistent_ptr<pmemoid_vector> oids;
    pmem::obj::persistent_ptr<pmem::obj::string> str;
};
 
int main(int argc, char *argv[])
{
    if (argc < 2) {
        std::cerr << "Usage: " << argv[0] << " file\n";
        exit(1);
    }
 
    const char *path = argv[1];
 
    pmem::obj::pool<Root> pop;
 
    try {
        pop = pmem::obj::pool<Root>::create(path, "pmemkv", SIZE, S_IRWXU);
 
        pmem::obj::transaction::run(pop, [&] {
            pop.root()->oids = pmem::obj::make_persistent<pmemoid_vector>();
            pop.root()->str = pmem::obj::make_persistent<pmem::obj::string>();
 
            pop.root()->oids->emplace_back(OID_NULL);
            pop.root()->oids->emplace_back(OID_NULL);
        });
 
        LOG("Creating configs");
        config cfg_1;
        config cfg_2;
 
        status ret = cfg_1.put_oid(&(pop.root()->oids->at(0)));
        ASSERT(ret == status::OK);
        ret = cfg_2.put_oid(&(pop.root()->oids->at(1)));
        ASSERT(ret == status::OK);
 
        LOG("Starting first cmap engine");
        db *kv_1 = new db();
        ASSERT(kv_1 != nullptr);
        status s = kv_1->open("cmap", std::move(cfg_1));
        ASSERT(s == status::OK);
 
        *(pop.root()->str) = "some string";
 
        LOG("Starting second cmap engine");
        db *kv_2 = new db();
        ASSERT(kv_2 != nullptr);
        s = kv_2->open("cmap", std::move(cfg_2));
        ASSERT(s == status::OK);
 
        LOG("Putting new key into first cmap");
        s = kv_1->put("key_1", "value_1");
        ASSERT(s == status::OK);
 
        LOG("Putting new key into second cmap");
        s = kv_2->put("key_2", "value_2");
        ASSERT(s == status::OK);
 
        LOG("Reading key back from first cmap");
        std::string value;
        s = kv_1->get("key_1", &value);
        ASSERT(s == status::OK && value == "value_1");
 
        LOG("Reading key back from second cmap");
        value.clear();
        s = kv_2->get("key_2", &value);
        ASSERT(s == status::OK && value == "value_2");
 
        LOG("Defragmenting the first cmap");
        s = kv_1->defrag(0, 100);
        ASSERT(s == status::OK);
 
        LOG("Defragmenting the second cmap");
        s = kv_2->defrag(0, 100);
        ASSERT(s == status::OK);
 
        LOG("Stopping first cmap engine");
        delete kv_1;
 
        LOG("Stopping second cmap engine");
        delete kv_2;
 
    } catch (std::exception &e) {
        std::cerr << "Exception occurred: " << e.what() << std::endl;
    }
 
    try {
        pop.close();
    } catch (const std::logic_error &e) {
        std::cerr << "Exception occurred: " << e.what() << std::endl;
    }
 
    return 0;
}

Member Typedef Documentation

◆ read_iterator

using pmem::kv::db::read_iterator = iterator<true>

◆ write_iterator

using pmem::kv::db::write_iterator = iterator<false>

Constructor & Destructor Documentation

◆ db()

pmem::kv::db::db ( )

inlinenoexcept

Default constructor with uninitialized database.

Member Function Documentation

◆ close()

void pmem::kv::db::close ( )

inlinenoexcept

Closes pmemkv database.

◆ count_above()

status pmem::kv::db::count_above	(	string_view	key,
		std::size_t &	cnt
	)

inlinenoexcept

It returns number of currently stored elements in pmem::kv::db, whose keys are greater than the given key.

Keys are sorted in order specified by a comparator.

Parameters

[in]	key	sets the lower bound of counting
[out]	cnt	number of records in pmem::kv::db matching query

Returns: pmem::kv::status

◆ count_all()

status pmem::kv::db::count_all ( std::size_t & cnt )

inlinenoexcept

It returns number of currently stored elements in pmem::kv::db.

Parameters

[out] cnt number of records stored in pmem::kv::db.

Returns: pmem::kv::status

◆ count_below()

status pmem::kv::db::count_below	(	string_view	key,
		std::size_t &	cnt
	)

inlinenoexcept

It returns number of currently stored elements in pmem::kv::db, whose keys are less than the given key.

Keys are sorted in order specified by a comparator.

Parameters

[in]	key	sets the upper bound of counting
[out]	cnt	number of records in pmem::kv::db matching query

Returns: pmem::kv::status

◆ count_between()

status pmem::kv::db::count_between	(	string_view	key1,
		string_view	key2,
		std::size_t &	cnt
	)

inlinenoexcept

It returns number of currently stored elements in pmem::kv::db, whose keys are greater than the key1 and less than the key2.

Keys are sorted in order specified by a comparator.

Parameters

[in]	key1	sets the lower bound of counting
[in]	key2	sets the upper bound of counting
[out]	cnt	number of records in pmem::kv::db matching query

Returns: pmem::kv::status

◆ count_equal_above()

status pmem::kv::db::count_equal_above	(	string_view	key,
		std::size_t &	cnt
	)

inlinenoexcept

It returns number of currently stored elements in pmem::kv::db, whose keys are greater than or equal to the given key.

Keys are sorted in order specified by a comparator.

Parameters

[in]	key	sets the lower bound of counting
[out]	cnt	number of records in pmem::kv::db matching query

Returns: pmem::kv::status

◆ count_equal_below()

status pmem::kv::db::count_equal_below	(	string_view	key,
		std::size_t &	cnt
	)

inlinenoexcept

It returns number of currently stored elements in pmem::kv::db, whose keys are lower than or equal to the given key.

Keys are sorted in order specified by a comparator.

Parameters

[in]	key	sets the lower bound of counting
[out]	cnt	number of records in pmem::kv::db matching query

Returns: pmem::kv::status

◆ defrag()

status pmem::kv::db::defrag	(	double	start_percent = `0`,
		double	amount_percent = `100`
	)

inline

Defragments approximately 'amount_percent' percent of elements in the database starting from 'start_percent' percent of elements.

Parameters

[in]	start_percent	starting percent of elements to defragment from
[in]	amount_percent	amount percent of elements to defragment

Returns: pmem::kv::status

◆ errormsg()

std::string pmem::kv::db::errormsg ( )

inline

Returns a human readable string describing the last error.

Even if this is a method from the db class, it can return the last error from some other class.

Returns: std::string with a description of the last error

◆ exists()

status pmem::kv::db::exists ( string_view key )

inlinenoexcept

Checks existence of record with given key.

If record is present pmem::kv::status::OK is returned, otherwise pmem::kv::status::NOT_FOUND is returned. Other possible return values are described in pmem::kv::status.

Parameters

[in] key record's key to query for in database

Returns: pmem::kv::status

◆ get() [1/3]

status pmem::kv::db::get	(	string_view	key,
		get_v_callback *	callback,
		void *	arg
	)

inlinenoexcept

Executes (C-like) callback function for record with given key.

If record is present and no error occurred, the function returns pmem::kv::status::OK. If record does not exist pmem::kv::status::NOT_FOUND is returned. Other possible return values are described in pmem::kv::status. Callback is called with the following parameters: pointer to a value, size of the value and arg specified by the user. This function is guaranteed to be implemented by all engines.

Parameters

[in]	key	record's key to query for
[in]	callback	function to be called for returned element
[in]	arg	additional arguments to be passed to callback

Returns: pmem::kv::status

◆ get() [2/3]

status pmem::kv::db::get	(	string_view	key,
		std::function< get_v_function >	f
	)

inlinenoexcept

Executes function for record with given key.

If record is present and no error occurred the function returns pmem::kv::status::OK. If record does not exist pmem::kv::status::NOT_FOUND is returned.

Parameters

[in]	key	record's key to query for
[in]	f	function called for returned element, it is called with only one param - value (key is known)

Returns: pmem::kv::status

◆ get() [3/3]

status pmem::kv::db::get	(	string_view	key,
		std::string *	value
	)

inlinenoexcept

Gets value copy of record with given key.

In absence of any errors, pmem::kv::status::OK is returned. This function is guaranteed to be implemented by all engines.

Parameters

[in]	key	record's key to query for
[out]	value	stores returned copy of the data

Returns: pmem::kv::status

◆ get_above() [1/2]

status pmem::kv::db::get_above	(	string_view	key,
		get_kv_callback *	callback,
		void *	arg
	)

inlinenoexcept

Executes (C-like) callback function for every record stored in pmem::kv::db, whose keys are greater than the given key.

Arguments passed to the callback function are: pointer to a key, size of the key, pointer to a value, size of the value and arg specified by the user. Callback can stop iteration by returning non-zero value. In that case get_above() returns pmem::kv::status::STOPPED_BY_CB. Returning 0 continues iteration.

Keys are sorted in order specified by a comparator.

Parameters

[in]	key	sets the lower bound for querying
[in]	callback	function to be called for each returned element
[in]	arg	additional arguments to be passed to callback

Returns: pmem::kv::status

◆ get_above() [2/2]

status pmem::kv::db::get_above	(	string_view	key,
		std::function< get_kv_function >	f
	)

inlinenoexcept

Executes function for every record stored in pmem::kv::db, whose keys are greater than the given key.

Callback can stop iteration by returning non-zero value. In that case get_above() returns pmem::kv::status::STOPPED_BY_CB. Returning 0 continues iteration.

Keys are sorted in order specified by a comparator.

Parameters

[in]	key	sets the lower bound for querying
[in]	f	function called for each returned element, it is called with params: key and value

Returns: pmem::kv::status

◆ get_all() [1/2]

status pmem::kv::db::get_all	(	get_kv_callback *	callback,
		void *	arg
	)

inlinenoexcept

Executes (C-like) callback function for every record stored in pmem::kv::db.

Arguments passed to the callback function are: pointer to a key, size of the key, pointer to a value, size of the value and arg specified by the user. Callback can stop iteration by returning non-zero value. In that case get_all() returns pmem::kv::status::STOPPED_BY_CB. Returning 0 continues iteration.

Parameters

[in]	callback	function to be called for every element stored in db
[in]	arg	additional arguments to be passed to callback

Returns: pmem::kv::status

◆ get_all() [2/2]

status pmem::kv::db::get_all ( std::function< get_kv_function > f )

inlinenoexcept

Executes function for every record stored in pmem::kv::db.

Callback can stop iteration by returning non-zero value. In that case get_all() returns pmem::kv::status::STOPPED_BY_CB. Returning 0 continues iteration.

Parameters

[in] f function called for each returned element, it is called with params: key and value

Returns: pmem::kv::status

◆ get_below() [1/2]

status pmem::kv::db::get_below	(	string_view	key,
		get_kv_callback *	callback,
		void *	arg
	)

inlinenoexcept

Executes (C-like) callback function for every record stored in pmem::kv::db, whose keys are lower than the given key.

Arguments passed to the callback function are: pointer to a key, size of the key, pointer to a value, size of the value and arg specified by the user. Callback can stop iteration by returning non-zero value. In that case get_below() returns pmem::kv::status::STOPPED_BY_CB. Returning 0 continues iteration.

Keys are sorted in order specified by a comparator.

Parameters

[in]	key	sets the upper bound for querying
[in]	callback	function to be called for each returned element
[in]	arg	additional arguments to be passed to callback

Returns: pmem::kv::status

◆ get_below() [2/2]

status pmem::kv::db::get_below	(	string_view	key,
		std::function< get_kv_function >	f
	)

inlinenoexcept

Executes function for every record stored in pmem::kv::db, whose keys are less than the given key.

Callback can stop iteration by returning non-zero value. In that case get_below() returns pmem::kv::status::STOPPED_BY_CB. Returning 0 continues iteration.

Keys are sorted in order specified by a comparator.

Parameters

[in]	key	sets the upper bound for querying
[in]	f	function called for each returned element, it is called with params: key and value

Returns: pmem::kv::status

◆ get_between() [1/2]

status pmem::kv::db::get_between	(	string_view	key1,
		string_view	key2,
		get_kv_callback *	callback,
		void *	arg
	)

inlinenoexcept

Executes (C-like) callback function for every record stored in pmem::kv::db, whose keys are greater than the key1 and less than the key2.

Arguments passed to the callback function are: pointer to a key, size of the key, pointer to a value, size of the value and arg specified by the user. Callback can stop iteration by returning non-zero value. In that case get_between() returns pmem::kv::status::STOPPED_BY_CB. Returning 0 continues iteration.

Keys are sorted in order specified by a comparator.

Parameters

[in]	key1	sets the lower bound for querying
[in]	key2	sets the upper bound for querying
[in]	callback	function to be called for each returned element
[in]	arg	additional arguments to be passed to callback

Returns: pmem::kv::status

◆ get_between() [2/2]

status pmem::kv::db::get_between	(	string_view	key1,
		string_view	key2,
		std::function< get_kv_function >	f
	)

inlinenoexcept

Executes function for every record stored in pmem::kv::db, whose keys are greater than the key1 and less than the key2.

Callback can stop iteration by returning non-zero value. In that case get_between() returns pmem::kv::status::STOPPED_BY_CB. Returning 0 continues iteration.

Keys are sorted in order specified by a comparator.

Parameters

[in]	key1	sets the lower bound for querying
[in]	key2	sets the upper bound for querying
[in]	f	function called for each returned element, it is called with params: key and value

Returns: pmem::kv::status

◆ get_equal_above() [1/2]

status pmem::kv::db::get_equal_above	(	string_view	key,
		get_kv_callback *	callback,
		void *	arg
	)

inlinenoexcept

Executes (C-like) callback function for every record stored in pmem::kv::db, whose keys are greater than or equal to the given key.

Arguments passed to the callback function are: pointer to a key, size of the key, pointer to a value, size of the value and arg specified by the user. Callback can stop iteration by returning non-zero value. In that case get_equal_above() returns pmem::kv::status::STOPPED_BY_CB. Returning 0 continues iteration.

Keys are sorted in order specified by a comparator.

Parameters

[in]	key	sets the lower bound for querying
[in]	callback	function to be called for each returned element
[in]	arg	additional arguments to be passed to callback

Returns: pmem::kv::status

◆ get_equal_above() [2/2]

status pmem::kv::db::get_equal_above	(	string_view	key,
		std::function< get_kv_function >	f
	)

inlinenoexcept

Executes function for every record stored in pmem::kv::db, whose keys are greater than or equal to the given key.

Callback can stop iteration by returning non-zero value. In that case get_equal_above()* returns pmem::kv::status::STOPPED_BY_CB. Returning 0 continues iteration.

Keys are sorted in order specified by a comparator.

Parameters

[in]	key	sets the lower bound for querying
[in]	f	function called for each returned element, it is called with params: key and value

Returns: pmem::kv::status

◆ get_equal_below() [1/2]

status pmem::kv::db::get_equal_below	(	string_view	key,
		get_kv_callback *	callback,
		void *	arg
	)

inlinenoexcept

Executes (C-like) callback function for every record stored in pmem::kv::db, whose keys are lower than or equal to the given key.

Arguments passed to the callback function are: pointer to a key, size of the key, pointer to a value, size of the value and arg specified by the user. Callback can stop iteration by returning non-zero value. In that case get_equal_below() returns pmem::kv::status::STOPPED_BY_CB. Returning 0 continues iteration.

Keys are sorted in order specified by a comparator.

Parameters

[in]	key	sets the upper bound for querying
[in]	callback	function to be called for each returned element
[in]	arg	additional arguments to be passed to callback

Returns: pmem::kv::status

◆ get_equal_below() [2/2]

status pmem::kv::db::get_equal_below	(	string_view	key,
		std::function< get_kv_function >	f
	)

inlinenoexcept

Executes function for every record stored in pmem::kv::db, whose keys are lower than or equal to the given key.

Callback can stop iteration by returning non-zero value. In that case get_equal_below()* returns pmem::kv::status::STOPPED_BY_CB. Returning 0 continues iteration.

Keys are sorted in order specified by a comparator.

Parameters

[in]	key	sets the upper bound for querying
[in]	f	function called for each returned element, it is called with params: key and value

Returns: pmem::kv::status

◆ new_read_iterator()

result< db::read_iterator > pmem::kv::db::new_read_iterator ( )

inline

Returns new read iterator in pmem::kv::result.

Returns: pmem::kv::result<db::read_iterator>

◆ new_write_iterator()

result< db::write_iterator > pmem::kv::db::new_write_iterator ( )

inline

Returns new write iterator in pmem::kv::result.

Returns: pmem::kv::result<db::write_iterator>

◆ open()

status pmem::kv::db::open	(	const std::string &	engine_name,
		config &&	cfg = `config{}`
	)

inlinenoexcept

Opens the pmemkv database with specified config.

Parameters

[in]	engine_name	name of the engine to work with
[in]	cfg	pmem::kv::config with parameters specified for the engine

Returns: pmem::kv::status

◆ put()

status pmem::kv::db::put	(	string_view	key,
		string_view	value
	)

inlinenoexcept

Inserts a key-value pair into pmemkv database.

This function is guaranteed to be implemented by all engines.

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::db::remove ( string_view key )

inlinenoexcept

Removes from database record with given key.

This function is guaranteed to be implemented by all engines.

Parameters

[in] key record's key to query for, to be removed

Returns: pmem::kv::status

◆ tx_begin()

result< tx > pmem::kv::db::tx_begin ( )

inlinenoexcept

Starts a pmemkv transaction.

Returns: transaction handle

Member Data Documentation

◆ db_

std::unique_ptr<pmemkv_db, decltype(&pmemkv_close)> pmem::kv::db::db_

private

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

/tmp/pmemkv-Ns4/src/libpmemkv.hpp

Classes

Public Types

Public Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ read_iterator

◆ write_iterator

Constructor & Destructor Documentation

◆ db()

Member Function Documentation

◆ close()

◆ count_above()

◆ count_all()

◆ count_below()

◆ count_between()

◆ count_equal_above()

◆ count_equal_below()

◆ defrag()

◆ errormsg()

◆ exists()

◆ get() [1/3]

◆ get() [2/3]

◆ get() [3/3]

◆ get_above() [1/2]

◆ get_above() [2/2]

◆ get_all() [1/2]

◆ get_all() [2/2]

◆ get_below() [1/2]

◆ get_below() [2/2]

◆ get_between() [1/2]

◆ get_between() [2/2]

◆ get_equal_above() [1/2]

◆ get_equal_above() [2/2]

◆ get_equal_below() [1/2]

◆ get_equal_below() [2/2]

◆ new_read_iterator()

◆ new_write_iterator()

◆ open()

◆ put()

◆ remove()

◆ tx_begin()

Member Data Documentation

◆ db_