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

#include </pmemkv/doc_update/pmemkv/src/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...

db &	operator= (const db &other)=delete

db &	operator= (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] other another 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]	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

◆ 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_name name 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_name	name of the engine to work with
[in]	cfg	pmem::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] other another 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]	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

Member Data Documentation

◆ _db

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

private

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

/pmemkv/doc_update/pmemkv/src/libpmemkv.hpp

Public Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ db() [1/3]

◆ ~db()

◆ db() [2/3]

◆ db() [3/3]

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]

◆ open() [1/2]

◆ open() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ put()

◆ remove()

Member Data Documentation

◆ _db