PMEMKV  1.3.1-git1.g6468f74
This is the C++ documentation for PMEMKV.
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>

Public Member Functions

 db () noexcept
 Default constructor with uninitialized database. More...
 
 ~db ()
 Default destructor. More...
 
 db (const db &other)=delete
 
 db (db &&other) noexcept
 Move constructor. More...
 
dboperator= (const db &other)=delete
 
dboperator= (db &&other) noexcept
 Move assignment operator. More...
 
status open (const std::string &engine_name) noexcept
 Opens the pmemkv database without any configuration parameters. More...
 
status open (const std::string &engine_name, config &&cfg) 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...
 
std::string errormsg ()
 Returns a human readable string describing the last error. More...
 

Private Attributes

pmemkv_db * _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.

Constructor & Destructor Documentation

◆ db() [1/3]

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

Default constructor with uninitialized database.

◆ ~db()

pmem::kv::db::~db ( )
inline

Default destructor.

Closes pmemkv database.

◆ db() [2/3]

pmem::kv::db::db ( const db other)
delete

◆ db() [3/3]

pmem::kv::db::db ( db &&  other)
inlinenoexcept

Move constructor.

Initializes database with another database. Ownership is being transferred to a class that move constructor was called on.

Parameters
[in]otheranother database, to be moved from

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

◆ open() [1/2]

status pmem::kv::db::open ( const std::string &  engine_name)
inlinenoexcept

Opens the pmemkv database without any configuration parameters.

Parameters
[in]engine_namename of the engine to work with
Returns
pmem::kv::status

◆ open() [2/2]

status pmem::kv::db::open ( const std::string &  engine_name,
config &&  cfg 
)
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

◆ operator=() [1/2]

db& pmem::kv::db::operator= ( const db other)
delete

◆ operator=() [2/2]

db & pmem::kv::db::operator= ( db &&  other)
inlinenoexcept

Move assignment operator.

Deletes previous database and replaces it with another database. Ownership is being transferred to a class that assign operator was called on.

Parameters
[in]otheranother database, to be assigned from

◆ 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

Member Data Documentation

◆ _db

pmemkv_db* pmem::kv::db::_db
private

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