PMEMKV  1.5.0-git49.g4c2663e
This is the C++ documentation for PMEMKV.
Classes | Public Types | Public Member Functions | Private Attributes | List of all members
pmem::kv::db Class Reference

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< txtx_begin () noexcept
 Starts a pmemkv transaction. More...
 
result< read_iteratornew_read_iterator ()
 Returns new read iterator in pmem::kv::result. More...
 
result< write_iteratornew_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;
}
db() noexcept
Default constructor with uninitialized database.
Definition: libpmemkv.hpp:1775
Main C++ pmemkv public header.
Main pmemkv namespace.
status
Status returned by most of pmemkv functions.
Definition: libpmemkv.hpp:84
@ NOT_FOUND
record (or config item) not found
obj::string_view string_view
Partial string_view implementation, defined in pmem::obj namespace in libpmemobj-cpp library (see: ht...
Definition: libpmemkv.hpp:47

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

◆ write_iterator

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]keysets the lower bound of counting
[out]cntnumber 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]cntnumber 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]keysets the upper bound of counting
[out]cntnumber 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]key1sets the lower bound of counting
[in]key2sets the upper bound of counting
[out]cntnumber 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]keysets the lower bound of counting
[out]cntnumber 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]keysets the lower bound of counting
[out]cntnumber 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_percentstarting percent of elements to defragment from
[in]amount_percentamount 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]keyrecord'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]keyrecord's key to query for
[in]callbackfunction to be called for returned element
[in]argadditional 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]keyrecord's key to query for
[in]ffunction 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]keyrecord's key to query for
[out]valuestores 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]keysets the lower bound for querying
[in]callbackfunction to be called for each returned element
[in]argadditional 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]keysets the lower bound for querying
[in]ffunction 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]callbackfunction to be called for every element stored in db
[in]argadditional 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]ffunction 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]keysets the upper bound for querying
[in]callbackfunction to be called for each returned element
[in]argadditional 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]keysets the upper bound for querying
[in]ffunction 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]key1sets the lower bound for querying
[in]key2sets the upper bound for querying
[in]callbackfunction to be called for each returned element
[in]argadditional 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]key1sets the lower bound for querying
[in]key2sets the upper bound for querying
[in]ffunction 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]keysets the lower bound for querying
[in]callbackfunction to be called for each returned element
[in]argadditional 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]keysets the lower bound for querying
[in]ffunction 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]keysets the upper bound for querying
[in]callbackfunction to be called for each returned element
[in]argadditional 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]keysets the upper bound for querying
[in]ffunction 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_namename of the engine to work with
[in]cfgpmem::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]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::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]keyrecord'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: