ISAR/libmdbx
3
0
Fork 0
mirror of https://github.com/isar/libmdbx.git synced 2025-03-27 00:26:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

mdbx++: minor reflow Doxygen comments.

Browse Source
This commit is contained in:
Leo Yuriev 2025-03-17 13:53:36 +03:00 committed by Леонид Юрьев (Leonid Yuriev)
parent c0b1ab1466
commit e6891b295b
1 changed files with 68 additions and 137 deletions

205
mdbx.h++

@ -158,8 +158,7 @@
#endif #endif
#endif /* Byte Order */ #endif /* Byte Order */
/** Workaround for old compilers without properly support for `C++17 constexpr`. /** Workaround for old compilers without properly support for `C++17 constexpr` */
*/
#if defined(DOXYGEN) #if defined(DOXYGEN)
#define MDBX_CXX17_CONSTEXPR constexpr #define MDBX_CXX17_CONSTEXPR constexpr
#elif defined(__cpp_constexpr) && __cpp_constexpr >= 201603L && \ #elif defined(__cpp_constexpr) && __cpp_constexpr >= 201603L && \
@ -170,8 +169,7 @@
#define MDBX_CXX17_CONSTEXPR inline #define MDBX_CXX17_CONSTEXPR inline
#endif /* MDBX_CXX17_CONSTEXPR */ #endif /* MDBX_CXX17_CONSTEXPR */
/** Workaround for old compilers without properly support for C++20 `constexpr`. /** Workaround for old compilers without properly support for C++20 `constexpr`. */
*/
#if defined(DOXYGEN) #if defined(DOXYGEN)
#define MDBX_CXX20_CONSTEXPR constexpr #define MDBX_CXX20_CONSTEXPR constexpr
#elif defined(__cpp_lib_is_constant_evaluated) && __cpp_lib_is_constant_evaluated >= 201811L && \ #elif defined(__cpp_lib_is_constant_evaluated) && __cpp_lib_is_constant_evaluated >= 201811L && \
@ -195,8 +193,7 @@
#define MDBX_CXX20_CONSTEXPR_ENUM inline #define MDBX_CXX20_CONSTEXPR_ENUM inline
#endif /* CONSTEXPR_ENUM_FLAGS_OPERATIONS */ #endif /* CONSTEXPR_ENUM_FLAGS_OPERATIONS */
/** Workaround for old compilers without support assertion inside `constexpr` /** Workaround for old compilers without support assertion inside `constexpr` functions. */
* functions. */
#if defined(CONSTEXPR_ASSERT) #if defined(CONSTEXPR_ASSERT)
#define MDBX_CONSTEXPR_ASSERT(expr) CONSTEXPR_ASSERT(expr) #define MDBX_CONSTEXPR_ASSERT(expr) CONSTEXPR_ASSERT(expr)
#elif defined NDEBUG #elif defined NDEBUG
@ -221,8 +218,7 @@
#endif #endif
#endif /* MDBX_UNLIKELY */ #endif /* MDBX_UNLIKELY */
/** Workaround for old compilers without properly support for C++20 `if /** Workaround for old compilers without properly support for C++20 `if constexpr`. */
* constexpr`. */
#if defined(DOXYGEN) #if defined(DOXYGEN)
#define MDBX_IF_CONSTEXPR constexpr #define MDBX_IF_CONSTEXPR constexpr
#elif defined(__cpp_if_constexpr) && __cpp_if_constexpr >= 201606L #elif defined(__cpp_if_constexpr) && __cpp_if_constexpr >= 201606L
@ -398,8 +394,7 @@ namespace filesystem = ::std::experimental::filesystem;
namespace filesystem = ::std::filesystem; namespace filesystem = ::std::filesystem;
/// \brief Defined if `mdbx::filesystem::path` is available. /// \brief Defined if `mdbx::filesystem::path` is available.
/// \details If defined, it is always `mdbx::filesystem::path`, /// \details If defined, it is always `mdbx::filesystem::path`,
/// which in turn can be refs to `std::filesystem::path` /// which in turn can be refs to `std::filesystem::path` or `std::experimental::filesystem::path`.
/// or `std::experimental::filesystem::path`.
/// Nonetheless `MDBX_STD_FILESYSTEM_PATH` not defined if the `::mdbx::path` /// Nonetheless `MDBX_STD_FILESYSTEM_PATH` not defined if the `::mdbx::path`
/// is fallbacked to c `std::string` or `std::wstring`. /// is fallbacked to c `std::string` or `std::wstring`.
#define MDBX_STD_FILESYSTEM_PATH ::mdbx::filesystem::path #define MDBX_STD_FILESYSTEM_PATH ::mdbx::filesystem::path
@ -499,9 +494,7 @@ public:
static inline void success_or_panic(int error_code, const char *context_where, const char *func_who) noexcept; static inline void success_or_panic(int error_code, const char *context_where, const char *func_who) noexcept;
}; };
/// \brief Base class for all libmdbx's exceptions that are corresponds /// \brief Base class for all libmdbx's exceptions that are corresponds to libmdbx errors.
/// to libmdbx errors.
///
/// \see MDBX_error_t /// \see MDBX_error_t
class LIBMDBX_API_TYPE exception : public ::std::runtime_error { class LIBMDBX_API_TYPE exception : public ::std::runtime_error {
using base = ::std::runtime_error; using base = ::std::runtime_error;
@ -517,8 +510,7 @@ public:
const ::mdbx::error error() const noexcept { return error_; } const ::mdbx::error error() const noexcept { return error_; }
}; };
/// \brief Fatal exception that lead termination anyway /// \brief Fatal exception that lead termination anyway in dangerous unrecoverable cases.
/// in dangerous unrecoverable cases.
class LIBMDBX_API_TYPE fatal : public exception { class LIBMDBX_API_TYPE fatal : public exception {
using base = exception; using base = exception;
@ -654,8 +646,7 @@ struct LIBMDBX_API_TYPE slice : public ::MDBX_val {
/// \brief Create an empty slice. /// \brief Create an empty slice.
MDBX_CXX11_CONSTEXPR slice() noexcept; MDBX_CXX11_CONSTEXPR slice() noexcept;
/// \brief Create a slice that refers to [0,bytes-1] of memory bytes pointed /// \brief Create a slice that refers to [0,bytes-1] of memory bytes pointed by ptr.
/// by ptr.
MDBX_CXX14_CONSTEXPR slice(const void *ptr, size_t bytes); MDBX_CXX14_CONSTEXPR slice(const void *ptr, size_t bytes);
/// \brief Create a slice that refers to [begin,end] of memory bytes. /// \brief Create a slice that refers to [begin,end] of memory bytes.
@ -1010,8 +1001,7 @@ struct LIBMDBX_API_TYPE slice : public ::MDBX_val {
/// \brief Checks the slice is not refers to null address or has zero length. /// \brief Checks the slice is not refers to null address or has zero length.
MDBX_CXX11_CONSTEXPR bool is_valid() const noexcept { return !(iov_base == nullptr && iov_len != 0); } MDBX_CXX11_CONSTEXPR bool is_valid() const noexcept { return !(iov_base == nullptr && iov_len != 0); }
/// \brief Build an invalid slice which non-zero length and refers to null /// \brief Build an invalid slice which non-zero length and refers to null address.
/// address.
MDBX_CXX14_CONSTEXPR static slice invalid() noexcept { return slice(size_t(-1)); } MDBX_CXX14_CONSTEXPR static slice invalid() noexcept { return slice(size_t(-1)); }
template <typename POD> MDBX_CXX14_CONSTEXPR POD as_pod() const { template <typename POD> MDBX_CXX14_CONSTEXPR POD as_pod() const {
@ -1239,8 +1229,7 @@ struct LIBMDBX_API to_hex {
char *write_bytes(char *dest, size_t dest_size) const; char *write_bytes(char *dest, size_t dest_size) const;
/// \brief Output hexadecimal dump of passed slice to the std::ostream. /// \brief Output hexadecimal dump of passed slice to the std::ostream.
/// \throws std::ios_base::failure corresponding to std::ostream::write() /// \throws std::ios_base::failure corresponding to std::ostream::write() behaviour.
/// behaviour.
::std::ostream &output(::std::ostream &out) const; ::std::ostream &output(::std::ostream &out) const;
/// \brief Checks whether a passed slice is empty, /// \brief Checks whether a passed slice is empty,
@ -1283,23 +1272,18 @@ struct LIBMDBX_API to_base58 {
return wrap_width ? bytes + bytes / wrap_width : bytes; return wrap_width ? bytes + bytes / wrap_width : bytes;
} }
/// \brief Fills the buffer by [Base58](https://en.wikipedia.org/wiki/Base58) /// \brief Fills the buffer by [Base58](https://en.wikipedia.org/wiki/Base58) dump of passed slice.
/// dump of passed slice.
/// \throws std::length_error if given buffer is too small. /// \throws std::length_error if given buffer is too small.
char *write_bytes(char *dest, size_t dest_size) const; char *write_bytes(char *dest, size_t dest_size) const;
/// \brief Output [Base58](https://en.wikipedia.org/wiki/Base58) /// \brief Output [Base58](https://en.wikipedia.org/wiki/Base58) dump of passed slice to the std::ostream.
/// dump of passed slice to the std::ostream. /// \throws std::ios_base::failure corresponding to std::ostream::write() behaviour.
/// \throws std::ios_base::failure corresponding to std::ostream::write()
/// behaviour.
::std::ostream &output(::std::ostream &out) const; ::std::ostream &output(::std::ostream &out) const;
/// \brief Checks whether a passed slice is empty, /// \brief Checks whether a passed slice is empty, and therefore there will be no output bytes.
/// and therefore there will be no output bytes.
bool is_empty() const noexcept { return source.empty(); } bool is_empty() const noexcept { return source.empty(); }
/// \brief Checks whether the content of a passed slice is a valid data /// \brief Checks whether the content of a passed slice is a valid data and could be encoded or unexpectedly not.
/// and could be encoded or unexpectedly not.
bool is_erroneous() const noexcept { return false; } bool is_erroneous() const noexcept { return false; }
}; };
@ -1341,8 +1325,7 @@ struct LIBMDBX_API to_base64 {
/// \brief Output [Base64](https://en.wikipedia.org/wiki/Base64) /// \brief Output [Base64](https://en.wikipedia.org/wiki/Base64)
/// dump of passed slice to the std::ostream. /// dump of passed slice to the std::ostream.
/// \throws std::ios_base::failure corresponding to std::ostream::write() /// \throws std::ios_base::failure corresponding to std::ostream::write() behaviour.
/// behaviour.
::std::ostream &output(::std::ostream &out) const; ::std::ostream &output(::std::ostream &out) const;
/// \brief Checks whether a passed slice is empty, /// \brief Checks whether a passed slice is empty,
@ -1383,13 +1366,11 @@ struct LIBMDBX_API from_hex {
/// hexadecimal dump from a passed slice to decoded data. /// hexadecimal dump from a passed slice to decoded data.
MDBX_CXX11_CONSTEXPR size_t envisage_result_length() const noexcept { return source.length() >> 1; } MDBX_CXX11_CONSTEXPR size_t envisage_result_length() const noexcept { return source.length() >> 1; }
/// \brief Fills the destination with data decoded from hexadecimal dump /// \brief Fills the destination with data decoded from hexadecimal dump from a passed slice.
/// from a passed slice.
/// \throws std::length_error if given buffer is too small. /// \throws std::length_error if given buffer is too small.
char *write_bytes(char *dest, size_t dest_size) const; char *write_bytes(char *dest, size_t dest_size) const;
/// \brief Checks whether a passed slice is empty, /// \brief Checks whether a passed slice is empty, and therefore there will be no output bytes.
/// and therefore there will be no output bytes.
bool is_empty() const noexcept { return source.empty(); } bool is_empty() const noexcept { return source.empty(); }
/// \brief Checks whether the content of a passed slice is a valid hexadecimal /// \brief Checks whether the content of a passed slice is a valid hexadecimal
@ -1422,8 +1403,7 @@ struct LIBMDBX_API from_base58 {
} }
/// \brief Returns the number of bytes needed for conversion /// \brief Returns the number of bytes needed for conversion
/// [Base58](https://en.wikipedia.org/wiki/Base58) dump from a passed slice to /// [Base58](https://en.wikipedia.org/wiki/Base58) dump from a passed slice to decoded data.
/// decoded data.
MDBX_CXX11_CONSTEXPR size_t envisage_result_length() const noexcept { MDBX_CXX11_CONSTEXPR size_t envisage_result_length() const noexcept {
return source.length() /* могут быть все нули кодируемые один-к-одному */; return source.length() /* могут быть все нули кодируемые один-к-одному */;
} }
@ -1433,13 +1413,11 @@ struct LIBMDBX_API from_base58 {
/// \throws std::length_error if given buffer is too small. /// \throws std::length_error if given buffer is too small.
char *write_bytes(char *dest, size_t dest_size) const; char *write_bytes(char *dest, size_t dest_size) const;
/// \brief Checks whether a passed slice is empty, /// \brief Checks whether a passed slice is empty, and therefore there will be no output bytes.
/// and therefore there will be no output bytes.
bool is_empty() const noexcept { return source.empty(); } bool is_empty() const noexcept { return source.empty(); }
/// \brief Checks whether the content of a passed slice is a valid /// \brief Checks whether the content of a passed slice is a valid
/// [Base58](https://en.wikipedia.org/wiki/Base58) dump, and therefore there /// [Base58](https://en.wikipedia.org/wiki/Base58) dump, and therefore there could be decoded or not.
/// could be decoded or not.
bool is_erroneous() const noexcept; bool is_erroneous() const noexcept;
}; };
@ -1468,8 +1446,7 @@ struct LIBMDBX_API from_base64 {
} }
/// \brief Returns the number of bytes needed for conversion /// \brief Returns the number of bytes needed for conversion
/// [Base64](https://en.wikipedia.org/wiki/Base64) dump from a passed slice to /// [Base64](https://en.wikipedia.org/wiki/Base64) dump from a passed slice to decoded data.
/// decoded data.
MDBX_CXX11_CONSTEXPR size_t envisage_result_length() const noexcept { return (source.length() + 3) / 4 * 3; } MDBX_CXX11_CONSTEXPR size_t envisage_result_length() const noexcept { return (source.length() + 3) / 4 * 3; }
/// \brief Fills the destination with data decoded from /// \brief Fills the destination with data decoded from
@ -1936,8 +1913,7 @@ public:
/// the buffer, rather than stores it. /// the buffer, rather than stores it.
MDBX_NOTHROW_PURE_FUNCTION MDBX_CXX20_CONSTEXPR bool is_reference() const noexcept { return !is_freestanding(); } MDBX_NOTHROW_PURE_FUNCTION MDBX_CXX20_CONSTEXPR bool is_reference() const noexcept { return !is_freestanding(); }
/// \brief Returns the number of bytes that can be held in currently allocated /// \brief Returns the number of bytes that can be held in currently allocated storage.
/// storage.
MDBX_NOTHROW_PURE_FUNCTION MDBX_CXX20_CONSTEXPR size_t capacity() const noexcept { MDBX_NOTHROW_PURE_FUNCTION MDBX_CXX20_CONSTEXPR size_t capacity() const noexcept {
return is_freestanding() ? silo_.capacity() : 0; return is_freestanding() ? silo_.capacity() : 0;
} }
@ -1961,16 +1937,14 @@ public:
MDBX_CXX11_CONSTEXPR const byte *end_byte_ptr() const noexcept { return slice_.end_byte_ptr(); } MDBX_CXX11_CONSTEXPR const byte *end_byte_ptr() const noexcept { return slice_.end_byte_ptr(); }
/// \brief Returns casted to pointer to byte an address of data. /// \brief Returns casted to pointer to byte an address of data.
/// \pre REQUIRES: The buffer should store data chunk, but not referenced to /// \pre REQUIRES: The buffer should store data chunk, but not referenced to an external one.
/// an external one.
MDBX_CXX11_CONSTEXPR byte *byte_ptr() noexcept { MDBX_CXX11_CONSTEXPR byte *byte_ptr() noexcept {
MDBX_CONSTEXPR_ASSERT(is_freestanding()); MDBX_CONSTEXPR_ASSERT(is_freestanding());
return const_cast<byte *>(slice_.byte_ptr()); return const_cast<byte *>(slice_.byte_ptr());
} }
/// \brief Returns casted to pointer to byte an end of data. /// \brief Returns casted to pointer to byte an end of data.
/// \pre REQUIRES: The buffer should store data chunk, but not referenced to /// \pre REQUIRES: The buffer should store data chunk, but not referenced to an external one.
/// an external one.
MDBX_CXX11_CONSTEXPR byte *end_byte_ptr() noexcept { MDBX_CXX11_CONSTEXPR byte *end_byte_ptr() noexcept {
MDBX_CONSTEXPR_ASSERT(is_freestanding()); MDBX_CONSTEXPR_ASSERT(is_freestanding());
return const_cast<byte *>(slice_.end_byte_ptr()); return const_cast<byte *>(slice_.end_byte_ptr());
@ -1983,16 +1957,14 @@ public:
MDBX_CXX11_CONSTEXPR const char *end_char_ptr() const noexcept { return slice_.end_char_ptr(); } MDBX_CXX11_CONSTEXPR const char *end_char_ptr() const noexcept { return slice_.end_char_ptr(); }
/// \brief Returns casted to pointer to char an address of data. /// \brief Returns casted to pointer to char an address of data.
/// \pre REQUIRES: The buffer should store data chunk, but not referenced to /// \pre REQUIRES: The buffer should store data chunk, but not referenced to an external one.
/// an external one.
MDBX_CXX11_CONSTEXPR char *char_ptr() noexcept { MDBX_CXX11_CONSTEXPR char *char_ptr() noexcept {
MDBX_CONSTEXPR_ASSERT(is_freestanding()); MDBX_CONSTEXPR_ASSERT(is_freestanding());
return const_cast<char *>(slice_.char_ptr()); return const_cast<char *>(slice_.char_ptr());
} }
/// \brief Returns casted to pointer to char an end of data. /// \brief Returns casted to pointer to char an end of data.
/// \pre REQUIRES: The buffer should store data chunk, but not referenced to /// \pre REQUIRES: The buffer should store data chunk, but not referenced to an external one.
/// an external one.
MDBX_CXX11_CONSTEXPR char *end_char_ptr() noexcept { MDBX_CXX11_CONSTEXPR char *end_char_ptr() noexcept {
MDBX_CONSTEXPR_ASSERT(is_freestanding()); MDBX_CONSTEXPR_ASSERT(is_freestanding());
return const_cast<char *>(slice_.end_char_ptr()); return const_cast<char *>(slice_.end_char_ptr());
@ -2005,16 +1977,14 @@ public:
MDBX_CXX11_CONSTEXPR const void *end() const noexcept { return slice_.end(); } MDBX_CXX11_CONSTEXPR const void *end() const noexcept { return slice_.end(); }
/// \brief Return a pointer to the beginning of the referenced data. /// \brief Return a pointer to the beginning of the referenced data.
/// \pre REQUIRES: The buffer should store data chunk, but not referenced to /// \pre REQUIRES: The buffer should store data chunk, but not referenced to an external one.
/// an external one.
MDBX_CXX11_CONSTEXPR void *data() noexcept { MDBX_CXX11_CONSTEXPR void *data() noexcept {
MDBX_CONSTEXPR_ASSERT(is_freestanding()); MDBX_CONSTEXPR_ASSERT(is_freestanding());
return const_cast<void *>(slice_.data()); return const_cast<void *>(slice_.data());
} }
/// \brief Return a pointer to the end of the referenced data. /// \brief Return a pointer to the end of the referenced data.
/// \pre REQUIRES: The buffer should store data chunk, but not referenced to /// \pre REQUIRES: The buffer should store data chunk, but not referenced to an external one.
/// an external one.
MDBX_CXX11_CONSTEXPR void *end() noexcept { MDBX_CXX11_CONSTEXPR void *end() noexcept {
MDBX_CONSTEXPR_ASSERT(is_freestanding()); MDBX_CONSTEXPR_ASSERT(is_freestanding());
return const_cast<void *>(slice_.end()); return const_cast<void *>(slice_.end());
@ -2744,8 +2714,7 @@ MDBX_EXTERN_API_TEMPLATE(LIBMDBX_API_TYPE, buffer<legacy_allocator>);
MDBX_EXTERN_API_TEMPLATE(LIBMDBX_API_TYPE, buffer<polymorphic_allocator>); MDBX_EXTERN_API_TEMPLATE(LIBMDBX_API_TYPE, buffer<polymorphic_allocator>);
#endif /* __cpp_lib_memory_resource >= 201603L */ #endif /* __cpp_lib_memory_resource >= 201603L */
/// \brief Combines data slice with boolean flag to represent result of certain /// \brief Combines data slice with boolean flag to represent result of certain operations.
/// operations.
struct value_result { struct value_result {
slice value; slice value;
bool done; bool done;
@ -2758,8 +2727,7 @@ struct value_result {
} }
}; };
/// \brief Combines pair of slices for key and value to represent result of /// \brief Combines pair of slices for key and value to represent result of certain operations.
/// certain operations.
struct pair { struct pair {
using stl_pair = std::pair<slice, slice>; using stl_pair = std::pair<slice, slice>;
slice key, value; slice key, value;
@ -2919,8 +2887,7 @@ MDBX_CXX01_CONSTEXPR_ENUM bool is_reverse(key_mode mode) noexcept {
MDBX_CXX01_CONSTEXPR_ENUM bool is_msgpack(key_mode mode) noexcept { return mode == key_mode::msgpack; } MDBX_CXX01_CONSTEXPR_ENUM bool is_msgpack(key_mode mode) noexcept { return mode == key_mode::msgpack; }
/// \brief Kind of the values and sorted multi-values with corresponding /// \brief Kind of the values and sorted multi-values with corresponding comparison.
/// comparison.
enum class value_mode { enum class value_mode {
single = MDBX_DB_DEFAULTS, ///< Usual single value for each key. In terms of single = MDBX_DB_DEFAULTS, ///< Usual single value for each key. In terms of
///< keys, they are unique. ///< keys, they are unique.
@ -3000,8 +2967,7 @@ MDBX_CXX01_CONSTEXPR_ENUM bool is_reverse(value_mode mode) noexcept {
MDBX_CXX01_CONSTEXPR_ENUM bool is_msgpack(value_mode mode) noexcept { return mode == value_mode::msgpack; } MDBX_CXX01_CONSTEXPR_ENUM bool is_msgpack(value_mode mode) noexcept { return mode == value_mode::msgpack; }
/// \brief A handle for an individual table (aka key-value space, maps or /// \brief A handle for an individual table (aka key-value space, maps or sub-database) in the environment.
/// sub-database) in the environment.
/// \see txn::open_map() \see txn::create_map() /// \see txn::open_map() \see txn::create_map()
/// \see txn::clear_map() \see txn::drop_map() /// \see txn::clear_map() \see txn::drop_map()
/// \see txn::get_handle_info() \see txn::get_map_stat() /// \see txn::get_handle_info() \see txn::get_map_stat()
@ -3130,12 +3096,10 @@ public:
/// environment). /// environment).
intptr_t size_upper{default_value}; intptr_t size_upper{default_value};
/// \brief The growth step in bytes, must be greater than zero to allow the /// \brief The growth step in bytes, must be greater than zero to allow the database to grow.
/// database to grow.
intptr_t growth_step{default_value}; intptr_t growth_step{default_value};
/// \brief The shrink threshold in bytes, must be greater than zero to allow /// \brief The shrink threshold in bytes, must be greater than zero to allow the database to shrink.
/// the database to shrink.
intptr_t shrink_threshold{default_value}; intptr_t shrink_threshold{default_value};
/// \brief The database page size for new database creation /// \brief The database page size for new database creation
@ -3270,47 +3234,34 @@ public:
static inline size_t pagesize_min() noexcept; static inline size_t pagesize_min() noexcept;
/// \brief Returns the maximal database page size in bytes. /// \brief Returns the maximal database page size in bytes.
static inline size_t pagesize_max() noexcept; static inline size_t pagesize_max() noexcept;
/// \brief Returns the minimal database size in bytes for specified page /// \brief Returns the minimal database size in bytes for specified page size.
/// size.
static inline size_t dbsize_min(intptr_t pagesize); static inline size_t dbsize_min(intptr_t pagesize);
/// \brief Returns the maximal database size in bytes for specified page /// \brief Returns the maximal database size in bytes for specified page size.
/// size.
static inline size_t dbsize_max(intptr_t pagesize); static inline size_t dbsize_max(intptr_t pagesize);
/// \brief Returns the minimal key size in bytes for specified table /// \brief Returns the minimal key size in bytes for specified table flags.
/// flags.
static inline size_t key_min(MDBX_db_flags_t flags) noexcept; static inline size_t key_min(MDBX_db_flags_t flags) noexcept;
/// \brief Returns the minimal key size in bytes for specified keys mode. /// \brief Returns the minimal key size in bytes for specified keys mode.
static inline size_t key_min(key_mode mode) noexcept; static inline size_t key_min(key_mode mode) noexcept;
/// \brief Returns the maximal key size in bytes for specified page size and /// \brief Returns the maximal key size in bytes for specified page size and table flags.
/// table flags.
static inline size_t key_max(intptr_t pagesize, MDBX_db_flags_t flags); static inline size_t key_max(intptr_t pagesize, MDBX_db_flags_t flags);
/// \brief Returns the maximal key size in bytes for specified page size and /// \brief Returns the maximal key size in bytes for specified page size and keys mode.
/// keys mode.
static inline size_t key_max(intptr_t pagesize, key_mode mode); static inline size_t key_max(intptr_t pagesize, key_mode mode);
/// \brief Returns the maximal key size in bytes for given environment and /// \brief Returns the maximal key size in bytes for given environment and table flags.
/// table flags.
static inline size_t key_max(const env &, MDBX_db_flags_t flags); static inline size_t key_max(const env &, MDBX_db_flags_t flags);
/// \brief Returns the maximal key size in bytes for given environment and /// \brief Returns the maximal key size in bytes for given environment and keys mode.
/// keys mode.
static inline size_t key_max(const env &, key_mode mode); static inline size_t key_max(const env &, key_mode mode);
/// \brief Returns the minimal values size in bytes for specified table /// \brief Returns the minimal values size in bytes for specified table flags.
/// flags.
static inline size_t value_min(MDBX_db_flags_t flags) noexcept; static inline size_t value_min(MDBX_db_flags_t flags) noexcept;
/// \brief Returns the minimal values size in bytes for specified values /// \brief Returns the minimal values size in bytes for specified values mode.
/// mode.
static inline size_t value_min(value_mode) noexcept; static inline size_t value_min(value_mode) noexcept;
/// \brief Returns the maximal value size in bytes for specified page size /// \brief Returns the maximal value size in bytes for specified page size and table flags.
/// and table flags.
static inline size_t value_max(intptr_t pagesize, MDBX_db_flags_t flags); static inline size_t value_max(intptr_t pagesize, MDBX_db_flags_t flags);
/// \brief Returns the maximal value size in bytes for specified page size /// \brief Returns the maximal value size in bytes for specified page size and values mode.
/// and values mode.
static inline size_t value_max(intptr_t pagesize, value_mode); static inline size_t value_max(intptr_t pagesize, value_mode);
/// \brief Returns the maximal value size in bytes for given environment and /// \brief Returns the maximal value size in bytes for given environment and table flags.
/// table flags.
static inline size_t value_max(const env &, MDBX_db_flags_t flags); static inline size_t value_max(const env &, MDBX_db_flags_t flags);
/// \brief Returns the maximal value size in bytes for specified page size /// \brief Returns the maximal value size in bytes for specified page size and values mode.
/// and values mode.
static inline size_t value_max(const env &, value_mode); static inline size_t value_max(const env &, value_mode);
/// \brief Returns maximal size of key-value pair to fit in a single page /// \brief Returns maximal size of key-value pair to fit in a single page
@ -3390,13 +3341,11 @@ public:
/// \brief Make sure that the environment is not being used by other /// \brief Make sure that the environment is not being used by other
/// processes, or return an error otherwise. /// processes, or return an error otherwise.
ensure_unused = MDBX_ENV_ENSURE_UNUSED, ensure_unused = MDBX_ENV_ENSURE_UNUSED,
/// \brief Wait until other processes closes the environment before /// \brief Wait until other processes closes the environment before deletion.
/// deletion.
wait_for_unused = MDBX_ENV_WAIT_FOR_UNUSED wait_for_unused = MDBX_ENV_WAIT_FOR_UNUSED
}; };
/// \brief Removes the environment's files in a proper and multiprocess-safe /// \brief Removes the environment's files in a proper and multiprocess-safe way.
/// way.
#ifdef MDBX_STD_FILESYSTEM_PATH #ifdef MDBX_STD_FILESYSTEM_PATH
static bool remove(const MDBX_STD_FILESYSTEM_PATH &pathname, const remove_mode mode = just_remove); static bool remove(const MDBX_STD_FILESYSTEM_PATH &pathname, const remove_mode mode = just_remove);
#endif /* MDBX_STD_FILESYSTEM_PATH */ #endif /* MDBX_STD_FILESYSTEM_PATH */
@ -3422,12 +3371,10 @@ public:
/// \brief Return snapshot information about the MDBX environment. /// \brief Return snapshot information about the MDBX environment.
inline info get_info() const; inline info get_info() const;
/// \brief Return statistics about the MDBX environment accordingly to the /// \brief Return statistics about the MDBX environment accordingly to the specified transaction.
/// specified transaction.
inline stat get_stat(const txn &) const; inline stat get_stat(const txn &) const;
/// \brief Return information about the MDBX environment accordingly to the /// \brief Return information about the MDBX environment accordingly to the specified transaction.
/// specified transaction.
inline info get_info(const txn &) const; inline info get_info(const txn &) const;
/// \brief Returns the file descriptor for the DXB file of MDBX environment. /// \brief Returns the file descriptor for the DXB file of MDBX environment.
@ -3439,8 +3386,7 @@ public:
/// Returns environment flags. /// Returns environment flags.
inline MDBX_env_flags_t get_flags() const; inline MDBX_env_flags_t get_flags() const;
/// \brief Returns the maximum number of threads/reader slots for the /// \brief Returns the maximum number of threads/reader slots for the environment.
/// environment.
/// \see extra_runtime_option::max_readers /// \see extra_runtime_option::max_readers
inline unsigned max_readers() const; inline unsigned max_readers() const;
@ -3824,8 +3770,7 @@ public:
/// volume of dirty pages) in bytes. /// volume of dirty pages) in bytes.
size_t size_max() const { return env().transaction_size_max(); } size_t size_max() const { return env().transaction_size_max(); }
/// \brief Returns current write transaction size (i.e.summary volume of dirty /// \brief Returns current write transaction size (i.e.summary volume of dirty pages) in bytes.
/// pages) in bytes.
size_t size_current() const { size_t size_current() const {
assert(is_readwrite()); assert(is_readwrite());
return size_t(get_info().txn_space_dirty); return size_t(get_info().txn_space_dirty);
@ -3984,42 +3929,32 @@ public:
inline map_handle::info get_handle_info(map_handle map) const; inline map_handle::info get_handle_info(map_handle map) const;
using canary = ::MDBX_canary; using canary = ::MDBX_canary;
/// \brief Set integers markers (aka "canary") associated with the /// \brief Set integers markers (aka "canary") associated with the environment.
/// environment.
inline txn &put_canary(const canary &); inline txn &put_canary(const canary &);
/// \brief Returns fours integers markers (aka "canary") associated with the /// \brief Returns fours integers markers (aka "canary") associated with the environment.
/// environment.
inline canary get_canary() const; inline canary get_canary() const;
/// Reads sequence generator associated with a key-value map (aka /// Reads sequence generator associated with a key-value map (aka table).
/// table).
inline uint64_t sequence(map_handle map) const; inline uint64_t sequence(map_handle map) const;
/// \brief Reads and increment sequence generator associated with a key-value /// \brief Reads and increment sequence generator associated with a key-value map (aka table).
/// map (aka table).
inline uint64_t sequence(map_handle map, uint64_t increment); inline uint64_t sequence(map_handle map, uint64_t increment);
/// \brief Compare two keys according to a particular key-value map (aka /// \brief Compare two keys according to a particular key-value map (aka table).
/// table).
inline int compare_keys(map_handle map, const slice &a, const slice &b) const noexcept; inline int compare_keys(map_handle map, const slice &a, const slice &b) const noexcept;
/// \brief Compare two values according to a particular key-value map (aka /// \brief Compare two values according to a particular key-value map (aka table).
/// table).
inline int compare_values(map_handle map, const slice &a, const slice &b) const noexcept; inline int compare_values(map_handle map, const slice &a, const slice &b) const noexcept;
/// \brief Compare keys of two pairs according to a particular key-value map /// \brief Compare keys of two pairs according to a particular key-value map (aka table).
/// (aka table).
inline int compare_keys(map_handle map, const pair &a, const pair &b) const noexcept; inline int compare_keys(map_handle map, const pair &a, const pair &b) const noexcept;
/// \brief Compare values of two pairs according to a particular key-value map /// \brief Compare values of two pairs according to a particular key-value map(aka table).
/// (aka table).
inline int compare_values(map_handle map, const pair &a, const pair &b) const noexcept; inline int compare_values(map_handle map, const pair &a, const pair &b) const noexcept;
/// \brief Get value by key from a key-value map (aka table). /// \brief Get value by key from a key-value map (aka table).
inline slice get(map_handle map, const slice &key) const; inline slice get(map_handle map, const slice &key) const;
/// \brief Get first of multi-value and values count by key from a key-value /// \brief Get first of multi-value and values count by key from a key-value multimap (aka table).
/// multimap (aka table).
inline slice get(map_handle map, slice key, size_t &values_count) const; inline slice get(map_handle map, slice key, size_t &values_count) const;
/// \brief Get value by key from a key-value map (aka table). /// \brief Get value by key from a key-value map (aka table).
inline slice get(map_handle map, const slice &key, const slice &value_at_absence) const; inline slice get(map_handle map, const slice &key, const slice &value_at_absence) const;
/// \brief Get first of multi-value and values count by key from a key-value /// \brief Get first of multi-value and values count by key from a key-value multimap (aka table).
/// multimap (aka table).
inline slice get(map_handle map, slice key, size_t &values_count, const slice &value_at_absence) const; inline slice get(map_handle map, slice key, size_t &values_count, const slice &value_at_absence) const;
/// \brief Get value for equal or great key from a table. /// \brief Get value for equal or great key from a table.
/// \return Bundle of key-value pair and boolean flag, /// \return Bundle of key-value pair and boolean flag,
@ -4518,12 +4453,10 @@ public:
//---------------------------------------------------------------------------- //----------------------------------------------------------------------------
/// \brief Renew/bind a cursor with a new transaction and previously used /// \brief Renew/bind a cursor with a new transaction and previously used key-value map handle.
/// key-value map handle.
inline void renew(::mdbx::txn &txn); inline void renew(::mdbx::txn &txn);
/// \brief Bind/renew a cursor with a new transaction and specified key-value /// \brief Bind/renew a cursor with a new transaction and specified key-value map handle.
/// map handle.
inline void bind(::mdbx::txn &txn, ::mdbx::map_handle map_handle); inline void bind(::mdbx::txn &txn, ::mdbx::map_handle map_handle);
/// \brief Unbind cursor from a transaction. /// \brief Unbind cursor from a transaction.
@ -4556,12 +4489,10 @@ public:
value_result try_insert(const pair &kv) { return try_insert(kv.key, kv.value); } value_result try_insert(const pair &kv) { return try_insert(kv.key, kv.value); }
void upsert(const pair &kv) { return upsert(kv.key, kv.value); } void upsert(const pair &kv) { return upsert(kv.key, kv.value); }
/// \brief Removes single key-value pair or all multi-values at the current /// \brief Removes single key-value pair or all multi-values at the current cursor position.
/// cursor position.
inline bool erase(bool whole_multivalue = false); inline bool erase(bool whole_multivalue = false);
/// \brief Seeks and removes first value or whole multi-value of the given /// \brief Seeks and removes first value or whole multi-value of the given key.
/// key.
/// \return `True` if the key is found and a value(s) is removed. /// \return `True` if the key is found and a value(s) is removed.
inline bool erase(const slice &key, bool whole_multivalue = true); inline bool erase(const slice &key, bool whole_multivalue = true);