mdbx.h++ File Reference

The libmdbx C++ API header file. More...

#include <algorithm>
#include <cassert>
#include <climits>
#include <cstring>
#include <exception>
#include <ostream>
#include <sstream>
#include <stdexcept>
#include <string>
#include <type_traits>
#include <utility>
#include <vector>
#include "mdbx.h"

Go to the source code of this file.

Classes
class	mdbx::exception_thunk
	Transfers C++ exceptions thru C callbacks. More...
class	mdbx::error
	Implements error information and throwing corresponding exceptions. More...
class	mdbx::exception
	Base class for all libmdbx's exceptions that are corresponds to libmdbx errors. More...
class	mdbx::fatal
	Fatal exception that lead termination anyway in dangerous unrecoverable cases. More...
struct	mdbx::bad_map_id
struct	mdbx::bad_transaction
struct	mdbx::bad_value_size
struct	mdbx::db_corrupted
struct	mdbx::db_full
struct	mdbx::db_invalid
struct	mdbx::db_too_large
struct	mdbx::db_unable_extend
struct	mdbx::db_version_mismatch
struct	mdbx::db_wanna_write_for_recovery
struct	mdbx::incompatible_operation
struct	mdbx::internal_page_full
struct	mdbx::internal_problem
struct	mdbx::key_exists
struct	mdbx::key_mismatch
struct	mdbx::max_maps_reached
struct	mdbx::max_readers_reached
struct	mdbx::multivalue
struct	mdbx::no_data
struct	mdbx::not_found
struct	mdbx::operation_not_permitted
struct	mdbx::permission_denied_or_not_writeable
struct	mdbx::reader_slot_busy
struct	mdbx::remote_media
struct	mdbx::something_busy
struct	mdbx::thread_mismatch
struct	mdbx::transaction_full
struct	mdbx::transaction_overlapping
struct	mdbx::duplicated_lck_file
struct	mdbx::dangling_map_id
struct	mdbx::transaction_ousted
struct	mdbx::mvcc_retarded
struct	mdbx::slice
	References a data located outside the slice. More...
struct	mdbx::default_capacity_policy
struct	mdbx::to_hex
	Hexadecimal encoder which satisfy SliceTranscoder concept. More...
struct	mdbx::to_base58
	Base58 encoder which satisfy SliceTranscoder concept. More...
struct	mdbx::to_base64
	Base64 encoder which satisfy SliceTranscoder concept. More...
struct	mdbx::from_hex
	Hexadecimal decoder which satisfy SliceTranscoder concept. More...
struct	mdbx::from_base58
	Base58 decoder which satisfy SliceTranscoder concept. More...
struct	mdbx::from_base64
	Base64 decoder which satisfy SliceTranscoder concept. More...
class	mdbx::buffer< ALLOCATOR, CAPACITY_POLICY >
	The chunk of data stored inside the buffer or located outside it. More...
union	mdbx::buffer< ALLOCATOR, CAPACITY_POLICY >::silo::bin
struct	mdbx::buffer< ALLOCATOR, CAPACITY_POLICY >::silo::bin::stub_allocated_holder
struct	mdbx::buffer< ALLOCATOR, CAPACITY_POLICY >::silo::bin::capacity_holder
struct	mdbx::buffer< ALLOCATOR, CAPACITY_POLICY >::silo::bin::inplace_flag_holder
struct	mdbx::value_result
	Combines data slice with boolean flag to represent result of certain operations. More...
struct	mdbx::pair
	Combines pair of slices for key and value to represent result of certain operations. More...
struct	mdbx::pair_result
	Combines pair of slices for key and value with boolean flag to represent result of certain operations. More...
struct	mdbx::buffer_pair_spec< ALLOCATOR, CAPACITY_POLICY >
struct	mdbx::map_handle
	A handle for an individual table (aka key-value space, maps or sub-database) in the environment. More...
struct	mdbx::map_handle::info
class	mdbx::env
	Unmanaged database environment. More...
struct	mdbx::env::geometry
	Database geometry for size management. More...
struct	mdbx::env::geometry::size
	Tagged type for output to std::ostream. More...
struct	mdbx::env::reclaiming_options
	Garbage reclaiming options. More...
