PMEMKV  1.5.0-git40.ga0a3589
This is the C++ documentation for PMEMKV.
Public Member Functions | Private Member Functions | Private Attributes | List of all members
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]keyThe string representing config item's name.
[out]valueThe pointer to data.
[out]countThe 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]keyThe string representing config item's name.
[out]valueThe 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]keyThe string representing config item's name.
[out]valueThe 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]keyThe string representing config item's name.
[out]valueThe 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]keyThe string representing config item's name.
[out]valueThe 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]comparatorforwarding 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";
}
};
obj::string_view string_view
Partial string_view implementation, defined in pmem::obj namespace in libpmemobj-cpp library (see: ht...
Definition: libpmemkv.hpp:47

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;
});
config() noexcept
Default constructor with uninitialized config.
Definition: libpmemkv.hpp:1258
status
Status returned by most of pmemkv functions.
Definition: libpmemkv.hpp:84

◆ 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]keyThe string representing config item's name.
[in]valueThe pointer to data.
[in]countThe count of elements stored under reference.
Returns
pmem::kv::status

◆ put_force_create()

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

◆ 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]keyThe string representing config item's name.
[in]valueThe 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]keyThe string representing config item's name.
[in]objectunique_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]keyThe string representing config item's name.
[in]valueThe pointer to object.
[in]deleterThe 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]oidpointer (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]pathto 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]sizeof 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]keyThe string representing config item's name.
[in]valueThe 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]keyThe string representing config item's name.
[in]valueThe 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: