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::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::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...
struct	mdbx::default_capacity_policy
struct	mdbx::buffer_tag
	Type tag for delivered buffer template classes. 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::buffer_pair_spec< ALLOCATOR, CAPACITY_POLICY >
class	mdbx::cache_entry
	Cache entry for get-cached API (initial draft). More...
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 >
struct	std::hash<::mdbx::map_handle >
struct	std::hash<::mdbx::env >
struct	std::hash<::mdbx::txn >
struct	std::hash<::mdbx::cursor >
struct	std::hash<::mdbx::buffer< ALLOCATOR, CAPACITY_POLICY > >

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, ...)
#define	MDBX_INSTALL_API_TEMPLATE(API_ATTRIBUTES, ...)
#define	MDBX_MSVC_DECLSPEC_EMPTY_BASES   /* nope */
#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_CXX_HAS_POLYMORPHIC_ALLOCATOR   1
	Defined as 1 if the mdbx::polymorphic_allocator is available.
#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
	The byte-like type that don't presumes aliases for pointers as does the char.
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::txnid = uint64_t
	Transaction ID and MVCC-snapshot number.
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.
using	mdbx::comparator = ::MDBX_cmp_func *
using	mdbx::default_buffer = buffer<default_allocator, default_capacity_policy>
	Default buffer.
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.

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
constexpr const version_info &	mdbx::get_version () noexcept
	Returns libmdbx version information.
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<typename A>
constexpr bool	mdbx::allocation_aware_details::allocator_is_always_equal () noexcept
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
constexpr bool	mdbx::operator== (const error &a, const error &b)
constexpr bool	mdbx::operator!= (const error &a, const error &b)
constexpr bool	mdbx::operator== (const slice &a, const slice &b)
constexpr bool	mdbx::operator< (const slice &a, const slice &b)
constexpr bool	mdbx::operator> (const slice &a, const slice &b)
constexpr bool	mdbx::operator<= (const slice &a, const slice &b)
constexpr bool	mdbx::operator>= (const slice &a, const slice &b)
constexpr bool	mdbx::operator!= (const slice &a, const slice &b)
template<class ALLOCATOR, typename CAPACITY_POLICY>
inline ::std::ostream &	mdbx::operator<< (::std::ostream &out, const buffer< ALLOCATOR, CAPACITY_POLICY > &it)
	mdbx::MDBX_EXTERN_API_TEMPLATE (LIBMDBX_API_TYPE, buffer< legacy_allocator, default_capacity_policy >)
	mdbx::MDBX_EXTERN_API_TEMPLATE (LIBMDBX_API_TYPE, buffer< polymorphic_allocator, default_capacity_policy >)
template<class ALLOCATOR, class CAPACITY_POLICY, MutableByteProducer PRODUCER>
buffer< ALLOCATOR, CAPACITY_POLICY >	mdbx::make_buffer (PRODUCER &producer, const ALLOCATOR &alloc)
template<class ALLOCATOR, class CAPACITY_POLICY, ImmutableByteProducer PRODUCER>
buffer< ALLOCATOR, CAPACITY_POLICY >	mdbx::make_buffer (const PRODUCER &producer, const ALLOCATOR &alloc)
template<class ALLOCATOR, MutableByteProducer PRODUCER>
string< ALLOCATOR >	mdbx::make_string (PRODUCER &producer, const ALLOCATOR &alloc)
template<class ALLOCATOR, ImmutableByteProducer PRODUCER>
string< ALLOCATOR >	mdbx::make_string (const PRODUCER &producer, const ALLOCATOR &alloc)
constexpr bool	mdbx::operator== (const pair &a, const pair &b)
constexpr bool	mdbx::operator< (const pair &a, const pair &b)
constexpr bool	mdbx::operator> (const pair &a, const pair &b)
constexpr bool	mdbx::operator<= (const pair &a, const pair &b)
constexpr bool	mdbx::operator>= (const pair &a, const pair &b)
constexpr bool	mdbx::operator!= (const pair &a, const pair &b)
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)
constexpr bool	mdbx::operator== (const env &a, const env &b)
constexpr bool	mdbx::operator!= (const env &a, const env &b)
constexpr bool	mdbx::operator== (const txn &a, const txn &b)
constexpr bool	mdbx::operator!= (const txn &a, const txn &b)
constexpr bool	mdbx::operator== (const cursor &a, const cursor &b)
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)
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 &)
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)
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)

Variables
template<class ALLOCATOR = default_allocator, class CAPACITY_POLICY = default_capacity_policy>
class MDBX_MSVC_DECLSPEC_EMPTY_BASES	mdbx::buffer

Detailed Description

The libmdbx C++ API header file.

libmdbx (aka MDBX) is an extremely fast, compact, powerful, embeddable, transactional key-value store, with Apache 2.0 license. MDBX has a specific set of properties and capabilities, focused on creating unique lightweight solutions with extraordinary performance.

Please visit https://libmdbx.dqdkfa.ru for more information, documentation, C++ API description and links to the origin git repo with the source code. Questions, feedback and suggestions are welcome to the Telegram' group https://t.me/libmdbx.

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

The libmdbx project has been completely relocated to the jurisdiction of the Russian Federation.

Note

libmdbx is still open and provided with first-class free support.

Copyright

SPDX-License-Identifier: Apache-2.0

Author

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

Date

2020-2026

---

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
size_t	stub_capacity_bytes_
allocator_pointer	stub_ptr_

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)]

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,
			... )

Value:

extern template class API_ATTRIBUTES __VA_ARGS__

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,
			... )

Value:

template class __VA_ARGS__

MDBX_LIKELY

#define MDBX_LIKELY

(

cond

)

Value:

__builtin_expect(!!(cond), 1)

MDBX_MSVC_DECLSPEC_EMPTY_BASES

#define MDBX_MSVC_DECLSPEC_EMPTY_BASES   /* nope */

MDBX_UNLIKELY

#define MDBX_UNLIKELY

(

cond

)

Value:

__builtin_expect(!!(cond), 0)

MDBX_USING_CXX_EXPERIMETAL_FILESYSTEM

#define MDBX_USING_CXX_EXPERIMETAL_FILESYSTEM   0