struct	mdbx::env::operate_options
	Operate options. More...
struct	mdbx::env::operate_parameters
	Operate parameters. More...
struct	mdbx::env::limits
struct	mdbx::env::reader_info
	Reader information. More...
class	mdbx::env_managed
	Managed database environment. More...
struct	mdbx::env_managed::create_parameters
	Additional parameters for creating a new database. More...
class	mdbx::txn
	Unmanaged database transaction. More...
class	mdbx::txn_managed
	Managed database transaction. More...
class	mdbx::cursor
	Unmanaged cursor. More...
struct	mdbx::cursor::move_result
struct	mdbx::cursor::estimate_result
class	mdbx::cursor_managed
	Managed cursor. More...
struct	std::hash<::mdbx::slice >

Namespaces
namespace	mdbx
	The libmdbx C++ API namespace.
namespace	mdbx::allocation_aware_details
namespace	std
	STL namespace.

Concepts
concept	mdbx::MutableByteProducer
concept	mdbx::ImmutableByteProducer
concept	mdbx::SliceTranscoder

Macros
#define	MDBX_USING_CXX_EXPERIMETAL_FILESYSTEM   0
#define	MDBX_EXTERN_API_TEMPLATE(API_ATTRIBUTES, API_TYPENAME)
#define	MDBX_INSTALL_API_TEMPLATE(API_ATTRIBUTES, API_TYPENAME)
#define	MDBX_CXX17_CONSTEXPR   constexpr
#define	MDBX_CXX20_CONSTEXPR   constexpr
#define	MDBX_CXX01_CONSTEXPR_ENUM   MDBX_CXX01_CONSTEXPR
#define	MDBX_CXX11_CONSTEXPR_ENUM   MDBX_CXX11_CONSTEXPR
#define	MDBX_CXX14_CONSTEXPR_ENUM   MDBX_CXX14_CONSTEXPR
#define	MDBX_CXX17_CONSTEXPR_ENUM   MDBX_CXX17_CONSTEXPR
#define	MDBX_CXX20_CONSTEXPR_ENUM   MDBX_CXX20_CONSTEXPR
#define	MDBX_CONSTEXPR_ASSERT(expr)
#define	MDBX_LIKELY(cond)
#define	MDBX_UNLIKELY(cond)
#define	MDBX_IF_CONSTEXPR   constexpr
#define	MDBX_CXX17_FALLTHROUGH   [[fallthrough]]
#define	MDBX_CXX20_LIKELY   [[likely]]
#define	MDBX_ASSERT_CXX20_CONCEPT_SATISFIED(CONCEPT, TYPE)
#define	MDBX_STD_FILESYSTEM_PATH   ::mdbx::filesystem::path
	Defined if mdbx::filesystem::path is available.
#define	MDBX_DECLARE_EXCEPTION(NAME)

Typedefs
using	mdbx::byte = char8_t
using	mdbx::version_info = ::MDBX_version_info
	libmdbx version information,
using	mdbx::build_info = ::MDBX_build_info
	libmdbx build information
using	mdbx::legacy_allocator = ::std::string::allocator_type
	Legacy allocator but it is recommended to use polymorphic_allocator.
using	mdbx::polymorphic_allocator = ::std::pmr::string::allocator_type
	Default polymorphic allocator for modern code.
using	mdbx::default_allocator = polymorphic_allocator
using	mdbx::default_buffer = buffer<default_allocator, default_capacity_policy>
	Default buffer.
template<class ALLOCATOR = default_allocator>
using	mdbx::string = ::std::basic_string<char, ::std::char_traits<char>, ALLOCATOR>
	Default single-byte string.
using	mdbx::filehandle = ::mdbx_filehandle_t
using	mdbx::path = ::mdbx::filesystem::path
using	mdbx::duration = ::std::chrono::duration<unsigned, ::std::ratio<1, 65536>>
	Duration in 1/65536 units of second.
template<typename BUFFER>
using	mdbx::buffer_pair = buffer_pair_spec<typename BUFFER::allocator_type, typename BUFFER::reservation_policy>
	Combines pair of buffers for key and value to hold an operands for certain operations.
using	mdbx::default_buffer_pair = buffer_pair<default_buffer>
	Default pair of buffers.
using	mdbx::comparator = ::MDBX_cmp_func *

Enumerations
enum	mdbx::loop_control { mdbx::continue_loop = 0 , mdbx::exit_loop = INT32_MIN }
	Loop control constants for readers enumeration functor and other cases. More...
enum class	mdbx::key_mode { mdbx::key_mode::usual = MDBX_DB_DEFAULTS , mdbx::key_mode::reverse = MDBX_REVERSEKEY , mdbx::key_mode::ordinal = MDBX_INTEGERKEY , mdbx::key_mode::msgpack = -1 }
	Kinds of the keys and corresponding modes of comparing it. More...
enum class	mdbx::value_mode {   mdbx::value_mode::single = MDBX_DB_DEFAULTS , mdbx::value_mode::multi = MDBX_DUPSORT , mdbx::value_mode::multi_reverse = MDBX_DUPSORT | MDBX_REVERSEDUP , mdbx::value_mode::multi_samelength = MDBX_DUPSORT | MDBX_DUPFIXED ,   mdbx::value_mode::multi_ordinal = MDBX_DUPSORT | MDBX_DUPFIXED | MDBX_INTEGERDUP , mdbx::value_mode::multi_reverse_samelength , mdbx::value_mode::msgpack = -1 }
	Kind of the values and sorted multi-values with corresponding comparison. More...
enum	mdbx::put_mode { mdbx::insert_unique = MDBX_NOOVERWRITE , mdbx::upsert = MDBX_UPSERT , mdbx::update = MDBX_CURRENT }
	Key-value pairs put mode. More...

Functions
MDBX_CXX11_CONSTEXPR const version_info &	mdbx::get_version () noexcept
	Returns libmdbx version information.
MDBX_CXX11_CONSTEXPR const build_info &	mdbx::get_build () noexcept
	Returns libmdbx build information.
LIBMDBX_API void	mdbx::throw_too_small_target_buffer ()
LIBMDBX_API void	mdbx::throw_max_length_exceeded ()
LIBMDBX_API void	mdbx::throw_out_range ()
LIBMDBX_API void	mdbx::throw_allocators_mismatch ()
LIBMDBX_API void	mdbx::throw_bad_value_size ()
LIBMDBX_API void	mdbx::throw_incomparable_cursors ()
template<class ALLOCATOR = default_allocator, typename CAPACITY_POLICY = default_capacity_policy, MutableByteProducer PRODUCER>
buffer< ALLOCATOR, CAPACITY_POLICY >	mdbx::make_buffer (PRODUCER &producer, const ALLOCATOR &allocator=ALLOCATOR())
template<class ALLOCATOR = default_allocator, typename CAPACITY_POLICY = default_capacity_policy, ImmutableByteProducer PRODUCER>
buffer< ALLOCATOR, CAPACITY_POLICY >	mdbx::make_buffer (const PRODUCER &producer, const ALLOCATOR &allocator=ALLOCATOR())
template<class ALLOCATOR = default_allocator, MutableByteProducer PRODUCER>
string< ALLOCATOR >	mdbx::make_string (PRODUCER &producer, const ALLOCATOR &allocator=ALLOCATOR())
template<class ALLOCATOR = default_allocator, ImmutableByteProducer PRODUCER>
string< ALLOCATOR >	mdbx::make_string (const PRODUCER &producer, const ALLOCATOR &allocator=ALLOCATOR())
template<typename A>
constexpr bool	mdbx::allocation_aware_details::allocator_is_always_equal () noexcept
inline ::std::ostream &	mdbx::operator<< (::std::ostream &out, const to_hex &wrapper)
inline ::std::ostream &	mdbx::operator<< (::std::ostream &out, const to_base58 &wrapper)
inline ::std::ostream &	mdbx::operator<< (::std::ostream &out, const to_base64 &wrapper)
	mdbx::MDBX_EXTERN_API_TEMPLATE (LIBMDBX_API_TYPE, buffer< legacy_allocator >)
MDBX_CXX01_CONSTEXPR_ENUM bool	mdbx::is_usual (key_mode mode) noexcept
MDBX_CXX01_CONSTEXPR_ENUM bool	mdbx::is_ordinal (key_mode mode) noexcept
MDBX_CXX01_CONSTEXPR_ENUM bool	mdbx::is_samelength (key_mode mode) noexcept
MDBX_CXX01_CONSTEXPR_ENUM bool	mdbx::is_reverse (key_mode mode) noexcept
MDBX_CXX01_CONSTEXPR_ENUM bool	mdbx::is_msgpack (key_mode mode) noexcept
MDBX_CXX01_CONSTEXPR_ENUM bool	mdbx::is_usual (value_mode mode) noexcept
MDBX_CXX01_CONSTEXPR_ENUM bool	mdbx::is_multi (value_mode mode) noexcept
MDBX_CXX01_CONSTEXPR_ENUM bool	mdbx::is_ordinal (value_mode mode) noexcept
MDBX_CXX01_CONSTEXPR_ENUM bool	mdbx::is_samelength (value_mode mode) noexcept
MDBX_CXX01_CONSTEXPR_ENUM bool	mdbx::is_reverse (value_mode mode) noexcept
MDBX_CXX01_CONSTEXPR_ENUM bool	mdbx::is_msgpack (value_mode mode) noexcept
comparator	mdbx::default_comparator (key_mode mode) noexcept
comparator	mdbx::default_comparator (value_mode mode) noexcept
LIBMDBX_API::std::ostream &	mdbx::operator<< (::std::ostream &, const slice &)
LIBMDBX_API::std::ostream &	mdbx::operator<< (::std::ostream &, const pair &)
LIBMDBX_API::std::ostream &	mdbx::operator<< (::std::ostream &, const pair_result &)
template<class ALLOCATOR, typename CAPACITY_POLICY>
inline ::std::ostream &	mdbx::operator<< (::std::ostream &out, const buffer< ALLOCATOR, CAPACITY_POLICY > &it)
LIBMDBX_API::std::ostream &	mdbx::operator<< (::std::ostream &, const env::geometry::size &)
LIBMDBX_API::std::ostream &	mdbx::operator<< (::std::ostream &, const env::geometry &)
LIBMDBX_API::std::ostream &	mdbx::operator<< (::std::ostream &, const env::operate_parameters &)
LIBMDBX_API::std::ostream &	mdbx::operator<< (::std::ostream &, const env::mode &)
LIBMDBX_API::std::ostream &	mdbx::operator<< (::std::ostream &, const env::durability &)
LIBMDBX_API::std::ostream &	mdbx::operator<< (::std::ostream &, const env::reclaiming_options &)
LIBMDBX_API::std::ostream &	mdbx::operator<< (::std::ostream &, const env::operate_options &)
LIBMDBX_API::std::ostream &	mdbx::operator<< (::std::ostream &, const env_managed::create_parameters &)
LIBMDBX_API::std::ostream &	mdbx::operator<< (::std::ostream &, const MDBX_log_level_t &)
LIBMDBX_API::std::ostream &	mdbx::operator<< (::std::ostream &, const MDBX_debug_flags_t &)
LIBMDBX_API::std::ostream &	mdbx::operator<< (::std::ostream &, const error &)
inline ::std::ostream &	mdbx::operator<< (::std::ostream &out, const MDBX_error_t &errcode)
MDBX_CXX11_CONSTEXPR bool	mdbx::operator== (const error &a, const error &b)
MDBX_CXX11_CONSTEXPR bool	mdbx::operator!= (const error &a, const error &b)
MDBX_NOTHROW_PURE_FUNCTION MDBX_CXX14_CONSTEXPR bool	mdbx::operator== (const slice &a, const slice &b)
MDBX_NOTHROW_PURE_FUNCTION MDBX_CXX14_CONSTEXPR bool	mdbx::operator< (const slice &a, const slice &b)
MDBX_NOTHROW_PURE_FUNCTION MDBX_CXX14_CONSTEXPR bool	mdbx::operator> (const slice &a, const slice &b)
MDBX_NOTHROW_PURE_FUNCTION MDBX_CXX14_CONSTEXPR bool	mdbx::operator<= (const slice &a, const slice &b)
MDBX_NOTHROW_PURE_FUNCTION MDBX_CXX14_CONSTEXPR bool	mdbx::operator>= (const slice &a, const slice &b)
MDBX_NOTHROW_PURE_FUNCTION MDBX_CXX14_CONSTEXPR bool	mdbx::operator!= (const slice &a, const slice &b)
MDBX_NOTHROW_PURE_FUNCTION MDBX_CXX14_CONSTEXPR bool	mdbx::operator== (const pair &a, const pair &b)
MDBX_NOTHROW_PURE_FUNCTION MDBX_CXX14_CONSTEXPR bool	mdbx::operator< (const pair &a, const pair &b)
MDBX_NOTHROW_PURE_FUNCTION MDBX_CXX14_CONSTEXPR bool	mdbx::operator> (const pair &a, const pair &b)
MDBX_NOTHROW_PURE_FUNCTION MDBX_CXX14_CONSTEXPR bool	mdbx::operator<= (const pair &a, const pair &b)
MDBX_NOTHROW_PURE_FUNCTION MDBX_CXX14_CONSTEXPR bool	mdbx::operator>= (const pair &a, const pair &b)
MDBX_NOTHROW_PURE_FUNCTION MDBX_CXX14_CONSTEXPR bool	mdbx::operator!= (const pair &a, const pair &b)
MDBX_CXX11_CONSTEXPR bool	mdbx::operator== (const env &a, const env &b)
MDBX_CXX11_CONSTEXPR bool	mdbx::operator!= (const env &a, const env &b)
MDBX_CXX11_CONSTEXPR bool	mdbx::operator== (const txn &a, const txn &b)
MDBX_CXX11_CONSTEXPR bool	mdbx::operator!= (const txn &a, const txn &b)
MDBX_CXX11_CONSTEXPR bool	mdbx::operator== (const cursor &a, const cursor &b)
MDBX_CXX11_CONSTEXPR bool	mdbx::operator!= (const cursor &a, const cursor &b)
int	mdbx::compare_position_nothrow (const cursor &left, const cursor &right, bool ignore_nested=false)
int	mdbx::compare_position (const cursor &left, const cursor &right, bool ignore_nested=false)
ptrdiff_t	mdbx::estimate (const cursor &from, const cursor &to)
string	std::to_string (const ::mdbx::slice &value)
template<class ALLOCATOR, typename CAPACITY_POLICY>
string	std::to_string (const ::mdbx::buffer< ALLOCATOR, CAPACITY_POLICY > &buffer)
string	std::to_string (const ::mdbx::pair &value)
string	std::to_string (const ::mdbx::env::geometry &value)
string	std::to_string (const ::mdbx::env::operate_parameters &value)
string	std::to_string (const ::mdbx::env::mode &value)
string	std::to_string (const ::mdbx::env::durability &value)
string	std::to_string (const ::mdbx::env::reclaiming_options &value)
string	std::to_string (const ::mdbx::env::operate_options &value)
string	std::to_string (const ::mdbx::env_managed::create_parameters &value)
string	std::to_string (const ::MDBX_log_level_t &value)
string	std::to_string (const ::MDBX_debug_flags_t &value)
string	std::to_string (const ::mdbx::error &value)
string	std::to_string (const ::MDBX_error_t &errcode)

Detailed Description

The libmdbx C++ API header file.

Copyright

SPDX-License-Identifier: Apache-2.0

Author

Леонид Юрьев aka Leonid Yuriev leo@y.nosp@m.urie.nosp@m.v.ru

Date

2020-2025

Donations are welcome to ETH 0xD104d8f8B2dC312aaD74899F83EBf3EEBDC1EA3A. Всё будет хорошо!

Tested with:

• Elbrus LCC >= 1.23 (http://www.mcst.ru/lcc);
• GNU C++ >= 4.8;
• clang >= 3.9;
• MSVC >= 14.0 (Visual Studio 2015), but 19.2x could hang due optimizer bug;
• AppleClang, but without C++20 concepts.

---

Class Documentation

mdbx::buffer::silo::bin::stub_allocated_holder

struct mdbx::buffer::silo::bin::stub_allocated_holder

template<class ALLOCATOR, typename CAPACITY_POLICY>
struct mdbx::buffer< ALLOCATOR, CAPACITY_POLICY >::silo::bin::stub_allocated_holder

Class Members
allocator_pointer	ptr_
size_t	stub_capacity_bytes_

mdbx::buffer::silo::bin::capacity_holder

struct mdbx::buffer::silo::bin::capacity_holder

template<class ALLOCATOR, typename CAPACITY_POLICY>
struct mdbx::buffer< ALLOCATOR, CAPACITY_POLICY >::silo::bin::capacity_holder

Class Members
size_t	bytes_
byte	pad_[inplace_size - sizeof(allocator_pointer)]

mdbx::buffer::silo::bin::inplace_flag_holder

struct mdbx::buffer::silo::bin::inplace_flag_holder

template<class ALLOCATOR, typename CAPACITY_POLICY>
struct mdbx::buffer< ALLOCATOR, CAPACITY_POLICY >::silo::bin::inplace_flag_holder

Class Members
byte	buffer_[inplace_size - sizeof(byte)]
byte	lastbyte_

Macro Definition Documentation

MDBX_ASSERT_CXX20_CONCEPT_SATISFIED

#define MDBX_ASSERT_CXX20_CONCEPT_SATISFIED	(		CONCEPT,
			TYPE )

