pmem::kv::config Class Reference

Holds configuration parameters for engines. More...

#include <libpmemkv.hpp>

Public Member Functions
	config () noexcept
	Default constructor with uninitialized config. More...
	config (pmemkv_config *cfg) noexcept
	Creates config from pointer to pmemkv_config. More...
template<typename T >
status	put_data (const std::string &key, const T *value, const std::size_t number=1) noexcept
	Puts binary data pointed by value, of type T, with count of elements to a config. More...
template<typename T >
status	put_object (const std::string &key, T *value, void(*deleter)(void *)) noexcept
	Puts object pointed by value, of type T, with given destructor to a config. More...
template<typename T , typename D >
status	put_object (const std::string &key, std::unique_ptr< T, D > object) noexcept
	Puts unique_ptr (to an object) to a config. More...
status	put_uint64 (const std::string &key, std::uint64_t value) noexcept
	Puts std::uint64_t value to a config. More...
status	put_int64 (const std::string &key, std::int64_t value) noexcept
	Puts std::int64_t value to a config. More...
status	put_string (const std::string &key, const std::string &value) noexcept
	Puts string value to a config. More...
status	put_size (std::uint64_t size) noexcept
	Puts size to a config, it's required when creating new database pool. More...
status	put_path (const std::string &path) noexcept
	Puts path (of a database pool) to a config, to open or create. More...
status	put_force_create (bool value) noexcept force_create_deprecated
	It's an alias for config::put_create_or_error_if_exists, kept for compatibility. More...
status	put_create_or_error_if_exists (bool value) noexcept
	Puts create_or_error_if_exists parameter to a config. More...
status	put_create_if_missing (bool value) noexcept
	Puts create_if_missing parameter to a config. More...
status	put_oid (PMEMoid *oid) noexcept
	Puts PMEMoid object to a config. More...
template<typename Comparator >
status	put_comparator (Comparator &&comparator)
	Puts comparator object to a config. More...
template<typename T >
status	get_data (const std::string &key, T *&value, std::size_t &number) const noexcept
	Gets object from a config item with key name and copies it into T object value. More...
template<typename T >
status	get_object (const std::string &key, T *&value) const noexcept
	Gets binary data from a config item with key name and assigns pointer to T object value. More...
status	get_uint64 (const std::string &key, std::uint64_t &value) const noexcept
	Gets std::uint64_t value from a config item with key name. More...
status	get_int64 (const std::string &key, std::int64_t &value) const noexcept
	Gets std::int64_t value from a config item with key name. More...
status	get_string (const std::string &key, std::string &value) const noexcept
	Gets string value from a config item with key name. More...
pmemkv_config *	release () noexcept
	Similarly to std::unique_ptr::release it passes the ownership of underlying pmemkv_config variable and sets it to nullptr. More...

Private Member Functions
int	init () noexcept
	Initialization function for config. More...

Private Attributes
std::unique_ptr< pmemkv_config, decltype(&pmemkv_config_delete)>	config_

Detailed Description

Holds configuration parameters for engines.

It stores mappings of keys (strings) to values. A value can be: uint64_t, int64_t, string, binary data, pointer to an object (with accompanying deleter function).

It also delivers methods to store and read configuration items provided by a user. Once the configuration object is set (with all required parameters),pmemkv_open it can be passed to db::open() method.

List of options which are required by pmemkv database is specific to an engine. Every engine has documented all supported config parameters (please see libpmemkv(7) for details).

Constructor & Destructor Documentation

config() [1/2]

pmem::kv::config::config ( )

inlinenoexcept

Default constructor with uninitialized config.

config() [2/2]

pmem::kv::config::config ( pmemkv_config *  cfg )

inlineexplicitnoexcept

Creates config from pointer to pmemkv_config.

Ownership is transferred to config class.

Member Function Documentation

get_data()

template<typename T >

status pmem::kv::config::get_data ( const std::string &  key, T *&  value, std::size_t &  count  ) const

inlinenoexcept

Gets object from a config item with key name and copies it into T object value.

Parameters

[in]	key	The string representing config item's name.
[out]	value	The pointer to data.
[out]	count	The count of elements stored under reference.

Returns

pmem::kv::status

get_int64()

status pmem::kv::config::get_int64 ( const std::string &  key, std::int64_t &  value  ) const

inlinenoexcept

Gets std::int64_t value from a config item with key name.

Parameters

[in]	key	The string representing config item's name.
[out]	value	The std::int64_t value.

Returns

pmem::kv::status

get_object()

template<typename T >

status pmem::kv::config::get_object ( const std::string &  key, T *&  value  ) const

inlinenoexcept

Gets binary data from a config item with key name and assigns pointer to T object value.

Parameters

[in]	key	The string representing config item's name.
[out]	value	The pointer to object.

Returns

pmem::kv::status

get_string()

status pmem::kv::config::get_string ( const std::string &  key, std::string &  value  ) const

inlinenoexcept

Gets string value from a config item with key name.

Parameters

[in]	key	The string representing config item's name.
[out]	value	The string value.

Returns

pmem::kv::status

get_uint64()

status pmem::kv::config::get_uint64 ( const std::string &  key, std::uint64_t &  value  ) const

inlinenoexcept

Gets std::uint64_t value from a config item with key name.

Parameters

[in]	key	The string representing config item's name.
[out]	value	The std::uint64_t value.

Returns

pmem::kv::status

init()

int pmem::kv::config::init ( )

inlineprivatenoexcept

Initialization function for config.

It's lazy initialized and called within all put functions.

Returns

int initialization result; 0 on success

put_comparator()

template<typename Comparator >

status pmem::kv::config::put_comparator ( Comparator &&  comparator )

inline

Puts comparator object to a config.

Comparator must:

• implement int compare(pmem::kv::string_view, pmem::kv::string_view)
• implement std::string name()
• be copy or move constructible
• be thread-safe

Parameters

[in]

comparator

forwarding reference to a comparator

Returns

pmem::kv::status

Example implementation of custom comparator:

class lexicographical_comparator {
public:
    int compare(string_view k1, string_view k2)
    {
        if (k1.compare(k2) == 0)
            return 0;
        else if (std::lexicographical_compare(k1.data(), k1.data() + k1.size(),
                              k2.data(), k2.data() + k2.size()))
            return -1;
        else
            return 1;
    }
 
    std::string name()
    {
        return "lexicographical_comparator";
    }
};

And example usage (set in config and use while itarating over keys):

    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);
    s = cfg.put_comparator(lexicographical_comparator{});
    ASSERT(s == status::OK);
 
    LOG("Opening pmemkv database with 'csmap' engine");
    db *kv = new db();
    ASSERT(kv != nullptr);
    s = kv->open("csmap", std::move(cfg));
    ASSERT(s == status::OK);
 
    LOG("Putting new keys");
    s = kv->put("key1", "value1");
    ASSERT(s == status::OK);
    s = kv->put("key2", "value2");
    ASSERT(s == status::OK);
    s = kv->put("key3", "value3");
    ASSERT(s == status::OK);
 
    LOG("Iterating over existing keys in order specified by the comparator");
    kv->get_all([](string_view k, string_view v) {
        LOG("  visited: " << k.data());
        return 0;
    });

put_create_if_missing()

status pmem::kv::config::put_create_if_missing ( bool  value )

inlinenoexcept

Puts create_if_missing parameter to a config.

This flag is mutually exclusive with create_or_error_if_exists (see config::put_create_or_error_if_exists). It works only with engines supporting this flag and it means: If true: pmemkv tries to open the pool and if that doesn't succeed it means there's (most likely) no pool to use, so it creates it. If false: pmemkv opens the pool, unless the path does not exist - then it fails. False by default.

Returns

pmem::kv::status

put_create_or_error_if_exists()

status pmem::kv::config::put_create_or_error_if_exists ( bool  value )

inlinenoexcept