Value:

static_assert(CONCEPT<TYPE>)

MDBX_CONSTEXPR_ASSERT

#define MDBX_CONSTEXPR_ASSERT

(

expr

)

Value:

((expr) ? void(0) : [] { assert(!#expr); }())

Workaround for old compilers without support assertion inside constexpr functions.

MDBX_CXX01_CONSTEXPR_ENUM

#define MDBX_CXX01_CONSTEXPR_ENUM   MDBX_CXX01_CONSTEXPR

MDBX_CXX11_CONSTEXPR_ENUM

#define MDBX_CXX11_CONSTEXPR_ENUM   MDBX_CXX11_CONSTEXPR

MDBX_CXX14_CONSTEXPR_ENUM

#define MDBX_CXX14_CONSTEXPR_ENUM   MDBX_CXX14_CONSTEXPR

MDBX_CXX17_CONSTEXPR

#define MDBX_CXX17_CONSTEXPR   constexpr

Workaround for old compilers without properly support for C++17 constexpr

MDBX_CXX17_CONSTEXPR_ENUM

#define MDBX_CXX17_CONSTEXPR_ENUM   MDBX_CXX17_CONSTEXPR

MDBX_CXX17_FALLTHROUGH

#define MDBX_CXX17_FALLTHROUGH   [[fallthrough]]

MDBX_CXX20_CONSTEXPR

#define MDBX_CXX20_CONSTEXPR   constexpr

Workaround for old compilers without properly support for C++20 constexpr.

MDBX_CXX20_CONSTEXPR_ENUM

#define MDBX_CXX20_CONSTEXPR_ENUM   MDBX_CXX20_CONSTEXPR

MDBX_CXX20_LIKELY

#define MDBX_CXX20_LIKELY   [[likely]]

MDBX_EXTERN_API_TEMPLATE

#define MDBX_EXTERN_API_TEMPLATE	(		API_ATTRIBUTES,
			API_TYPENAME )

Value:

extern template class API_ATTRIBUTES API_TYPENAME

MDBX_IF_CONSTEXPR

#define MDBX_IF_CONSTEXPR   constexpr

Workaround for old compilers without properly support for C++20 if constexpr.

MDBX_INSTALL_API_TEMPLATE

#define MDBX_INSTALL_API_TEMPLATE	(		API_ATTRIBUTES,
			API_TYPENAME )

Value:

template class API_TYPENAME

MDBX_LIKELY

#define MDBX_LIKELY

(

cond

)

Value:

__builtin_expect(!!(cond), 1)

MDBX_UNLIKELY

#define MDBX_UNLIKELY

(

cond

)

Value:

__builtin_expect(!!(cond), 0)

MDBX_USING_CXX_EXPERIMETAL_FILESYSTEM

#define MDBX_USING_CXX_EXPERIMETAL_FILESYSTEM   0