Puts create_or_error_if_exists parameter to a config.

This flag is mutually exclusive with create_if_missing (see config::put_create_if_missing). It works only with engines supporting this flag and it means: If true: pmemkv creates the pool, unless it exists - then it fails. If false: pmemkv opens the pool, unless the path does not exist - then it fails. False by default.

Returns

pmem::kv::status

put_data()

template<typename T >

status pmem::kv::config::put_data ( const std::string &  key, const T *  value, const std::size_t  count = 1  )

inlinenoexcept

Puts binary data pointed by value, of type T, with count of elements to a config.

Count parameter is useful for putting arrays of data.

Parameters

[in]	key	The string representing config item's name.
[in]	value	The pointer to data.
[in]	count	The count of elements stored under reference.

Returns

pmem::kv::status

put_force_create()

status pmem::kv::config::put_force_create ( bool  value )

inlinenoexcept

It's an alias for config::put_create_or_error_if_exists, kept for compatibility.

Deprecated:

use config::put_create_or_error_if_exists instead.

Returns

pmem::kv::status

put_int64()

status pmem::kv::config::put_int64 ( const std::string &  key, std::int64_t  value  )

inlinenoexcept

Puts std::int64_t value to a config.

Parameters

[in]	key	The string representing config item's name.
[in]	value	The std::int64_t value.

Returns

pmem::kv::status

put_object() [1/2]

template<typename T , typename D >

status pmem::kv::config::put_object ( const std::string &  key, std::unique_ptr< T, D >  object  )

inlinenoexcept

Puts unique_ptr (to an object) to a config.

Parameters

[in]	key	The string representing config item's name.
[in]	object	unique_ptr to an object.

Returns

pmem::kv::status

put_object() [2/2]

template<typename T >

status pmem::kv::config::put_object ( const std::string &  key, T *  value, void(*)(void *)  deleter  )

inlinenoexcept

Puts object pointed by value, of type T, with given destructor to a config.

Parameters

[in]	key	The string representing config item's name.
[in]	value	The pointer to object.
[in]	deleter	The object's destructor function.

Returns

pmem::kv::status

put_oid()

status pmem::kv::config::put_oid ( PMEMoid *  oid )

inlinenoexcept

Puts PMEMoid object to a config.

Parameters

[in]

oid

pointer (for details see libpmemobj(7)) which points to the engine data. If oid is null, engine will allocate new data, otherwise it will use existing one.

Returns

pmem::kv::status

put_path()

status pmem::kv::config::put_path ( const std::string &  path )

inlinenoexcept

Puts path (of a database pool) to a config, to open or create.

Parameters

[in]

path

to a database file or to a poolset file (see poolset(5) for details). Note that when using poolset file, size should be 0.

Returns

pmem::kv::status

put_size()

status pmem::kv::config::put_size ( std::uint64_t  size )

inlinenoexcept

Puts size to a config, it's required when creating new database pool.

Parameters

[in]

size

of the database in bytes.

Returns

pmem::kv::status

put_string()

status pmem::kv::config::put_string ( const std::string &  key, const std::string &  value  )

inlinenoexcept

Puts string value to a config.

Parameters

[in]	key	The string representing config item's name.
[in]	value	The string value.

Returns

pmem::kv::status

put_uint64()

status pmem::kv::config::put_uint64 ( const std::string &  key, std::uint64_t  value  )

inlinenoexcept

Puts std::uint64_t value to a config.

Parameters

[in]	key	The string representing config item's name.
[in]	value	The std::uint64_t value.

Returns

pmem::kv::status

release()

pmemkv_config * pmem::kv::config::release ( )

inlinenoexcept

Similarly to std::unique_ptr::release it passes the ownership of underlying pmemkv_config variable and sets it to nullptr.

Returns

handle to pmemkv_config

Member Data Documentation

config_

std::unique_ptr<pmemkv_config, decltype(&pmemkv_config_delete)> pmem::kv::config::config_

private

---

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

• /pmemkv/src/libpmemkv.hpp