From a902538e34bbe316ef0b443b29408642b2391bf3 Mon Sep 17 00:00:00 2001 From: Leonid Yuriev Date: Thu, 23 Jul 2020 19:24:21 +0300 Subject: [PATCH] mdbx: more Doxygen tags (almost done). Change-Id: I696e717e37a905f68af059c51f9df327c257332e --- GNUmakefile | 4 +- README.md | 6 +- docs/Doxyfile.in | 2 +- docs/_toc.md | 5 +- mdbx.h | 2914 ++++++++++++++++++++++++---------------------- src/core.c | 8 +- src/internals.h | 4 +- src/mdbx_dump.c | 2 +- src/mdbx_load.c | 2 +- test/test.cc | 4 +- test/test.h | 2 +- 11 files changed, 1567 insertions(+), 1386 deletions(-) diff --git a/GNUmakefile b/GNUmakefile index b51f5bbf..95bdb69f 100644 --- a/GNUmakefile +++ b/GNUmakefile @@ -270,8 +270,8 @@ docs/intro.md: docs/_preface.md docs/__characteristics.md docs/__improvements.md docs/usage.md: docs/__usage.md docs/_starting.md docs/__bindings.md echo -e "\\page usage Usage\n\\section getting Getting the libmdbx" | cat - $? | sed 's/^Bindings$$/Bindings {#bindings}/' > $@ -doxygen: docs/Doxyfile docs/overall.md docs/intro.md docs/usage.md mdbx.h ChangeLog.md - rm -rf docs/html && cp mdbx.h ChangeLog.md docs/ && (cd docs && doxygen Doxyfile) +doxygen: docs/Doxyfile docs/overall.md docs/intro.md docs/usage.md mdbx.h ChangeLog.md AUTHORS LICENSE + rm -rf docs/html && cp mdbx.h ChangeLog.md docs/ && (cd docs && doxygen Doxyfile) && cp AUTHORS LICENSE docs/html/ .PHONY: dist release-assets dist: libmdbx-sources-$(MDBX_VERSION_SUFFIX).tar.gz $(lastword $(MAKEFILE_LIST)) diff --git a/README.md b/README.md index 4a2e9571..84e530c0 100644 --- a/README.md +++ b/README.md @@ -460,9 +460,9 @@ from the [ios-cmake](https://github.com/leetal/ios-cmake) project. ## API description -For more information and API description see the [mdbx.h](mdbx.h) header. -Please do not hesitate to point out errors in the documentation, -including creating [PR](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests) with corrections and improvements. + +Please refer to the online [_libmdbx_ API reference](https://erthink.github.io/libmdbx/) +and/or see the [mdbx.h](mdbx.h) header. diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index ebd23547..0b936376 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -1558,7 +1558,7 @@ FORMULA_MACROFILE = # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -USE_MATHJAX = NO +USE_MATHJAX = YES # When MathJax is enabled you can set the default output format to be used for # the MathJax output. See the MathJax site (see: diff --git a/docs/_toc.md b/docs/_toc.md index 23883232..60e7748b 100644 --- a/docs/_toc.md +++ b/docs/_toc.md @@ -34,8 +34,9 @@ each of which is divided into several sections. - Cleaning up - \ref bindings -3. The `C` API reference manual: - - TODO +3. The `C` API manual: + - The \ref c_api reference + - The \ref mdbx.h header file reference Please do not hesitate to point out errors in the documentation, including creating [PR](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests) with corrections and improvements. diff --git a/mdbx.h b/mdbx.h index 16ebee65..658e4ca5 100644 --- a/mdbx.h +++ b/mdbx.h @@ -112,9 +112,8 @@ typedef pthread_t mdbx_tid_t; #pragma warning(pop) #endif -/** - \defgroup api_macros Common Macros - @{ */ +/** \defgroup api_macros Common Macros + * @{ */ /*----------------------------------------------------------------------------*/ @@ -255,10 +254,9 @@ typedef pthread_t mdbx_tid_t; #endif #endif /* LIBMDBX_API */ -/** - @} The end of Common Macros - \defgroup c_api C API - @{ */ +/** @} The end of Common Macros + * \defgroup c_api C API + * @{ */ #ifdef __cplusplus extern "C" { @@ -286,8 +284,8 @@ extern LIBMDBX_VERINFO_API const struct MDBX_version_info { } mdbx_version; /** MDBX build information - \attention Some strings could be NULL in case no corresponding information was - provided at build time (i.e. flags). */ + * \attention Some strings could be NULL in case no corresponding information + * was provided at build time (i.e. flags). */ extern LIBMDBX_VERINFO_API const struct MDBX_build_info { const char *datetime; /**< build timestamp (ISO-8601 or __DATE__ __TIME__) */ const char *target; /**< cpu/arch-system-config triplet */ @@ -343,11 +341,11 @@ void LIBMDBX_API NTAPI mdbx_dll_handler(PVOID module, DWORD reason, #endif /* !MDBX_BUILD_SHARED_LIBRARY */ #endif /* Windows */ -/**** OPACITY STRUCTURES ******************************************************/ +/* OPACITY STRUCTURES *********************************************************/ /** Opaque structure for a database environment. - \details An environment supports multiple key-value databases (aka key-value - spaces or tables), all residing in the same shared-memory map. */ + * \details An environment supports multiple key-value databases (aka key-value + * spaces or tables), all residing in the same shared-memory map. */ #ifndef __cplusplus typedef struct MDBX_env MDBX_env; #else @@ -355,8 +353,8 @@ struct MDBX_env; #endif /** Opaque structure for a transaction handle. - \details All database operations require a transaction handle. Transactions - may be read-only or read-write. */ + * \details All database operations require a transaction handle. Transactions + * may be read-only or read-write. */ #ifndef __cplusplus typedef struct MDBX_txn MDBX_txn; #else @@ -378,7 +376,7 @@ struct MDBX_cursor; /** Generic structure used for passing keys and data in and out of the database. * - * Values returned from the database are valid only until a subsequent + * \details Values returned from the database are valid only until a subsequent * update operation, or the end of the transaction. Do not modify or * free them, they commonly point into the database itself. * @@ -390,8 +388,8 @@ struct MDBX_cursor; * length keys. */ #ifndef HAVE_STRUCT_IOVEC struct iovec { - void *iov_base /* pointer to some data */; - size_t iov_len /* the length of data in bytes */; + void *iov_base; /**< pointer to some data */ + size_t iov_len; /**< the length of data in bytes */ }; #define HAVE_STRUCT_IOVEC #endif /* HAVE_STRUCT_IOVEC */ @@ -400,8 +398,8 @@ struct iovec { /* The `iov_len` is signed on Sun/Solaris. * So define custom MDBX_val to avoid a lot of warings. */ struct MDBX_val { - void *iov_base /* pointer to some data */; - size_t iov_len /* the length of data in bytes */; + void *iov_base; /**< pointer to some data */ + size_t iov_len; /**< the length of data in bytes */ }; #ifndef __cplusplus typedef struct MDBX_val MDBX_val; @@ -412,11 +410,11 @@ typedef struct iovec MDBX_val; enum MDBX_constants { /** The hard limit for DBI handles */ - MDBX_MAX_DBI = UINT32_C(32765), - /** The maximum size of a data item. */ + /** The maximum size of a data item. */ MDBX_MAXDATASIZE = UINT32_C(0x7fff0000), + /** The minimal database page size in bytes. */ MDBX_MIN_PAGESIZE = 256, @@ -424,23 +422,33 @@ enum MDBX_constants { MDBX_MAX_PAGESIZE = 65536, }; -/**** DEBUG & LOGGING ********************************************************** - * Logging and runtime debug flags. - * - * NOTE: Most of debug feature enabled only when libmdbx builded with - * MDBX_DEBUG options. - */ +/* THE FILES ******************************************************************* + * At the file system level, the environment corresponds to a pair of files. */ -/** Log level (requires build libmdbx with MDBX_DEBUG) */ +/** The name of the lock file in the environment */ +#define MDBX_LOCKNAME "/mdbx.lck" +/** The name of the data file in the environment */ +#define MDBX_DATANAME "/mdbx.dat" + +/** The suffix of the lock file when MDBX_NOSUBDIR is used */ +#define MDBX_LOCK_SUFFIX "-lck" + +/* DEBUG & LOGGING ************************************************************/ + +/** \defgroup log_and_debug Logging and runtime debug + * \note Most of debug feature enabled only when libmdbx builded with + * `MDBX_DEBUG` option. @{ */ + +/** Log level (requires build libmdbx with `MDBX_DEBUG` option) */ enum MDBX_log_level_t { - MDBX_LOG_FATAL = 0 /** critical conditions, i.e. assertion failures */, - MDBX_LOG_ERROR = 1 /** error conditions */, - MDBX_LOG_WARN = 2 /** warning conditions */, - MDBX_LOG_NOTICE = 3 /** normal but significant condition */, - MDBX_LOG_VERBOSE = 4 /** verbose informational */, - MDBX_LOG_DEBUG = 5 /** debug-level messages */, - MDBX_LOG_TRACE = 6 /** trace debug-level messages */, - MDBX_LOG_EXTRA = 7 /** extra debug-level messages (dump pgno lists) */, + MDBX_LOG_FATAL = 0, /**< critical conditions, i.e. assertion failures */ + MDBX_LOG_ERROR = 1, /**< error conditions */ + MDBX_LOG_WARN = 2, /**< warning conditions */ + MDBX_LOG_NOTICE = 3, /**< normal but significant condition */ + MDBX_LOG_VERBOSE = 4, /**< verbose informational */ + MDBX_LOG_DEBUG = 5, /**< debug-level messages */ + MDBX_LOG_TRACE = 6, /**< trace debug-level messages */ + MDBX_LOG_EXTRA = 7, /**< extra debug-level messages (dump pgno lists) */ /** for mdbx_setup_debug() only: Don't change current settings */ MDBX_LOG_DONTCHANGE = -1 @@ -449,22 +457,20 @@ enum MDBX_log_level_t { typedef enum MDBX_log_level_t MDBX_log_level_t; #endif -/** Runtime debug flags. +/** Runtime debug flags * * \details MDBX_DBG_DUMP and MDBX_DBG_LEGACY_MULTIOPEN always have an effect, * but MDBX_DBG_ASSERT, MDBX_DBG_AUDIT and MDBX_DBG_JITTER only if libmdbx * builded with MDBX_DEBUG. */ enum MDBX_debug_flags_t { - MDBX_DBG_ASSERT = 1 /** Enable assertion checks */, - MDBX_DBG_AUDIT = 2 /** Enable pages usage audit at commit transactions */, - MDBX_DBG_JITTER = 4 /** Enable small random delays in critical points */, - MDBX_DBG_DUMP = 8 /** Include or not meta-pages in coredump files, - MAY affect performance in MDBX_WRITEMAP mode */ - , - MDBX_DBG_LEGACY_MULTIOPEN = 16 /** Allow multi-opening environment(s) */, - MDBX_DBG_LEGACY_OVERLAP = 32 /** Allow read and write transactions overlapping - for the same thread */ - , + MDBX_DBG_ASSERT = 1, /**< Enable assertion checks */ + MDBX_DBG_AUDIT = 2, /**< Enable pages usage audit at commit transactions */ + MDBX_DBG_JITTER = 4, /**< Enable small random delays in critical points */ + MDBX_DBG_DUMP = 8, /**< Include or not meta-pages in coredump files, + MAY affect performance in MDBX_WRITEMAP mode */ + MDBX_DBG_LEGACY_MULTIOPEN = 16, /**< Allow multi-opening environment(s) */ + MDBX_DBG_LEGACY_OVERLAP = 32, /**< Allow read and write transactions + overlapping for the same thread */ /** for mdbx_setup_debug() only: Don't change current settings */ MDBX_DBG_DONTCHANGE = -1 @@ -478,183 +484,178 @@ DEFINE_ENUM_FLAG_OPERATORS(MDBX_debug_flags_t) /** A debug-logger callback function, * called before printing the message and aborting. * - * [in] env An environment handle returned by mdbx_env_create(). - * [in] msg The assertion message, not including newline. */ + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [in] msg The assertion message, not including newline. */ typedef void MDBX_debug_func(MDBX_log_level_t loglevel, const char *function, int line, const char *msg, va_list args); +/** The "don't change `logger`" value for mdbx_setup_debug() */ #define MDBX_LOGGER_DONTCHANGE ((MDBX_debug_func *)(intptr_t)-1) -/* Setup global log-level, debug options and debug logger. */ -LIBMDBX_API int mdbx_setup_debug(MDBX_log_level_t loglevel, - MDBX_debug_flags_t flags, +/** Setup global log-level, debug options and debug logger. + * \returns The previously `debug_flags` in the 0-15 bits + * and `log_level` in the 16-31 bits. */ +LIBMDBX_API int mdbx_setup_debug(MDBX_log_level_t log_level, + MDBX_debug_flags_t debug_flags, MDBX_debug_func *logger); /** A callback function for most MDBX assert() failures, * called before printing the message and aborting. * - * [in] env An environment handle returned by mdbx_env_create(). - * [in] msg The assertion message, not including newline. */ + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [in] msg The assertion message, not including newline. */ typedef void MDBX_assert_func(const MDBX_env *env, const char *msg, const char *function, unsigned line); /** Set or reset the assert() callback of the environment. * * Does nothing if libmdbx was built with MDBX_DEBUG=0 or with NDEBUG, - * and will return MDBX_ENOSYS in such case. + * and will return `MDBX_ENOSYS` in such case. * - * [in] env An environment handle returned by mdbx_env_create(). - * [in] func An MDBX_assert_func function, or 0. + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [in] func An MDBX_assert_func function, or 0. * - * Returns A non-zero error value on failure and 0 on success. */ + * \returns A non-zero error value on failure and 0 on success. */ LIBMDBX_API int mdbx_env_set_assert(MDBX_env *env, MDBX_assert_func *func); -/* FIXME: Complete description */ +/** Dump given MDBX_val to the buffer */ LIBMDBX_API const char *mdbx_dump_val(const MDBX_val *key, char *const buf, const size_t bufsize); -/**** THE FILES **************************************************************** - * At the file system level, the environment corresponds to a pair of files. */ +/** @} The end of logging & debug */ -/** The name of the lock file in the environment */ -#define MDBX_LOCKNAME "/mdbx.lck" -/** The name of the data file in the environment */ -#define MDBX_DATANAME "/mdbx.dat" - -/** The suffix of the lock file when MDBX_NOSUBDIR is used */ -#define MDBX_LOCK_SUFFIX "-lck" - -/** ENVIRONMENT FLAGS *********************************************************/ +/** ENVIRONMENT FLAGS \anchor env_flags */ enum MDBX_env_flags_t { MDBX_ENV_DEFAULTS = 0, - /** MDBX_NOSUBDIR = no environment directory. + /** No environment directory. * * By default, MDBX creates its environment in a directory whose pathname is * given in path, and creates its data and lock files under that directory. * With this option, path is used as-is for the database main data file. * The database lock file is the path with "-lck" appended. * - * - with MDBX_NOSUBDIR = in a filesystem we have the pair of MDBX-files - * which names derived from given pathname by appending predefined suffixes. + * - with MDBX_NOSUBDIR = in a filesystem we have the pair of MDBX-files + * which names derived from given pathname by appending predefined suffixes. * - * - without MDBX_NOSUBDIR = in a filesystem we have the MDBX-directory with - * given pathname, within that a pair of MDBX-files with predefined names. + * - without MDBX_NOSUBDIR = in a filesystem we have the MDBX-directory with + * given pathname, within that a pair of MDBX-files with predefined names. * * This flag affects only at new environment creating by mdbx_env_open(), * otherwise at opening an existing environment libmdbx will choice this * automatically. */ MDBX_NOSUBDIR = UINT32_C(0x4000), - /** MDBX_RDONLY = read only mode. + /** Read only mode. * * Open the environment in read-only mode. No write operations will be * allowed. MDBX will still modify the lock file - except on read-only * filesystems, where MDBX does not use locks. * - * - with MDBX_RDONLY = open environment in read-only mode. - * MDBX supports pure read-only mode (i.e. without opening LCK-file) only - * when environment directory and/or both files are not writable (and the - * LCK-file may be missing). In such case allowing file(s) to be placed - * on a network read-only share. + * - with MDBX_RDONLY = open environment in read-only mode. + * MDBX supports pure read-only mode (i.e. without opening LCK-file) only + * when environment directory and/or both files are not writable (and the + * LCK-file may be missing). In such case allowing file(s) to be placed + * on a network read-only share. * - * - without MDBX_RDONLY = open environment in read-write mode. + * - without MDBX_RDONLY = open environment in read-write mode. * * This flag affects only at environment opening but can't be changed after. */ MDBX_RDONLY = UINT32_C(0x20000), - /** MDBX_EXCLUSIVE = open environment in exclusive/monopolistic mode. + /** Open environment in exclusive/monopolistic mode. * - * MDBX_EXCLUSIVE flag can be used as a replacement for MDB_NOLOCK, which - don't - * supported by MDBX. In this way, you can get the minimal overhead, but with - * the correct multi-process and mutli-thread locking. + * MDBX_EXCLUSIVE flag can be used as a replacement for MDB_NOLOCK, + * which don't supported by MDBX. + * In this way, you can get the minimal overhead, but with the correct + * multi-process and mutli-thread locking. * - * - with MDBX_EXCLUSIVE = open environment in exclusive/monopolistic mode - * or return MDBX_BUSY if environment already used by other process. - * The main feature of the exclusive mode is the ability to open the - * environment placed on a network share. + * - with MDBX_EXCLUSIVE = open environment in exclusive/monopolistic mode + * or return MDBX_BUSY if environment already used by other process. + * The main feature of the exclusive mode is the ability to open the + * environment placed on a network share. + * + * - without MDBX_EXCLUSIVE = open environment in cooperative mode, + * i.e. for multi-process access/interaction/cooperation. + * The main requirements of the cooperative mode are: + * + * 1. data files MUST be placed in the LOCAL file system, + * but NOT on a network share. + * 2. environment MUST be opened only by LOCAL processes, + * but NOT over a network. + * 3. OS kernel (i.e. file system and memory mapping implementation) and + * all processes that open the given environment MUST be running + * in the physically single RAM with cache-coherency. The only + * exception for cache-consistency requirement is Linux on MIPS + * architecture, but this case has not been tested for a long time). * - * - without MDBX_EXCLUSIVE = open environment in cooperative mode, - * i.e. for multi-process access/interaction/cooperation. - * The main requirements of the cooperative mode are: - * 1. data files MUST be placed in the LOCAL file system, - * but NOT on a network share. - * 2. environment MUST be opened only by LOCAL processes, - * but NOT over a network. - * 3. OS kernel (i.e. file system and memory mapping implementation) and - * all processes that open the given environment MUST be running - * in the physically single RAM with cache-coherency. The only - * exception for cache-consistency requirement is Linux on MIPS - * architecture, but this case has not been tested for a long time). - * This flag affects only at environment opening but can't be changed after. */ MDBX_EXCLUSIVE = UINT32_C(0x400000), - /** MDBX_ACCEDE = using database which already opened by another process(es). + /** Using database which already opened by another process(es). * * The MDBX_ACCEDE flag avoid MDBX_INCOMPATIBLE error while opening If the - * database is already used by another process(es) and environment mode/flags - * isn't compatible. In such cases, when using the MDBX_ACCEDE flag, instead - * of the specified incompatible options, the mode in which the database is - * already opened by other processes will be used, including MDBX_LIFORECLAIM, - * MDBX_COALESCE and MDBX_NORDAHEAD. The MDBX_ACCEDE flag is useful to open a - * database that already used by another process(es) and used mode/flags isn't - * known. + * database is already used by another process(es) and environment + * mode/flags isn't compatible. In such cases, when using the MDBX_ACCEDE + * flag, instead of the specified incompatible options, the mode in which + * the database is already opened by other processes will be used, including + * MDBX_LIFORECLAIM, MDBX_COALESCE and MDBX_NORDAHEAD. The MDBX_ACCEDE flag + * is useful to open a database that already used by another process(es) and + * used mode/flags isn't known. * * MDBX_ACCEDE has no effect if the current process is the only one either * opening the DB in read-only mode or other process(es) uses the DB in * read-only mode. */ MDBX_ACCEDE = UINT32_C(0x40000000), - /** MDBX_WRITEMAP = map data into memory with write permission. + /** Map data into memory with write permission. * * Use a writeable memory map unless MDBX_RDONLY is set. This uses fewer - * mallocs and requires much less work for tracking database pages, but loses - * protection from application bugs like wild pointer writes and other bad - * updates into the database. This may be slightly faster for DBs that fit - * entirely in RAM, but is slower for DBs larger than RAM. Also adds the - * possibility for stray application writes thru pointers to silently corrupt - * the database. Incompatible with nested transactions. + * mallocs and requires much less work for tracking database pages, but + * loses protection from application bugs like wild pointer writes and other + * bad updates into the database. This may be slightly faster for DBs that + * fit entirely in RAM, but is slower for DBs larger than RAM. Also adds the + * possibility for stray application writes thru pointers to silently + * corrupt the database. * - * NOTE: The MDBX_WRITEMAP mode is incompatible with nested transactions, + * - with MDBX_WRITEMAP = all data will be mapped into memory in the + * read-write mode. This offers a significant performance benefit, since the + * data will be modified directly in mapped memory and then flushed to disk + * by single system call, without any memory management nor copying. + * + * - without MDBX_WRITEMAP = data will be mapped into memory in the read-only + * mode. This requires stocking all modified database pages in memory and + * then writing them to disk through file operations. + * + * \warning On the other hand, MDBX_WRITEMAP adds the possibility for stray + * application writes thru pointers to silently corrupt the database. + + * \note The MDBX_WRITEMAP mode is incompatible with nested transactions, * since this is unreasonable. I.e. nested transactions requires mallocation * of database pages and more work for tracking ones, which neuters a - * performance boost caused by the MDBX_WRITEMAP mode. - * - * - with MDBX_WRITEMAP = all data will be mapped into memory in the - * read-write mode. This offers a significant performance benefit, since the - * data will be modified directly in mapped memory and then flushed to disk by - * single system call, without any memory management nor copying. - * \note On the other hand, MDBX_WRITEMAP adds the possibility for stray - * application writes thru pointers to silently corrupt the database. - * Moreover, MDBX_WRITEMAP disallows nested write transactions. - * - * - without MDBX_WRITEMAP = data will be mapped into memory in the read-only - * mode. This requires stocking all modified database pages in memory and - * then writing them to disk through file operations. + * performance boost caused by the MDBX_WRITEMAP mode. * * This flag affects only at environment opening but can't be changed after. */ MDBX_WRITEMAP = UINT32_C(0x80000), - /** MDBX_NOTLS = tie reader locktable slots to read-only transactions instead - * of to threads. + /** Tie reader locktable slots to read-only transactions + * instead of to threads. * * Don't use Thread-Local Storage, instead tie reader locktable slots to - * MDBX_txn objects instead of to threads. So, mdbx_txn_reset() keeps the slot - * reserved for the MDBX_txn object. A thread may use parallel read-only - * transactions. And a read-only transaction may span threads if you - * synchronizes its use. + * MDBX_txn objects instead of to threads. So, `mdbx_txn_reset()` keeps the + * slot reserved for the MDBX_txn object. A thread may use parallel + * read-only transactions. And a read-only transaction may span threads if + * you synchronizes its use. * * Applications that multiplex many user threads over individual OS threads * need this option. Such an application must also serialize the write - * transactions in an OS thread, since MDBX's write locking is unaware of the - * user threads. + * transactions in an OS thread, since MDBX's write locking is unaware of + * the user threads. * - * NOTE: Regardless to MDBX_NOTLS flag a write transaction entirely should + * \note Regardless to MDBX_NOTLS flag a write transaction entirely should * always be used in one thread from start to finish. MDBX checks this in a * reasonable manner and return the MDBX_THREAD_MISMATCH error in rules * violation. @@ -663,29 +664,28 @@ enum MDBX_env_flags_t { */ MDBX_NOTLS = UINT32_C(0x200000), - /** MDBX_NORDAHEAD = don't do readahead. + /** Don't do readahead. * * Turn off readahead. Most operating systems perform readahead on read * requests by default. This option turns it off if the OS supports it. - * Turning it off may help random read performance when the DB is larger than - * RAM and system RAM is full. + * Turning it off may help random read performance when the DB is larger + * than RAM and system RAM is full. * - * By default libmdbx dynamically enables/disables readahead depending on the - * actual database size and currently available memory. On the other hand, - * such automation has some limitation, i.e. could be performed only when DB - * size changing but can't tracks and reacts changing a free RAM availability, - * since it changes independently and asynchronously. + * By default libmdbx dynamically enables/disables readahead depending on + * the actual database size and currently available memory. On the other + * hand, such automation has some limitation, i.e. could be performed only + * when DB size changing but can't tracks and reacts changing a free RAM + * availability, since it changes independently and asynchronously. * - * NOTE: The mdbx_is_readahead_reasonable() function allows to quickly find + * \note The mdbx_is_readahead_reasonable() function allows to quickly find * out whether to use readahead or not based on the size of the data and the - * amount of available memory. + * amount of available memory. * * This flag affects only at environment opening and can't be changed after. */ MDBX_NORDAHEAD = UINT32_C(0x800000), - /** MDBX_NOMEMINIT = don't initialize malloc'd memory before writing to - * datafile. + /** Don't initialize malloc'd memory before writing to datafile. * * Don't initialize malloc'd memory before writing to unused spaces in the * data file. By default, memory for pages written to the data file is @@ -694,38 +694,38 @@ enum MDBX_env_flags_t { * use. This avoids persisting leftover data from other code (that used the * heap and subsequently freed the memory) into the data file. * - * Note that many other system libraries may allocate and free memory from the - * heap for arbitrary uses. E.g., stdio may use the heap for file I/O buffers. - * This initialization step has a modest performance cost so some applications - * may want to disable it using this flag. This option can be a problem for - * applications which handle sensitive data like passwords, and it makes - * memory checkers like Valgrind noisy. This flag is not needed with - * MDBX_WRITEMAP, which writes directly to the mmap instead of using malloc - * for pages. The initialization is also skipped if MDBX_RESERVE is used; the - * caller is expected to overwrite all of the memory that was reserved in that - * case. + * Note that many other system libraries may allocate and free memory from + * the heap for arbitrary uses. E.g., stdio may use the heap for file I/O + * buffers. This initialization step has a modest performance cost so some + * applications may want to disable it using this flag. This option can be a + * problem for applications which handle sensitive data like passwords, and + * it makes memory checkers like Valgrind noisy. This flag is not needed + * with MDBX_WRITEMAP, which writes directly to the mmap instead of using + * malloc for pages. The initialization is also skipped if MDBX_RESERVE is + * used; the caller is expected to overwrite all of the memory that was + * reserved in that case. * - * This flag may be changed at any time using mdbx_env_set_flags(). */ + * This flag may be changed at any time using `mdbx_env_set_flags()`. */ MDBX_NOMEMINIT = UINT32_C(0x1000000), - /** MDBX_COALESCE = aims to coalesce a Garbage Collection items. + /** Aims to coalesce a Garbage Collection items. * * With MDBX_COALESCE flag MDBX will aims to coalesce items while recycling - * a Garbage Collection. Technically, when possible short lists of pages will - * be combined into longer ones, but to fit on one database page. As a result, - * there will be fewer items in Garbage Collection and a page lists are - * longer, which slightly increases the likelihood of returning pages to + * a Garbage Collection. Technically, when possible short lists of pages + * will be combined into longer ones, but to fit on one database page. As a + * result, there will be fewer items in Garbage Collection and a page lists + * are longer, which slightly increases the likelihood of returning pages to * Unallocated space and reducing the database file. * * This flag may be changed at any time using mdbx_env_set_flags(). */ MDBX_COALESCE = UINT32_C(0x2000000), - /** MDBX_LIFORECLAIM = LIFO policy for recycling a Garbage Collection items. + /** LIFO policy for recycling a Garbage Collection items. * * MDBX_LIFORECLAIM flag turns on LIFO policy for recycling a Garbage * Collection items, instead of FIFO by default. On systems with a disk - * write-back cache, this can significantly increase write performance, up to - * several times in a best case scenario. + * write-back cache, this can significantly increase write performance, up + * to several times in a best case scenario. * * LIFO recycling policy means that for reuse pages will be taken which became * unused the lastest (i.e. just now or most recently). Therefore the loop of @@ -735,11 +735,12 @@ enum MDBX_env_flags_t { * ideal conditions for the efficient operation of the disk write-back cache. * * MDBX_LIFORECLAIM is compatible with all no-sync flags (i.e. - * MDBX_NOMETASYNC, MDBX_SAFE_NOSYNC, MDBX_UTTERLY_NOSYNC, MDBX_MAPASYNC), but - * gives no noticeable impact in combination with MDBX_SAFE_NOSYNC. Because - * MDBX will reused pages only before the last "steady" MVCC-snapshot, i.e. - * the loop length of database pages circulation will be mostly defined by - * frequency of calling mdbx_env_sync() rather than LIFO and FIFO difference. + * MDBX_NOMETASYNC, MDBX_SAFE_NOSYNC, MDBX_UTTERLY_NOSYNC, MDBX_MAPASYNC), + * but gives no noticeable impact in combination with MDBX_SAFE_NOSYNC. + * Because MDBX will reused pages only before the last "steady" MVCC-snapshot, + * i.e. the loop length of database pages circulation will be mostly defined + * by frequency of calling `mdbx_env_sync()` rather than LIFO and FIFO + * difference. * * This flag may be changed at any time using mdbx_env_set_flags(). */ MDBX_LIFORECLAIM = UINT32_C(0x4000000), @@ -747,207 +748,198 @@ enum MDBX_env_flags_t { /** Debugging option, fill/perturb released pages. */ MDBX_PAGEPERTURB = UINT32_C(0x8000000), - /**** SYNC MODES ************************************************************* - * (!!!) Using any combination of MDBX_SAFE_NOSYNC, MDBX_NOMETASYNC, - * MDBX_MAPASYNC and especially MDBX_UTTERLY_NOSYNC is always a deal to reduce - * durability for gain write performance. You must know exactly what you are - * doing and what risks you are taking! + /* SYNC MODES****************************************************************/ + /** \defgroup sync_modes SYNC MODES * - * NOTE for LMDB users: MDBX_SAFE_NOSYNC is NOT similar to LMDB_NOSYNC, but - * MDBX_UTTERLY_NOSYNC is exactly match LMDB_NOSYNC. - * See details below. + * \attention Using any combination of MDBX_SAFE_NOSYNC, MDBX_NOMETASYNC, + * MDBX_MAPASYNC and especially MDBX_UTTERLY_NOSYNC is always a deal to + * reduce durability for gain write performance. You must know exactly what + * you are doing and what risks you are taking! + * + * \note for LMDB users: MDBX_SAFE_NOSYNC is NOT similar to LMDB_NOSYNC, + * but MDBX_UTTERLY_NOSYNC is exactly match LMDB_NOSYNC. See details below. * * THE SCENE: - * - The DAT-file contains several MVCC-snapshots of B-tree at same time, - * each of those B-tree has its own root page. - * - Each of meta pages at the beginning of the DAT file contains a pointer - * to the root page of B-tree which is the result of the particular - * transaction, and a number of this transaction. - * - For data durability, MDBX must first write all MVCC-snapshot data pages - * and ensure that are written to the disk, then update a meta page with - * the new transaction number and a pointer to the corresponding new root - * page, and flush any buffers yet again. - * - Thus during commit a I/O buffers should be flushed to the disk twice; - * i.e. fdatasync(), FlushFileBuffers() or similar syscall should be - * called twice for each commit. This is very expensive for performance, - * but guaranteed durability even on unexpected system failure or power - * outage. Of course, provided that the operating system and the - * underlying hardware (e.g. disk) work correctly. + * - The DAT-file contains several MVCC-snapshots of B-tree at same time, + * each of those B-tree has its own root page. + * - Each of meta pages at the beginning of the DAT file contains a + * pointer to the root page of B-tree which is the result of the particular + * transaction, and a number of this transaction. + * - For data durability, MDBX must first write all MVCC-snapshot data + * pages and ensure that are written to the disk, then update a meta page + * with the new transaction number and a pointer to the corresponding new + * root page, and flush any buffers yet again. + * - Thus during commit a I/O buffers should be flushed to the disk twice; + * i.e. fdatasync(), FlushFileBuffers() or similar syscall should be + * called twice for each commit. This is very expensive for performance, + * but guaranteed durability even on unexpected system failure or power + * outage. Of course, provided that the operating system and the + * underlying hardware (e.g. disk) work correctly. * - * TRADE-OFF: By skipping some stages described above, you can significantly - * benefit in speed, while partially or completely losing in the guarantee of - * data durability and/or consistency in the event of system or power failure. + * TRADE-OFF: + * By skipping some stages described above, you can significantly benefit in + * speed, while partially or completely losing in the guarantee of data + * durability and/or consistency in the event of system or power failure. * Moreover, if for any reason disk write order is not preserved, then at * moment of a system crash, a meta-page with a pointer to the new B-tree may * be written to disk, while the itself B-tree not yet. In that case, the * database will be corrupted! * + * \see MDBX_NOMETASYNC + * \see MDBX_SAFE_NOSYNC + * \see MDBX_MAPASYNC + * \see MDBX_UTTERLY_NOSYNC * - * MDBX_NOMETASYNC = don't sync the meta-page after commit. - * - * Flush system buffers to disk only once per transaction, omit the - * metadata flush. Defer that until the system flushes files to disk, - * or next non-MDBX_RDONLY commit or mdbx_env_sync(). Depending on the - * platform and hardware, with MDBX_NOMETASYNC you may get a doubling of - * write performance. - * - * This trade-off maintains database integrity, but a system crash may - * undo the last committed transaction. I.e. it preserves the ACI - * (atomicity, consistency, isolation) but not D (durability) database - * property. - * - * MDBX_NOMETASYNC flag may be changed at any time using - * mdbx_env_set_flags() or by passing to mdbx_txn_begin() for particular - * write transaction. - * - * - * MDBX_UTTERLY_NOSYNC = don't sync anything and wipe previous steady commits. - * - * Don't flush system buffers to disk when committing a transaction. This - * optimization means a system crash can corrupt the database, if buffers - * are not yet flushed to disk. Depending on the platform and hardware, - * with MDBX_UTTERLY_NOSYNC you may get a multiple increase of write - * performance, even 100 times or more. - * - * If the filesystem preserves write order (which is rare and never - * provided unless explicitly noted) and the MDBX_WRITEMAP and - * MDBX_LIFORECLAIM flags are not used, then a system crash can't corrupt - * the database, but you can lose the last transactions, if at least one - * buffer is not yet flushed to disk. The risk is governed by how often - * the system flushes dirty buffers to disk and how often mdbx_env_sync() - * is called. So, transactions exhibit ACI (atomicity, consistency, - * isolation) properties and only lose D (durability). I.e. database - * integrity is maintained, but a system crash may undo the final - * transactions. - * - * Otherwise, if the filesystem not preserves write order (which is - * typically) or MDBX_WRITEMAP or MDBX_LIFORECLAIM flags are used, you - * should expect the corrupted database after a system crash. - * - * So, most important thing about MDBX_UTTERLY_NOSYNC: - * - a system crash immediately after commit the write transaction - * high likely lead to database corruption. - * - successful completion of mdbx_env_sync(force = true) after one or - * more commited transactions guarantees consystency and durability. - * - BUT by committing two or more transactions you back database into a - * weak state, in which a system crash may lead to database - * corruption! In case single transaction after mdbx_env_sync, - * you may lose transaction itself, but not a whole database. - * - * Nevertheless, MDBX_UTTERLY_NOSYNC provides "weak" durability in case - * of an application crash (but no durability on system failure), and - * therefore may be very useful in scenarios where data durability is not - * required over a system failure (e.g for short-lived data), or if you - * can take such risk. - * - * MDBX_UTTERLY_NOSYNC flag may be changed at any time using - * mdbx_env_set_flags(), but don't has effect if passed to - * mdbx_txn_begin() for particular write transaction. - * - * - * MDBX_SAFE_NOSYNC = don't sync anything but keep previous steady commits. - * - * Like MDBX_UTTERLY_NOSYNC the MDBX_SAFE_NOSYNC flag similarly disable - * flush system buffers to disk when committing a transaction. But there - * is a huge difference in how are recycled the MVCC snapshots - * corresponding to previous "steady" transactions (see below). - * - * Depending on the platform and hardware, with MDBX_SAFE_NOSYNC you may - * get a multiple increase of write performance, even 10 times or more. - * NOTE that (MDBX_SAFE_NOSYNC | MDBX_WRITEMAP) leaves the system with no - * hint for when to write transactions to disk. Therefore the - * (MDBX_MAPASYNC | MDBX_WRITEMAP) may be preferable, but without - * MDBX_SAFE_NOSYNC because the (MDBX_MAPASYNC | MDBX_SAFE_NOSYNC) - * actually gives MDBX_UTTERLY_NOSYNC. - * - * In contrast to MDBX_UTTERLY_NOSYNC mode, with MDBX_SAFE_NOSYNC flag - * MDBX will keeps untouched pages within B-tree of the last transaction - * "steady" which was synced to disk completely. This has big - * implications for both data durability and (unfortunately) performance: - * - a system crash can't corrupt the database, but you will lose the - * last transactions; because MDBX will rollback to last steady commit - * since it kept explicitly. - * - the last steady transaction makes an effect similar to "long-lived" - * read transaction (see above in the "RESTRICTIONS & CAVEATS" - * section) since prevents reuse of pages freed by newer write - * transactions, thus the any data changes will be placed in newly - * allocated pages. - * - to avoid rapid database growth, the system will sync data and issue - * a steady commit-point to resume reuse pages, each time there is - * insufficient space and before increasing the size of the file on - * disk. - * - * In other words, with MDBX_SAFE_NOSYNC flag MDBX insures you from the - * whole database corruption, at the cost increasing database size and/or - * number of disk IOPS. So, MDBX_SAFE_NOSYNC flag could be used with - * mdbx_env_synv() as alternatively for batch committing or nested - * transaction (in some cases). As well, auto-sync feature exposed by - * mdbx_env_set_syncbytes() and mdbx_env_set_syncperiod() functions could - * be very usefull with MDBX_SAFE_NOSYNC flag. - * - * The number and volume of of disk IOPS with MDBX_SAFE_NOSYNC flag will - * exactly the as without any no-sync flags. However, you should expect a - * larger process's work set (https://bit.ly/2kA2tFX) and significantly - * worse a locality of reference (https://bit.ly/2mbYq2J), due to the - * more intensive allocation of previously unused pages and increase - * the size of the database. - * - * MDBX_SAFE_NOSYNC flag may be changed at any time using - * mdbx_env_set_flags() or by passing to mdbx_txn_begin() for particular - * write transaction. - * - * - * MDBX_MAPASYNC = use asynchronous msync when MDBX_WRITEMAP is used. - * - * MDBX_MAPASYNC meaningful and give effect only in conjunction - * with MDBX_WRITEMAP or MDBX_SAFE_NOSYNC: - * - with MDBX_SAFE_NOSYNC actually gives MDBX_UTTERLY_NOSYNC, which - * wipe previous steady commits for reuse pages as described above. - * - with MDBX_WRITEMAP but without MDBX_SAFE_NOSYNC instructs MDBX to - * use asynchronous mmap-flushes to disk as described below. - * - with both MDBX_WRITEMAP and MDBX_SAFE_NOSYNC you get the both - * effects. - * - * Asynchronous mmap-flushes means that actually all writes will - * scheduled and performed by operation system on it own manner, i.e. - * unordered. MDBX itself just notify operating system that it would - * be nice to write data to disk, but no more. - * - * With MDBX_MAPASYNC flag, but without MDBX_UTTERLY_NOSYNC (i.e. without - * OR'ing with MDBX_SAFE_NOSYNC) MDBX will keeps untouched pages within - * B-tree of the last transaction "steady" which was synced to disk - * completely. So, this makes exactly the same "long-lived" impact and - * the same consequences as described above for MDBX_SAFE_NOSYNC flag. - * - * Depending on the platform and hardware, with combination of - * MDBX_WRITEMAP and MDBX_MAPASYNC you may get a multiple increase of - * write performance, even 25 times or more. MDBX_MAPASYNC flag may be - * changed at any time using mdbx_env_set_flags() or by passing - * to mdbx_txn_begin() for particular write transaction. - */ + * @{ */ - /** Don't sync meta-page after commit, - * see description in the "SYNC MODES" section above. */ + /** Don't sync the meta-page after commit. + * + * Flush system buffers to disk only once per transaction, omit the + * metadata flush. Defer that until the system flushes files to disk, + * or next non-MDBX_RDONLY commit or mdbx_env_sync(). Depending on the + * platform and hardware, with MDBX_NOMETASYNC you may get a doubling + * of write performance. + * + * This trade-off maintains database integrity, but a system crash may + * undo the last committed transaction. I.e. it preserves the ACI + * (atomicity, consistency, isolation) but not D (durability) database + * property. + * + * MDBX_NOMETASYNC flag may be changed at any time using + * `mdbx_env_set_flags()` or by passing to `mdbx_txn_begin()` for + * particular write transaction. \see sync_modes */ MDBX_NOMETASYNC = UINT32_C(0x40000), - /** Don't sync anything but keep previous steady commits, - * see description in the "SYNC MODES" section above. + /** Don't sync anything but keep previous steady commits. * - * \note don't combine this flag with MDBX_MAPASYNC - * since you will got MDBX_UTTERLY_NOSYNC in that way (see below) */ + * Like MDBX_UTTERLY_NOSYNC the MDBX_SAFE_NOSYNC flag similarly disable flush + * system buffers to disk when committing a transaction. But there is a huge + * difference in how are recycled the MVCC snapshots corresponding to previous + * "steady" transactions (see below). + * + * Depending on the platform and hardware, with MDBX_SAFE_NOSYNC you may get a + * multiple increase of write performance, even 10 times or more. + * \note Note that (MDBX_SAFE_NOSYNC | MDBX_WRITEMAP) leaves the system with + * no hint for when to write transactions to disk. Therefore the + * (MDBX_MAPASYNC | MDBX_WRITEMAP) may be preferable, but without + * MDBX_SAFE_NOSYNC because the (MDBX_MAPASYNC | MDBX_SAFE_NOSYNC) actually + * gives MDBX_UTTERLY_NOSYNC. + * + * In contrast to MDBX_UTTERLY_NOSYNC mode, with MDBX_SAFE_NOSYNC flag MDBX + * will keeps untouched pages within B-tree of the last transaction "steady" + * which was synced to disk completely. This has big implications for both + * data durability and (unfortunately) performance: + * - a system crash can't corrupt the database, but you will lose the last + * transactions; because MDBX will rollback to last steady commit since it + * kept explicitly. + * + * - the last steady transaction makes an effect similar to "long-lived" read + * transaction (see above in the \ref restrictions section) since prevents + * reuse of pages freed by newer write transactions, thus the any data + * changes will be placed in newly allocated pages. + * - to avoid rapid database growth, the system will sync data and issue + * a steady commit-point to resume reuse pages, each time there is + * insufficient space and before increasing the size of the file on disk. + * + * In other words, with MDBX_SAFE_NOSYNC flag MDBX insures you from the whole + * database corruption, at the cost increasing database size and/or number of + * disk IOPS. So, MDBX_SAFE_NOSYNC flag could be used with `mdbx_env_synv()` + * as alternatively for batch committing or nested transaction (in some + * cases). As well, auto-sync feature exposed by `mdbx_env_set_syncbytes()` + * and `mdbx_env_set_syncperiod()` functions could be very usefull with + * MDBX_SAFE_NOSYNC flag. + * + * The number and volume of of disk IOPS with MDBX_SAFE_NOSYNC flag will + * exactly the as without any no-sync flags. However, you should expect a + * larger process's [work set](https://bit.ly/2kA2tFX) and significantly worse + * a [locality of reference](https://bit.ly/2mbYq2J), due to the more + * intensive allocation of previously unused pages and increase the size of + * the database. + * + * MDBX_SAFE_NOSYNC flag may be changed at any time using + * `mdbx_env_set_flags()` or by passing to `mdbx_txn_begin()` for particular + * write transaction. + * + * \note don't combine this flag with MDBX_MAPASYNC since you will got + * MDBX_UTTERLY_NOSYNC in that way. \see sync_modes */ MDBX_SAFE_NOSYNC = UINT32_C(0x10000), - /** Use asynchronous msync when MDBX_WRITEMAP is used, - * see description in the "SYNC MODES" section above. + /** Use asynchronous msync when MDBX_WRITEMAP is used. * - * \note don't combine this flag with MDBX_SAFE_NOSYNC - * since you will got MDBX_UTTERLY_NOSYNC in that way (see below) */ + * MDBX_MAPASYNC meaningful and give effect only in conjunction + * with MDBX_WRITEMAP or MDBX_SAFE_NOSYNC: + * - with MDBX_SAFE_NOSYNC actually gives MDBX_UTTERLY_NOSYNC, which + * wipe previous steady commits for reuse pages as described above. + * - with MDBX_WRITEMAP but without MDBX_SAFE_NOSYNC instructs MDBX to + * use asynchronous mmap-flushes to disk as described below. + * - with both MDBX_WRITEMAP and MDBX_SAFE_NOSYNC you get the both effects. + * + * Asynchronous mmap-flushes means that actually all writes will scheduled and + * performed by operation system on it own manner, i.e. unordered. MDBX itself + * just notify operating system that it would be nice to write data to disk, + * but no more. + * + * With MDBX_MAPASYNC flag, but without MDBX_UTTERLY_NOSYNC (i.e. without + * OR'ing with MDBX_SAFE_NOSYNC) MDBX will keeps untouched pages within B-tree + * of the last transaction "steady" which was synced to disk completely. So, + * this makes exactly the same "long-lived" impact and the same consequences + * as described above for MDBX_SAFE_NOSYNC flag. + * + * Depending on the platform and hardware, with combination of MDBX_WRITEMAP + * and MDBX_MAPASYNC you may get a multiple increase of write performance, + * even 25 times or more. MDBX_MAPASYNC flag may be changed at any time using + * `mdbx_env_set_flags()` or by passing to `mdbx_txn_begin()` for particular + * write transaction. + * + * \note don't combine this flag with MDBX_SAFE_NOSYNC since you will got + * MDBX_UTTERLY_NOSYNC in that way. \see sync_modes */ MDBX_MAPASYNC = UINT32_C(0x100000), - /** Don't sync anything and wipe previous steady commits, - * see description in the "SYNC MODES" section above. */ + /** Don't sync anything and wipe previous steady commits. + * + * Don't flush system buffers to disk when committing a transaction. This + * optimization means a system crash can corrupt the database, if buffers are + * not yet flushed to disk. Depending on the platform and hardware, with + * MDBX_UTTERLY_NOSYNC you may get a multiple increase of write performance, + * even 100 times or more. + * + * If the filesystem preserves write order (which is rare and never provided + * unless explicitly noted) and the MDBX_WRITEMAP and MDBX_LIFORECLAIM flags + * are not used, then a system crash can't corrupt the database, but you can + * lose the last transactions, if at least one buffer is not yet flushed to + * disk. The risk is governed by how often the system flushes dirty buffers to + * disk and how often mdbx_env_sync() is called. So, transactions exhibit ACI + * (atomicity, consistency, isolation) properties and only lose D + * (durability). I.e. database integrity is maintained, but a system crash may + * undo the final transactions. + * + * Otherwise, if the filesystem not preserves write order (which is + * typically) or MDBX_WRITEMAP or MDBX_LIFORECLAIM flags are used, you + * should expect the corrupted database after a system crash. + * + * So, most important thing about MDBX_UTTERLY_NOSYNC: + * - a system crash immediately after commit the write transaction + * high likely lead to database corruption. + * - successful completion of mdbx_env_sync(force = true) after one or + * more commited transactions guarantees consystency and durability. + * - BUT by committing two or more transactions you back database into + * a weak state, in which a system crash may lead to database corruption! + * In case single transaction after mdbx_env_sync, you may lose transaction + * itself, but not a whole database. + * + * Nevertheless, MDBX_UTTERLY_NOSYNC provides "weak" durability in case + * of an application crash (but no durability on system failure), and + * therefore may be very useful in scenarios where data durability is + * not required over a system failure (e.g for short-lived data), or if you + * can take such risk. + * + * MDBX_UTTERLY_NOSYNC flag may be changed at any time using + * mdbx_env_set_flags(), but don't has effect if passed to mdbx_txn_begin() + * for particular write transaction. \see sync_modes */ MDBX_UTTERLY_NOSYNC = MDBX_SAFE_NOSYNC | MDBX_MAPASYNC, + /** @} The end of SYNC_MODES */ + /** Do not block when starting a write transaction */ MDBX_TRYTXN = UINT32_C(0x10000000), }; @@ -957,29 +949,34 @@ typedef enum MDBX_env_flags_t MDBX_env_flags_t; DEFINE_ENUM_FLAG_OPERATORS(MDBX_env_flags_t) #endif -/** DATABASE FLAGS ************************************************************/ +/** DATABASE FLAGS */ enum MDBX_db_flags_t { MDBX_DB_DEFAULTS = 0, - MDBX_REVERSEKEY = UINT32_C(0x02) /** Use reverse string keys */, - MDBX_DUPSORT = UINT32_C(0x04) /** Use sorted duplicates */, - MDBX_INTEGERKEY = UINT32_C(0x08) /** Numeric keys in native byte order, - either uint32_t or uint64_t. - The keys must all be of the same size and must - be aligned while passing as arguments. */ - , - MDBX_DUPFIXED = UINT32_C(0x10) /** With MDBX_DUPSORT; - sorted dup items have fixed size */ - , - MDBX_INTEGERDUP = UINT32_C(0x20) /** With MDBX_DUPSORT; - dups are MDBX_INTEGERKEY-style integers. - The data values must all be of the same size - and must be aligned while passing as arguments. */ - , - MDBX_REVERSEDUP = UINT32_C(0x40) /** With MDBX_DUPSORT; - use reverse string comparison */ - , - MDBX_CREATE = UINT32_C(0x40000) /** Create DB if not already existing */ + /** Use reverse string keys */ + MDBX_REVERSEKEY = UINT32_C(0x02), + + /** Use sorted duplicates, i.e. allow multi-values */ + MDBX_DUPSORT = UINT32_C(0x04), + + /** Numeric keys in native byte order either uint32_t or uint64_t. The keys + must all be of the same size and must be aligned while passing as + arguments. */ + MDBX_INTEGERKEY = UINT32_C(0x08), + + /** With MDBX_DUPSORT; sorted dup items have fixed size */ + MDBX_DUPFIXED = UINT32_C(0x10), + + /** With MDBX_DUPSORT; dups are MDBX_INTEGERKEY-style integers. The data + values must all be of the same size and must be aligned while passing as + arguments. */ + MDBX_INTEGERDUP = UINT32_C(0x20), + + /** With MDBX_DUPSORT; use reverse string comparison */ + MDBX_REVERSEDUP = UINT32_C(0x40), + + /** Create DB if not already existing */ + MDBX_CREATE = UINT32_C(0x40000) }; #ifndef __cplusplus typedef enum MDBX_db_flags_t MDBX_db_flags_t; @@ -987,39 +984,35 @@ typedef enum MDBX_db_flags_t MDBX_db_flags_t; DEFINE_ENUM_FLAG_OPERATORS(MDBX_db_flags_t) #endif -/** DATA UPDATE FLAGS *********************************************************/ +/** DATA UPDATE FLAGS */ enum MDBX_put_flags_t { MDBX_PUT_DEFAULTS = 0, - MDBX_NOOVERWRITE = UINT32_C(0x10) /* For upsertion: Don't write if the key - already exists. */ - , - MDBX_NODUPDATA = UINT32_C(0x20) /* Only for MDBX_DUPSORT. - For upsertion: don't write if the key/data - pair already exist. - For deletion: remove all duplicate - data items. */ - , - MDBX_CURRENT = UINT32_C(0x40) /* For upsertion: overwrite the current - key/data pair. - MDBX allows this flag for mdbx_put() for - explicit overwrite/update without insertion. */ - , - MDBX_RESERVE = UINT32_C(0x10000) /* For upsertion: Just reserve space - for data, don't copy it. Return a pointer - to the reserved space. */ - , - MDBX_APPEND = UINT32_C(0x20000) /* Data is being appended. Don't split full - pages, continue on a new instead. */ - , - MDBX_APPENDDUP = UINT32_C(0x40000) /* Duplicate data is being appended. - Don't split full pages, - continue on a new instead. */ - , + /** For upsertion: Don't write if the key already exists. */ + MDBX_NOOVERWRITE = UINT32_C(0x10), - MDBX_MULTIPLE = UINT32_C(0x80000) /* Store multiple data items in one call. - Only for MDBX_DUPFIXED. */ - , + /** Only for MDBX_DUPSORT. For upsertion: don't write if the key/data pair + already exist. For deletion: remove all duplicate data items. */ + MDBX_NODUPDATA = UINT32_C(0x20), + + /** For upsertion: overwrite the current key/data pair.MDBX allows this flag + for mdbx_put() for explicit overwrite/update without insertion. */ + MDBX_CURRENT = UINT32_C(0x40), + + /** For upsertion: Just reserve space for data, don't copy it. Return a + pointer to the reserved space. */ + MDBX_RESERVE = UINT32_C(0x10000), + + /** Data is being appended. Don't split full pages, continue on a new instead. + */ + MDBX_APPEND = UINT32_C(0x20000), + + /** Duplicate data is being appended. Don't split full pages, continue on a + new instead. */ + MDBX_APPENDDUP = UINT32_C(0x40000), + + /** Store multiple data items in one call. Only for MDBX_DUPFIXED. */ + MDBX_MULTIPLE = UINT32_C(0x80000) }; #ifndef __cplusplus typedef enum MDBX_put_flags_t MDBX_put_flags_t; @@ -1027,13 +1020,16 @@ typedef enum MDBX_put_flags_t MDBX_put_flags_t; DEFINE_ENUM_FLAG_OPERATORS(MDBX_put_flags_t) #endif -/** ENVIRONMENT COPY FLAGS** **************************************************/ +/** ENVIRONMENT COPY FLAGS */ enum MDBX_copy_flags_t { MDBX_CP_DEFAULTS = 0, - /* Copy with compactification: Omit free space from copy and renumber all + + /** Copy with compactification: Omit free space from copy and renumber all pages sequentially */ MDBX_CP_COMPACT = 1u, - MDBX_CP_FORCE_RESIZEABLE = 2u + + /** Force to make resizeable copy, i.e. dynamic size instead of fixed */ + MDBX_CP_FORCE_DYNAMIC_SIZE = 2u }; #ifndef __cplusplus typedef enum MDBX_copy_flags_t MDBX_copy_flags_t; @@ -1041,97 +1037,129 @@ typedef enum MDBX_copy_flags_t MDBX_copy_flags_t; DEFINE_ENUM_FLAG_OPERATORS(MDBX_copy_flags_t) #endif -/** CURSOR OPERATIONS ********************************************************** +/** CURSOR OPERATIONS * - * This is the set of all operations for retrieving data - * using a cursor. */ + * This is the set of all operations for retrieving data using a cursor. */ enum MDBX_cursor_op { - MDBX_FIRST, /** Position at first key/data item */ - MDBX_FIRST_DUP, /** MDBX_DUPSORT-only: Position at first data item - * of current key. */ - MDBX_GET_BOTH, /** MDBX_DUPSORT-only: Position at key/data pair. */ - MDBX_GET_BOTH_RANGE, /** MDBX_DUPSORT-only: Position at given key and at first - * data greater than or equal to specified data. */ - MDBX_GET_CURRENT, /** Return key/data at current cursor position */ - MDBX_GET_MULTIPLE, /** MDBX_DUPFIXED-only: Return up to a page of duplicate - * data items from current cursor position. - * Move cursor to prepare for MDBX_NEXT_MULTIPLE. */ - MDBX_LAST, /** Position at last key/data item */ - MDBX_LAST_DUP, /** MDBX_DUPSORT-only: Position at last data item - * of current key. */ - MDBX_NEXT, /** Position at next data item */ - MDBX_NEXT_DUP, /** MDBX_DUPSORT-only: Position at next data item - * of current key. */ - MDBX_NEXT_MULTIPLE, /** MDBX_DUPFIXED-only: Return up to a page of - * duplicate data items from next cursor position. - * Move cursor to prepare for MDBX_NEXT_MULTIPLE. */ - MDBX_NEXT_NODUP, /** Position at first data item of next key */ - MDBX_PREV, /* Position at previous data item */ - MDBX_PREV_DUP, /** MDBX_DUPSORT-only: Position at previous data item - * of current key. */ - MDBX_PREV_NODUP, /** Position at last data item of previous key */ - MDBX_SET, /** Position at specified key */ - MDBX_SET_KEY, /** Position at specified key, return both key and data */ - MDBX_SET_RANGE, /** Position at first key greater than or equal to - * specified key. */ - MDBX_PREV_MULTIPLE /** MDBX_DUPFIXED-only: Position at previous page and - * return up to a page of duplicate data items. */ + /** Position at first key/data item */ + MDBX_FIRST, + + /** MDBX_DUPSORT-only: Position at first data item of current key. */ + MDBX_FIRST_DUP, + + /** MDBX_DUPSORT-only: Position at key/data pair. */ + MDBX_GET_BOTH, + + /** MDBX_DUPSORT-only: Position at given key and at first data greater than or + equal to specified data. */ + MDBX_GET_BOTH_RANGE, + + /** Return key/data at current cursor position */ + MDBX_GET_CURRENT, + + /** MDBX_DUPFIXED-only: Return up to a page of duplicate data items from + current cursor position. Move cursor to prepare for MDBX_NEXT_MULTIPLE. */ + MDBX_GET_MULTIPLE, + + /** Position at last key/data item */ + MDBX_LAST, + + /** MDBX_DUPSORT-only: Position at last data item of current key. */ + MDBX_LAST_DUP, + + /** Position at next data item */ + MDBX_NEXT, + + /** MDBX_DUPSORT-only: Position at next data item of current key. */ + MDBX_NEXT_DUP, + + /** MDBX_DUPFIXED-only: Return up to a page of duplicate data items from next + cursor position. Move cursor to prepare for MDBX_NEXT_MULTIPLE. */ + MDBX_NEXT_MULTIPLE, + + /** Position at first data item of next key */ + MDBX_NEXT_NODUP, + + /** Position at previous data item */ + MDBX_PREV, + + /** MDBX_DUPSORT-only: Position at previous data item of current key. */ + MDBX_PREV_DUP, + + /** Position at last data item of previous key */ + MDBX_PREV_NODUP, + + /** Position at specified key */ + MDBX_SET, + + /** Position at specified key, return both key and data */ + MDBX_SET_KEY, + + /** Position at first key greater than or equal to specified key. */ + MDBX_SET_RANGE, + + /** MDBX_DUPFIXED-only: Position at previous page and return up to a page of + duplicate data items. */ + MDBX_PREV_MULTIPLE }; #ifndef __cplusplus typedef enum MDBX_cursor_op MDBX_cursor_op; #endif -/**** ERRORS & RETURN CODES **************************************************** +/** ERRORS & RETURN CODES + * * BerkeleyDB uses -30800 to -30999, we'll go under them */ - enum MDBX_error_t { - /* Successful result */ + /** Successful result */ MDBX_SUCCESS = 0, + + /** Alias for MDBX_SUCCESS */ MDBX_RESULT_FALSE = MDBX_SUCCESS, - /* Successful result with special meaning or a flag */ + + /** Successful result with special meaning or a flag */ MDBX_RESULT_TRUE = -1, - /* key/data pair already exists */ + /** key/data pair already exists */ MDBX_KEYEXIST = -30799, - /* key/data pair not found (EOF) */ + /** key/data pair not found (EOF) */ MDBX_NOTFOUND = -30798, - /* Requested page not found - this usually indicates corruption */ + /** Requested page not found - this usually indicates corruption */ MDBX_PAGE_NOTFOUND = -30797, - /* Database is corrupted (page was wrong type and so on) */ + /** Database is corrupted (page was wrong type and so on) */ MDBX_CORRUPTED = -30796, - /* Environment had fatal error (i.e. update of meta page failed and so on) */ + /** Environment had fatal error (i.e. update of meta page failed and so on) */ MDBX_PANIC = -30795, - /* DB file version mismatch with libmdbx */ + /** DB file version mismatch with libmdbx */ MDBX_VERSION_MISMATCH = -30794, - /* File is not a valid MDBX file */ + /** File is not a valid MDBX file */ MDBX_INVALID = -30793, - /* Environment mapsize reached */ + /** Environment mapsize reached */ MDBX_MAP_FULL = -30792, - /* Environment maxdbs reached */ + /** Environment maxdbs reached */ MDBX_DBS_FULL = -30791, - /* Environment maxreaders reached */ + /** Environment maxreaders reached */ MDBX_READERS_FULL = -30790, - /* Transaction has too many dirty pages, i.e transaction too big */ + /** Transaction has too many dirty pages, i.e transaction too big */ MDBX_TXN_FULL = -30788, - /* Cursor stack too deep - this usually indicates corruption, + /** Cursor stack too deep - this usually indicates corruption, * i.e branch-pages loop */ MDBX_CURSOR_FULL = -30787, - /* Page has not enough space - internal error */ + /** Page has not enough space - internal error */ MDBX_PAGE_FULL = -30786, - /* Database engine was unable to extend mapping, e.g. since address space + /** Database engine was unable to extend mapping, e.g. since address space * is unavailable or busy. This can mean: * - Database size extended by other process beyond to environment mapsize * and engine was unable to extend mapping while starting read transaction. @@ -1140,7 +1168,7 @@ enum MDBX_error_t { * or explicit call of mdbx_env_set_geometry(). */ MDBX_UNABLE_EXTEND_MAPSIZE = -30785, - /* Environment or database is not compatible with the requested operation + /** Environment or database is not compatible with the requested operation * or the specified flags. This can mean: * - The operation expects an MDBX_DUPSORT / MDBX_DUPFIXED database. * - Opening a named DB when the unnamed DB has MDBX_DUPSORT/MDBX_INTEGERKEY. @@ -1148,56 +1176,56 @@ enum MDBX_error_t { * - The database was dropped and recreated with different flags. */ MDBX_INCOMPATIBLE = -30784, - /* Invalid reuse of reader locktable slot, + /** Invalid reuse of reader locktable slot, * e.g. read-transaction already run for current thread */ MDBX_BAD_RSLOT = -30783, - /* Transaction is not valid for requested operation, + /** Transaction is not valid for requested operation, * e.g. had errored and be must aborted, has a child, or is invalid */ MDBX_BAD_TXN = -30782, - /* Invalid size or alignment of key or data for target database, + /** Invalid size or alignment of key or data for target database, * either invalid subDB name */ MDBX_BAD_VALSIZE = -30781, - /* The specified DBI-handle is invalid + /** The specified DBI-handle is invalid * or changed by another thread/transaction */ MDBX_BAD_DBI = -30780, - /* Unexpected internal error, transaction should be aborted */ + /** Unexpected internal error, transaction should be aborted */ MDBX_PROBLEM = -30779, - /* The last LMDB-compatible defined error code */ + /** The last LMDB-compatible defined error code */ MDBX_LAST_LMDB_ERRCODE = MDBX_PROBLEM, - /* Another write transaction is running or environment is already used while + /** Another write transaction is running or environment is already used while * opening with MDBX_EXCLUSIVE flag */ MDBX_BUSY = -30778, - /* The specified key has more than one associated value */ + /** The specified key has more than one associated value */ MDBX_EMULTIVAL = -30421, - /* Bad signature of a runtime object(s), this can mean: + /** Bad signature of a runtime object(s), this can mean: * - memory corruption or double-free; * - ABI version mismatch (rare case); */ MDBX_EBADSIGN = -30420, - /* Database should be recovered, but this could NOT be done for now + /** Database should be recovered, but this could NOT be done for now * since it opened in read-only mode */ MDBX_WANNA_RECOVERY = -30419, - /* The given key value is mismatched to the current cursor position */ + /** The given key value is mismatched to the current cursor position */ MDBX_EKEYMISMATCH = -30418, - /* Database is too large for current system, + /** Database is too large for current system, * e.g. could NOT be mapped into RAM. */ MDBX_TOO_LARGE = -30417, - /* A thread has attempted to use a not owned object, + /** A thread has attempted to use a not owned object, * e.g. a transaction that started by another thread. */ MDBX_THREAD_MISMATCH = -30416, - /* Overlapping read and write transactions for the current thread */ + /** Overlapping read and write transactions for the current thread */ MDBX_TXN_OVERLAPPING = -30415, #if defined(_WIN32) || defined(_WIN64) @@ -1243,7 +1271,7 @@ MDBX_DEPRECATED static __inline int MDBX_MAP_RESIZED_is_deprecated() { /**** FUNCTIONS & RELATED STRUCTURES ******************************************/ -/* Return a string describing a given error code. +/** Return a string describing a given error code. * * This function is a superset of the ANSI C X3.159-1989 (ANSI C) strerror(3) * function. If the error code is greater than or equal to 0, then the string @@ -1251,33 +1279,52 @@ MDBX_DEPRECATED static __inline int MDBX_MAP_RESIZED_is_deprecated() { * is less than 0, an error string corresponding to the MDBX library error is * returned. See errors for a list of MDBX-specific error codes. * - * mdbx_strerror() - is NOT thread-safe because may share common internal - * buffer for system maessages. The returned string must - * NOT be modified by the application, but MAY be modified - * by a subsequent call to mdbx_strerror(), strerror() and - * other related functions. + * mdbx_strerror() is NOT thread-safe because may share common internal buffer + * for system maessages. The returned string must NOT be modified by the + * application, but MAY be modified by a subsequent call to mdbx_strerror(), + * strerror() and other related functions. + * \see mdbx_strerror_r() * - * mdbx_strerror_r() - is thread-safe since uses user-supplied buffer where - * appropriate. The returned string must NOT be modified - * by the application, since it may be pointer to internal - * constant string. However, there is no restriction if the - * returned string points to the supplied buffer. + * \param [in] errnum The error code. * - * [in] err The error code. - * - * Returns "error message" The description of the error. */ + * \returns "error message" The description of the error. */ LIBMDBX_API const char *mdbx_strerror(int errnum); + +/** Return a string describing a given error code. + * + * This function is a superset of the ANSI C X3.159-1989 (ANSI C) strerror(3) + * function. If the error code is greater than or equal to 0, then the string + * returned by the system function strerror(3) is returned. If the error code + * is less than 0, an error string corresponding to the MDBX library error is + * returned. See errors for a list of MDBX-specific error codes. + * + * mdbx_strerror_r() is thread-safe since uses user-supplied buffer where + * appropriate. The returned string must NOT be modified by the application, + * since it may be pointer to internal constant string. However, there is no + * restriction if the returned string points to the supplied buffer. + * \see mdbx_strerror() + * + * \param [in] errnum The error code. + * \param [in,out] buf Buffer to store the error message. + * \param [in] buflen The size of buffer to store the message. + * + * \returns "error message" The description of the error. */ LIBMDBX_API const char *mdbx_strerror_r(int errnum, char *buf, size_t buflen); #if defined(_WIN32) || defined(_WIN64) -/* Bit of Windows' madness. The similar functions but returns Windows - * error-messages in the OEM-encoding for console utilities. */ +/** Bit of Windows' madness. The similar to mdbx_strerror() but returns Windows + * error-messages in the OEM-encoding for console utilities. + * \see mdbx_strerror_r_ANSI2OEM(). */ LIBMDBX_API const char *mdbx_strerror_ANSI2OEM(int errnum); + +/** Bit of Windows' madness. The similar to mdbx_strerror_r() but returns + * Windows error-messages in the OEM-encoding for console utilities. + * \see mdbx_strerror_ANSI2OEM(). */ LIBMDBX_API const char *mdbx_strerror_r_ANSI2OEM(int errnum, char *buf, size_t buflen); #endif /* Bit of Windows' madness */ -/* Create an MDBX environment instance. +/** Create an MDBX environment instance. * * This function allocates memory for a MDBX_env structure. To release * the allocated memory and discard the handle, call mdbx_env_close(). @@ -1287,36 +1334,36 @@ LIBMDBX_API const char *mdbx_strerror_r_ANSI2OEM(int errnum, char *buf, * e.g. mdbx_env_set_geometry(), mdbx_env_set_maxreaders(), * mdbx_env_set_maxdbs(), depending on usage requirements. * - * [out] env The address where the new handle will be stored. + * \param [out] penv The address where the new handle will be stored. * - * Returns a non-zero error value on failure and 0 on success. */ + * \returns a non-zero error value on failure and 0 on success. */ LIBMDBX_API int mdbx_env_create(MDBX_env **penv); -/* Open an environment instance. +/** Open an environment instance. * * Indifferently this function will fails or not, the mdbx_env_close() must be * called later to discard the MDBX_env handle and release associated resources. * - * [in] env An environment handle returned by mdbx_env_create() - * [in] pathname The directory in which the database files reside. - * This directory must already exist and be writable. - * [in] flags Special options for this environment. This parameter - * must be set to 0 or by bitwise OR'ing together one - * or more of the values described above in the - * "ENVIRONMENT FLAGS" and "SYNC MODES" sections. + * \param [in] env An environment handle returned by mdbx_env_create() + * \param [in] pathname The directory in which the database files reside. + * This directory must already exist and be writable. + * \param [in] flags Special options for this environment. This parameter + * must be set to 0 or by bitwise OR'ing together one + * or more of the values described above in the + * \ref env_flags and \ref sync_modes sections. * * Flags set by mdbx_env_set_flags() are also used: * - MDBX_NOSUBDIR, MDBX_RDONLY, MDBX_EXCLUSIVE, MDBX_WRITEMAP, MDBX_NOTLS, * MDBX_NORDAHEAD, MDBX_NOMEMINIT, MDBX_COALESCE, MDBX_LIFORECLAIM. - * See "ENVIRONMENT FLAGS" section above. + * See \ref env_flags section. * * - MDBX_NOMETASYNC, MDBX_SAFE_NOSYNC, MDBX_UTTERLY_NOSYNC, MDBX_MAPASYNC. - * See "SYNC MODES" section above. + * See \ref sync_modes section. * - * NOTE: MDB_NOLOCK flag don't supported by MDBX, + * \note MDB_NOLOCK flag don't supported by MDBX, * try use MDBX_EXCLUSIVE as a replacement. * - * NOTE: MDBX don't allow to mix processes with different MDBX_SAFE_NOSYNC, + * \note MDBX don't allow to mix processes with different MDBX_SAFE_NOSYNC, * MDBX_NOMETASYNC, MDBX_MAPASYNC flags on the same environment. * In such case MDBX_INCOMPATIBLE will be returned. * @@ -1324,53 +1371,54 @@ LIBMDBX_API int mdbx_env_create(MDBX_env **penv); * mdbx_env_set_geometry() are incompatible (i.e. for instance, different page * size) then mdbx_env_open() will return MDBX_INCOMPATIBLE error. * - * [in] mode The UNIX permissions to set on created files. Zero value means - * to open existing, but do not create. + * \param [in] mode The UNIX permissions to set on created files. + * Zero value means to open existing, but do not create. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_VERSION_MISMATCH = the version of the MDBX library doesn't match the - * version that created the database environment. - * - MDBX_INVALID = the environment file headers are corrupted. - * - MDBX_ENOENT = the directory specified by the path parameter + * \return A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_VERSION_MISMATCH the version of the MDBX library doesn't match + * the version that created the database environment. + * \retval MDBX_INVALID the environment file headers are corrupted. + * \retval MDBX_ENOENT the directory specified by the path parameter * doesn't exist. - * - MDBX_EACCES = the user didn't have permission to access + * \retval MDBX_EACCES the user didn't have permission to access * the environment files. - * - MDBX_EAGAIN = the environment was locked by another process. - * - MDBX_BUSY = MDBX_EXCLUSIVE flag was specified and the + * \retval MDBX_EAGAIN the environment was locked by another process. + * \retval MDBX_BUSY MDBX_EXCLUSIVE flag was specified and the * environment is in use by another process, * or the current process tries to open environment * more than once. - * - MDBX_INCOMPATIBLE = Environment is already opened by another process, + * \retval MDBX_INCOMPATIBLE Environment is already opened by another process, * but with different set of MDBX_SAFE_NOSYNC, * MDBX_NOMETASYNC, MDBX_MAPASYNC flags. * Or if the database is already exist and * parameters specified early by * mdbx_env_set_geometry() are incompatible (i.e. * for instance, different page size). - * - MDBX_WANNA_RECOVERY = MDBX_RDONLY flag was specified but read-write + * \retval MDBX_WANNA_RECOVERY MDBX_RDONLY flag was specified but read-write * access is required to rollback inconsistent state * after a system crash. - * - MDBX_TOO_LARGE = Database is too large for this process, i.e. + * \retval MDBX_TOO_LARGE Database is too large for this process, i.e. * 32-bit process tries to open >4Gb database. */ LIBMDBX_API int mdbx_env_open(MDBX_env *env, const char *pathname, unsigned flags, mode_t mode); -/* Copy an MDBX environment to the specified path, with options. +/** Copy an MDBX environment to the specified path, with options. * * This function may be used to make a backup of an existing environment. * No lockfile is created, since it gets recreated at need. - * NOTE: This call can trigger significant file size growth if run in + * \note This call can trigger significant file size growth if run in * parallel with write transactions, because it employs a read-only * transaction. See long-lived transactions under "Caveats" section. * - * [in] env An environment handle returned by mdbx_env_create(). It must - * have already been opened successfully. - * [in] dest The pathname of a file in which the copy will reside. This file - * must not be already exist, but parent directory must be writable. - * [in] flags Special options for this operation. This parameter must be set - * to 0 or by bitwise OR'ing together one or more of the values - * described here: + * \param [in] env An environment handle returned by mdbx_env_create(). + * It must have already been opened successfully. + * \param [in] dest The pathname of a file in which the copy will reside. + * This file must not be already exist, but parent directory + * must be writable. + * \param [in] flags Special options for this operation. This parameter must + * be set to 0 or by bitwise OR'ing together one or more + * of the values described here: * * - MDBX_CP_COMPACT * Perform compaction while copying: omit free pages and sequentially @@ -1378,47 +1426,52 @@ LIBMDBX_API int mdbx_env_open(MDBX_env *env, const char *pathname, * CPU for processing, but may running quickly than the default, on * account skipping free pages. * - * Returns A non-zero error value on failure and 0 on success. */ + * - MDBX_CP_FORCE_DYNAMIC_SIZE + * Force to make resizeable copy, i.e. dynamic size instead of fixed. + * + * \returns A non-zero error value on failure and 0 on success. */ LIBMDBX_API int mdbx_env_copy(MDBX_env *env, const char *dest, unsigned flags); -/* Copy an MDBX environment to the specified file descriptor, - * with options. +/** Copy an MDBX environment to the specified file descriptor, with options. * * This function may be used to make a backup of an existing environment. * No lockfile is created, since it gets recreated at need. See * mdbx_env_copy() for further details. * - * NOTE: This call can trigger significant file size growth if run in + * \note This call can trigger significant file size growth if run in * parallel with write transactions, because it employs a read-only * transaction. See long-lived transactions under "Caveats" section. * - * NOTE: Fails if the environment has suffered a page leak and the destination + * \note Fails if the environment has suffered a page leak and the destination * file descriptor is associated with a pipe, socket, or FIFO. * - * [in] env An environment handle returned by mdbx_env_create(). It must - * have already been opened successfully. - * [in] fd The filedescriptor to write the copy to. It must have already - * been opened for Write access. - * [in] flags Special options for this operation. See mdbx_env_copy() for - * options. + * \param [in] env An environment handle returned by mdbx_env_create(). + * It must have already been opened successfully. + * \param [in] fd The file descriptor to write the copy to. It must have + * already been opened for Write access. + * \param [in] flags Special options for this operation. \see mdbx_env_copy() + * for options. * - * Returns A non-zero error value on failure and 0 on success. */ + * \returns A non-zero error value on failure and 0 on success. */ LIBMDBX_API int mdbx_env_copy2fd(MDBX_env *env, mdbx_filehandle_t fd, unsigned flags); -/* Statistics for a database in the environment */ -typedef struct MDBX_stat { - uint32_t ms_psize; /* Size of a database page. - * This is the same for all databases. */ - uint32_t ms_depth; /* Depth (height) of the B-tree */ - uint64_t ms_branch_pages; /* Number of internal (non-leaf) pages */ - uint64_t ms_leaf_pages; /* Number of leaf pages */ - uint64_t ms_overflow_pages; /* Number of overflow pages */ - uint64_t ms_entries; /* Number of data items */ - uint64_t ms_mod_txnid; /* Transaction ID of commited last modification */ -} MDBX_stat; +/** Statistics for a database in the environment */ +struct MDBX_stat { + uint32_t ms_psize; /**< Size of a database page. This is the same for all + databases. */ + uint32_t ms_depth; /**< Depth (height) of the B-tree */ + uint64_t ms_branch_pages; /**< Number of internal (non-leaf) pages */ + uint64_t ms_leaf_pages; /**< Number of leaf pages */ + uint64_t ms_overflow_pages; /**< Number of overflow pages */ + uint64_t ms_entries; /**< Number of data items */ + uint64_t ms_mod_txnid; /**< Transaction ID of commited last modification */ +}; +#ifndef __cplusplus +typedef struct MDBX_stat MDBX_stat; +#endif -/* Return statistics about the MDBX environment. +/** Return statistics about the MDBX environment. * * At least one of env or txn argument must be non-null. If txn is passed * non-null then stat will be filled accordingly to the given transaction. @@ -1429,70 +1482,77 @@ typedef struct MDBX_stat { * Legacy mdbx_env_stat() correspond to calling mdbx_env_stat_ex() with the null * txn argument. * - * [in] env An environment handle returned by mdbx_env_create() - * [in] txn A transaction handle returned by mdbx_txn_begin() - * [out] stat The address of an MDBX_stat structure where the statistics - * will be copied + * \param [in] env An environment handle returned by mdbx_env_create() + * \param [in] txn A transaction handle returned by mdbx_txn_begin() + * \param [out] stat The address of an MDBX_stat structure where + * the statistics will be copied + * \param [in] bytes The size of MDBX_stat. * - * Returns A non-zero error value on failure and 0 on success. */ + * \returns A non-zero error value on failure and 0 on success. */ LIBMDBX_API int mdbx_env_stat_ex(const MDBX_env *env, const MDBX_txn *txn, MDBX_stat *stat, size_t bytes); +/** Return statistics about the MDBX environment. + * \deprecated Please use mdbx_env_stat_ex() insted. */ MDBX_DEPRECATED LIBMDBX_API int mdbx_env_stat(MDBX_env *env, MDBX_stat *stat, size_t bytes); -/* Information about the environment */ -typedef struct MDBX_envinfo { +/** Information about the environment */ +struct MDBX_envinfo { struct { - uint64_t lower; /* lower limit for datafile size */ - uint64_t upper; /* upper limit for datafile size */ - uint64_t current; /* current datafile size */ - uint64_t shrink; /* shrink threshold for datafile */ - uint64_t grow; /* growth step for datafile */ + uint64_t lower; /**< Lower limit for datafile size */ + uint64_t upper; /**< Upper limit for datafile size */ + uint64_t current; /**< Current datafile size */ + uint64_t shrink; /**< Shrink threshold for datafile */ + uint64_t grow; /**< Growth step for datafile */ } mi_geo; - uint64_t mi_mapsize; /* Size of the data memory map */ - uint64_t mi_last_pgno; /* ID of the last used page */ - uint64_t mi_recent_txnid; /* ID of the last committed transaction */ - uint64_t mi_latter_reader_txnid; /* ID of the last reader transaction */ - uint64_t mi_self_latter_reader_txnid; /* ID of the last reader transaction of - caller process */ + uint64_t mi_mapsize; /**< Size of the data memory map */ + uint64_t mi_last_pgno; /**< Number of the last used page */ + uint64_t mi_recent_txnid; /**< ID of the last committed transaction */ + uint64_t mi_latter_reader_txnid; /**< ID of the last reader transaction */ + uint64_t mi_self_latter_reader_txnid; /**< ID of the last reader transaction + of caller process */ uint64_t mi_meta0_txnid, mi_meta0_sign; uint64_t mi_meta1_txnid, mi_meta1_sign; uint64_t mi_meta2_txnid, mi_meta2_sign; - uint32_t mi_maxreaders; /* max reader slots in the environment */ - uint32_t mi_numreaders; /* max reader slots used in the environment */ - uint32_t mi_dxb_pagesize; /* database pagesize */ - uint32_t mi_sys_pagesize; /* system pagesize */ + uint32_t mi_maxreaders; /**< Total reader slots in the environment */ + uint32_t mi_numreaders; /**< Max reader slots used in the environment */ + uint32_t mi_dxb_pagesize; /**< Database pagesize */ + uint32_t mi_sys_pagesize; /**< System pagesize */ + /** A mostly unique ID that is regenerated on each boot. + + As such it can be used to identify the local machine's current boot. MDBX + uses such when open the database to determine whether rollback required to + the last steady sync point or not. I.e. if current bootid is differ from the + value within a database then the system was rebooted and all changes since + last steady sync must be reverted for data integrity. Zeros mean that no + relevant information is available from the system. */ struct { - /* A mostly unique ID that is regenerated on each boot. As such it can be - used to identify the local machine's current boot. MDBX uses such when - open the database to determine whether rollback required to the last - steady sync point or not. I.e. if current bootid is differ from the value - within a database then the system was rebooted and all changes since last - steady sync must be reverted for data integrity. Zeros mean that no - relevant information is available from the system. */ struct { uint64_t l, h; } current, meta0, meta1, meta2; } mi_bootid; - uint64_t mi_unsync_volume; /* bytes not explicitly synchronized to disk */ - uint64_t mi_autosync_threshold; /* current auto-sync threshold, see - mdbx_env_set_syncbytes(). */ - uint32_t mi_since_sync_seconds16dot16; /* time since the last steady sync in - 1/65536 of second */ - uint32_t mi_autosync_period_seconds16dot16 /* current auto-sync period in - 1/65536 of second, see - mdbx_env_set_syncperiod(). */ - ; - uint32_t mi_since_reader_check_seconds16dot16; /* time since the last readers - check in 1/65536 of second, - see mdbx_reader_check(). */ - uint32_t mi_mode; /* current environment mode, the same as - mdbx_env_get_flags() returns. */ -} MDBX_envinfo; + /** Bytes not explicitly synchronized to disk */ + uint64_t mi_unsync_volume; + /** Current auto-sync threshold, see mdbx_env_set_syncbytes(). */ + uint64_t mi_autosync_threshold; + /** Time since the last steady sync in 1/65536 of second */ + uint32_t mi_since_sync_seconds16dot16; + /** Current auto-sync period in 1/65536 of second, + * see mdbx_env_set_syncperiod(). */ + uint32_t mi_autosync_period_seconds16dot16; + /** Time since the last readers check in 1/65536 of second, + * see mdbx_reader_check(). */ + uint32_t mi_since_reader_check_seconds16dot16; + /** Current environment mode, the same as mdbx_env_get_flags() returns. */ + uint32_t mi_mode; +}; +#ifndef __cplusplus +typedef struct MDBX_envinfo MDBX_envinfo; +#endif -/* Return information about the MDBX environment. +/** Return information about the MDBX environment. * * At least one of env or txn argument must be non-null. If txn is passed * non-null then stat will be filled accordingly to the given transaction. @@ -1502,19 +1562,22 @@ typedef struct MDBX_envinfo { * * Legacy mdbx_env_info() correspond to calling mdbx_env_info_ex() with the null * txn argument. - - * [in] env An environment handle returned by mdbx_env_create() - * [in] txn A transaction handle returned by mdbx_txn_begin() - * [out] stat The address of an MDBX_envinfo structure - * where the information will be copied * - * Returns A non-zero error value on failure and 0 on success. */ + * \param [in] env An environment handle returned by mdbx_env_create() + * \param [in] txn A transaction handle returned by mdbx_txn_begin() + * \param [out] info The address of an MDBX_envinfo structure + * where the information will be copied + * \param [in] bytes The size of MDBX_envinfo. + * + * \returns A non-zero error value on failure and 0 on success. */ LIBMDBX_API int mdbx_env_info_ex(const MDBX_env *env, const MDBX_txn *txn, MDBX_envinfo *info, size_t bytes); +/** Return information about the MDBX environment. + * \deprecated Please use mdbx_env_info_ex() insted. */ MDBX_DEPRECATED LIBMDBX_API int mdbx_env_info(MDBX_env *env, MDBX_envinfo *info, size_t bytes); -/* Flush the environment data buffers to disk. +/** Flush the environment data buffers to disk. * * Unless the environment was opened with no-sync flags (MDBX_NOMETASYNC, * MDBX_SAFE_NOSYNC, MDBX_UTTERLY_NOSYNC and MDBX_MAPASYNC), then data is always @@ -1526,35 +1589,38 @@ MDBX_DEPRECATED LIBMDBX_API int mdbx_env_info(MDBX_env *env, MDBX_envinfo *info, * provide polling mode for lazy/asynchronous sync in conjunction with * mdbx_env_set_syncbytes() and/or mdbx_env_set_syncperiod(). * - * The mdbx_env_sync() is shortcut to calling mdbx_env_sync_ex() with - * try force=true and nonblock=false arguments. + * \note This call is not valid if the environment was opened with MDBX_RDONLY. * - * The mdbx_env_sync_poll() is shortcut to calling mdbx_env_sync_ex() with - * the force=false and nonblock=true arguments. + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [in] force If non-zero, force a flush. Otherwise, If force is zero, + * then will run in polling mode, i.e. it will check the + * thresholds that were set mdbx_env_set_syncbytes() and/or + * mdbx_env_set_syncperiod() and perform flush If at least + * one of the thresholds is reached. + * \param [in] nonblock Don't wait if write transaction is running + * by other thread. * - * NOTE: This call is not valid if the environment was opened with MDBX_RDONLY. - * - * [in] env An environment handle returned by mdbx_env_create(). - * [in] force If non-zero, force a flush. Otherwise, if force is zero, then - * will run in polling mode, i.e. it will check the thresholds - * that were set mdbx_env_set_syncbytes() and/or - * mdbx_env_set_syncperiod() and perform flush If at least one - * of the thresholds is reached. - * [in] nonblock Don't wait if write transaction is running by other thread. - * - * Returns A non-zero error value on failure and MDBX_RESULT_TRUE or 0 on - * success. The MDBX_RESULT_TRUE means no data pending for flush to disk, - * and 0 otherwise. Some possible errors are: - * - MDBX_EACCES = the environment is read-only. - * - MDBX_BUSY = the environment is used by other thread and nonblock=true. - * - MDBX_EINVAL = an invalid parameter was specified. - * - MDBX_EIO = an error occurred during synchronization. */ + * \returns A non-zero error value on failure and MDBX_RESULT_TRUE or 0 on + * success. The MDBX_RESULT_TRUE means no data pending for flush to disk, + * and 0 otherwise. Some possible errors are: + * \retval MDBX_EACCES the environment is read-only. + * \retval MDBX_BUSY the environment is used by other thread + * and nonblock=true. + * \retval MDBX_EINVAL an invalid parameter was specified. + * \retval MDBX_EIO an error occurred during synchronization. */ LIBMDBX_API int mdbx_env_sync_ex(MDBX_env *env, int force, int nonblock); + +/** The shortcut to calling mdbx_env_sync_ex() with + * the force=true and nonblock=false arguments. */ LIBMDBX_API int mdbx_env_sync(MDBX_env *env); + +/** The shortcut to calling mdbx_env_sync_ex() with + * the force=false and nonblock=true arguments. */ LIBMDBX_API int mdbx_env_sync_poll(MDBX_env *env); -/* Sets threshold to force flush the data buffers to disk, even of +/** Sets threshold to force flush the data buffers to disk, even any of * MDBX_SAFE_NOSYNC, MDBX_NOMETASYNC and MDBX_MAPASYNC flags in the environment. + * * The threshold value affects all processes which operates with given * environment until the last process close environment or a new value will be * settled. @@ -1567,18 +1633,20 @@ LIBMDBX_API int mdbx_env_sync_poll(MDBX_env *env); * The default is 0, than mean no any threshold checked, and no additional * flush will be made. * - * [in] env An environment handle returned by mdbx_env_create(). - * [in] threshold The size in bytes of summary changes when a synchronous - * flush would be made. + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [in] threshold The size in bytes of summary changes when + * a synchronous flush would be made. * - * Returns A non-zero error value on failure and 0 on success. */ + * \returns A non-zero error value on failure and 0 on success. */ LIBMDBX_API int mdbx_env_set_syncbytes(MDBX_env *env, size_t threshold); -/* Sets relative period since the last unsteay commit to force flush the data - * buffers to disk, even of MDBX_SAFE_NOSYNC, MDBX_NOMETASYNC and MDBX_MAPASYNC - * flags in the environment. The relative period value affects all processes - * which operates with given environment until the last process close - * environment or a new value will be settled. +/** Sets relative period since the last unsteay commit to force flush the data + * buffers to disk, even any of MDBX_SAFE_NOSYNC, MDBX_NOMETASYNC and + * MDBX_MAPASYNC flags in the environment. + * + * The relative period value affects all processes which operates with given + * environment until the last process close environment or a new value will be + * settled. * * Data is always written to disk when mdbx_txn_commit() is called, but the * operating system may keep it buffered. MDBX always flushes the OS buffers @@ -1593,15 +1661,15 @@ LIBMDBX_API int mdbx_env_set_syncbytes(MDBX_env *env, size_t threshold); * The default is 0, than mean no any timeout checked, and no additional * flush will be made. * - * [in] env An environment handle returned by mdbx_env_create(). - * [in] seconds_16dot16 The period in 1/65536 of second when a synchronous - * flush would be made since the last unsteay commit. + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [in] seconds_16dot16 The period in 1/65536 of second when + * a synchronous flush would be made since the last unsteay commit. * - * Returns A non-zero error value on failure and 0 on success. */ + * \returns A non-zero error value on failure and 0 on success. */ LIBMDBX_API int mdbx_env_set_syncperiod(MDBX_env *env, unsigned seconds_16dot16); -/* Close the environment and release the memory map. +/** Close the environment and release the memory map. * * Only a single thread may call this function. All transactions, databases, * and cursors must already be closed before calling this function. Attempts @@ -1609,88 +1677,88 @@ LIBMDBX_API int mdbx_env_set_syncperiod(MDBX_env *env, * The environment handle will be freed and must not be used again after this * call. * - * Legacy mdbx_env_close() correspond to calling mdbx_env_close_ex() with the - * argument dont_sync=false. + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [in] dont_sync A dont'sync flag, if non-zero the last checkpoint + * will be kept "as is" and may be still "weak" in the + * NOSYNC/MAPASYNC modes. Such "weak" checkpoint will be + * ignored on opening next time, and transactions since + * the last non-weak checkpoint (meta-page update) will + * rolledback for consistency guarantee. * - * [in] env An environment handle returned by mdbx_env_create(). - * [in] dont_sync A dont'sync flag, if non-zero the last checkpoint (meta-page - * update) will be kept "as is" and may be still "weak" in the - * NOSYNC/MAPASYNC modes. Such "weak" checkpoint will be - * ignored on opening next time, and transactions since the - * last non-weak checkpoint (meta-page update) will rolledback - * for consistency guarantee. - * - * Returns A non-zero error value on failure and 0 on success. - * Some possible errors are: - * - MDBX_BUSY = The write transaction is running by other thread, in such + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_BUSY The write transaction is running by other thread, in such * case MDBX_env instance has NOT be destroyed not released! - * NOTE: if any OTHER error code was returned then given - * MDBX_env instance has been destroyed and released. - * - MDBX_EBADSIGN = Environment handle already closed (i.e. mdbx_env_close() - * was already called or not valid (i.e. was not created - * by mdbx_env_create()). - * - MDBX_PANIC = If mdbx_env_close_ex() was called in the child process + * \note If any OTHER error code was returned then given + * MDBX_env instance has been destroyed and released. + * \retval MDBX_EBADSIGN Environment handle already closed or not valid, i.e. + * mdbx_env_close() was already called for the `env` + * or the `env` was not created by mdbx_env_create(). + * \retval MDBX_PANIC If mdbx_env_close_ex() was called in the child process * after fork(). In this case MDBX_PANIC is a expecte, * i.e. MDBX_env instance was freed in proper manner. - * - MDBX_EIO = an error occurred during synchronization. */ + * \retval MDBX_EIO An error occurred during synchronization. */ LIBMDBX_API int mdbx_env_close_ex(MDBX_env *env, int dont_sync); + +/** The shortcut to calling dbx_env_close_ex() with + * the dont_sync=false argument. */ LIBMDBX_API int mdbx_env_close(MDBX_env *env); -/* Set environment flags. +/** Set environment flags. * * This may be used to set some flags in addition to those from * mdbx_env_open(), or to unset these flags. * - * NOTE: In contrast to LMDB, the MDBX serialize threads via mutex while + * \note In contrast to LMDB, the MDBX serialize threads via mutex while * changing the flags. Therefore this function will be blocked while a write * transaction running by other thread, or MDBX_BUSY will be returned if * function called within a write transaction. * - * [in] env An environment handle returned by mdbx_env_create(). - * [in] flags The flags to change, bitwise OR'ed together. - * [in] onoff A non-zero value sets the flags, zero clears them. + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [in] flags The flags to change, bitwise OR'ed together. + * \param [in] onoff A non-zero value sets the flags, zero clears them. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_EINVAL An invalid parameter was specified. */ LIBMDBX_API int mdbx_env_set_flags(MDBX_env *env, unsigned flags, int onoff); -/* Get environment flags. +/** Get environment flags. * - * [in] env An environment handle returned by mdbx_env_create(). - * [out] flags The address of an integer to store the flags. + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [out] flags The address of an integer to store the flags. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_EINVAL An invalid parameter was specified. */ LIBMDBX_API int mdbx_env_get_flags(const MDBX_env *env, unsigned *flags); -/* Return the path that was used in mdbx_env_open(). +/** Return the path that was used in mdbx_env_open(). * - * [in] env An environment handle returned by mdbx_env_create() - * [out] dest Address of a string pointer to contain the path. - * This is the actual string in the environment, not a copy. - * It should not be altered in any way. + * \param [in] env An environment handle returned by mdbx_env_create() + * \param [out] dest Address of a string pointer to contain the path. + * This is the actual string in the environment, not a copy. + * It should not be altered in any way. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_EINVAL An invalid parameter was specified. */ LIBMDBX_API int mdbx_env_get_path(const MDBX_env *env, const char **dest); -/* Return the file descriptor for the given environment. +/** Return the file descriptor for the given environment. * - * NOTE: All MDBX file descriptors have FD_CLOEXEC and - * could't be used after exec() and or fork(). + * \note All MDBX file descriptors have FD_CLOEXEC and + * could't be used after exec() and or fork(). * - * [in] env An environment handle returned by mdbx_env_create(). - * [out] fd Address of a int to contain the descriptor. + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [out] fd Address of a int to contain the descriptor. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_EINVAL An invalid parameter was specified. */ LIBMDBX_API int mdbx_env_get_fd(const MDBX_env *env, mdbx_filehandle_t *fd); -/* Set all size-related parameters of environment, including page size and the +/** Set all size-related parameters of environment, including page size and the * min/max size of the memory map. * * In contrast to LMDB, the MDBX provide automatic size management of an @@ -1801,7 +1869,7 @@ LIBMDBX_API int mdbx_env_get_fd(const MDBX_env *env, mdbx_filehandle_t *fd); * is busy). Therefore, in the case of MDBX_UNABLE_EXTEND_MAPSIZE error you * need close and reopen the environment to resolve error. * - * NOTE: Actual values may be different than your have specified because of + * \note Actual values may be different than your have specified because of * rounding to specified database page size, the system page size and/or the * size of the system virtual memory management unit. You can get actual values * by mdbx_env_sync_ex() or see by using the tool "mdbx_chk" with the "-v" @@ -1811,19 +1879,19 @@ LIBMDBX_API int mdbx_env_get_fd(const MDBX_env *env, mdbx_filehandle_t *fd); * with the arguments size_lower, size_now, size_upper equal to the size * and -1 (i.e. default) for all other parameters. * - * [in] env An environment handle returned by mdbx_env_create() + * \param [in] env An environment handle returned by mdbx_env_create() * - * [in] size_lower The lower bound of database sive in bytes. - * Zero value means "minimal acceptable", - * and negative means "keep current or use default". + * \param [in] size_lower The lower bound of database sive in bytes. + * Zero value means "minimal acceptable", + * and negative means "keep current or use default". * - * [in] size_now The size in bytes to setup the database size for now. - * Zero value means "minimal acceptable", - * and negative means "keep current or use default". - * So, it is recommended always pass -1 in this argument - * except some special cases. + * \param [in] size_now The size in bytes to setup the database size for + * now. Zero value means "minimal acceptable", and + * negative means "keep current or use default". So, + * it is recommended always pass -1 in this argument + * except some special cases. * - * [in] size_upper The upper bound of database sive in bytes. + * \param [in] size_upper The upper bound of database sive in bytes. * Zero value means "minimal acceptable", * and negative means "keep current or use default". * It is recommended to avoid change upper bound while @@ -1838,81 +1906,91 @@ LIBMDBX_API int mdbx_env_get_fd(const MDBX_env *env, mdbx_filehandle_t *fd); * (which are extremely volatile in a multi-process * multi-threaded environment). * - * [in] growth_step The growth step in bytes, must be greater than zero - * to allow the database to grow. - * Negative value means "keep current or use default". + * \param [in] growth_step The growth step in bytes, must be greater than + * zero to allow the database to grow. Negative value + * means "keep current or use default". * - * [in] shrink_threshold The shrink threshold in bytes, must be greater than - * zero to allow the database to shrink. - * Negative value means "keep current or use default". + * \param [in] shrink_threshold The shrink threshold in bytes, must be greater + * than zero to allow the database to shrink. + * Negative value means "keep current + * or use default". * - * [in] pagesize The database page size for new database creation - * or -1 otherwise. Must be power of 2 in the range - * between MDBX_MIN_PAGESIZE and MDBX_MAX_PAGESIZE. - * Zero value means "minimal acceptable", - * and negative means "keep current or use default". + * \param [in] pagesize The database page size for new database + * creation or -1 otherwise. Must be power of 2 + * in the range between MDBX_MIN_PAGESIZE and + * MDBX_MAX_PAGESIZE. Zero value means "minimal + * acceptable", and negative means "keep current + * or use default". * - * Returns A non-zero error value on failure and 0 on success, - * some possible errors are: - * - MDBX_EINVAL = An invalid parameter was specified, - * or the environment has an active write transaction. - * - MDBX_EPERM = specific for Windows: Shrinking was disabled before and - * now it wanna be enabled, but there are reading threads - * that don't use the additional SRWL (that is required to - * avoid Windows issues). - * - MDBX_EACCESS = The environment opened in read-only. - * - MDBX_MAP_FULL = Specified size smaller than the space already - * consumed by the environment. - * - MDBX_TOO_LARGE = Specified size is too large, i.e. too many pages for - * given size, or a 32-bit process requests too much bytes - * for the 32-bit address space. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_EINVAL An invalid parameter was specified, + * or the environment has an active write transaction. + * \retval MDBX_EPERM Specific for Windows: Shrinking was disabled before + * and now it wanna be enabled, but there are reading + * threads that don't use the additional SRWL (that + * is required to avoid Windows issues). + * \retval MDBX_EACCESS The environment opened in read-only. + * \retval MDBX_MAP_FULL Specified size smaller than the space already + * consumed by the environment. + * \retval MDBX_TOO_LARGE Specified size is too large, i.e. too many pages for + * given size, or a 32-bit process requests too much + * bytes for the 32-bit address space. */ LIBMDBX_API int mdbx_env_set_geometry(MDBX_env *env, intptr_t size_lower, intptr_t size_now, intptr_t size_upper, intptr_t growth_step, intptr_t shrink_threshold, intptr_t pagesize); + +/** \deprecated Please use mdbx_env_set_geometry() instead. */ MDBX_DEPRECATED LIBMDBX_API int mdbx_env_set_mapsize(MDBX_env *env, size_t size); -/* Find out whether to use readahead or not, based on the given database size +/** Find out whether to use readahead or not, based on the given database size * and the amount of available memory. * - * [in] volume The expected database size in bytes. - * [in] redundancy Additional reserve or overload in case of negative value. + * \param [in] volume The expected database size in bytes. + * \param [in] redundancy Additional reserve or overload in case of negative + * value. * - * Returns: - * - MDBX_RESULT_TRUE = readahead is reasonable. - * - MDBX_RESULT_FALSE = readahead is NOT reasonable, i.e. MDBX_NORDAHEAD - * is useful to open environment by mdbx_env_open(). - * - Otherwise the error code. */ + * \returns A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, + * otherwise the error code: + * \retval MDBX_RESULT_TRUE Readahead is reasonable. + * \retval MDBX_RESULT_FALSE Readahead is NOT reasonable, i.e. MDBX_NORDAHEAD + * is useful to open environment by mdbx_env_open(). + * \retval Otherwise the error code. */ LIBMDBX_API int mdbx_is_readahead_reasonable(size_t volume, intptr_t redundancy); -/* The minimal database page size in bytes. */ +/** Returns the minimal database page size in bytes. */ __inline intptr_t mdbx_limits_pgsize_min(void) { return MDBX_MIN_PAGESIZE; } -/* The maximal database page size in bytes. */ +/** Returns the maximal database page size in bytes. */ __inline intptr_t mdbx_limits_pgsize_max(void) { return MDBX_MAX_PAGESIZE; } -/* Returns minimal database size in bytes for given page size, +/** Returns minimal database size in bytes for given page size, * or -1 if pagesize is invalid. */ LIBMDBX_API intptr_t mdbx_limits_dbsize_min(intptr_t pagesize); -/* Returns maximal database size in bytes for given page size, +/** Returns maximal database size in bytes for given page size, * or -1 if pagesize is invalid. */ LIBMDBX_API intptr_t mdbx_limits_dbsize_max(intptr_t pagesize); -/* Returns maximal key and data size in bytes for given page size +/** Returns maximal key size in bytes for given page size * and database flags (see mdbx_dbi_open_ex() description), * or -1 if pagesize is invalid. */ LIBMDBX_API intptr_t mdbx_limits_keysize_max(intptr_t pagesize, unsigned flags); + +/** Returns maximal data size in bytes for given page size + * and database flags (see mdbx_dbi_open_ex() description), + * or -1 if pagesize is invalid. */ LIBMDBX_API intptr_t mdbx_limits_valsize_max(intptr_t pagesize, unsigned flags); -/* Returns maximal write transaction size (i.e. limit for summary volume of +/** Returns maximal write transaction size (i.e. limit for summary volume of * dirty pages) in bytes for given page size, or -1 if pagesize is invalid. */ LIBMDBX_API intptr_t mdbx_limits_txnsize_max(intptr_t pagesize); -/* Set the maximum number of threads/reader slots for the environment. +/** Set the maximum number of threads/reader slots for the environment. * * This defines the number of slots in the lock table that is used to track * readers in the the environment. The default is 119 for 4K system page size. @@ -1923,26 +2001,26 @@ LIBMDBX_API intptr_t mdbx_limits_txnsize_max(intptr_t pagesize); * This function may only be called after mdbx_env_create() and before * mdbx_env_open(). * - * [in] env An environment handle returned by mdbx_env_create(). - * [in] readers The maximum number of reader lock table slots. + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [in] readers The maximum number of reader lock table slots. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_EINVAL = an invalid parameter was specified. - * - MDBX_EPERM = the environment is already open. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_EINVAL An invalid parameter was specified. + * \retval MDBX_EPERM The environment is already open. */ LIBMDBX_API int mdbx_env_set_maxreaders(MDBX_env *env, unsigned readers); -/* Get the maximum number of threads/reader slots for the environment. +/** Get the maximum number of threads/reader slots for the environment. * - * [in] env An environment handle returned by mdbx_env_create(). - * [out] readers Address of an integer to store the number of readers. + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [out] readers Address of an integer to store the number of readers. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_EINVAL An invalid parameter was specified. */ LIBMDBX_API int mdbx_env_get_maxreaders(const MDBX_env *env, unsigned *readers); -/* Set the maximum number of named databases for the environment. +/** Set the maximum number of named databases for the environment. * * This function is only needed if multiple databases will be used in the * environment. Simpler applications that use the environment as a single @@ -1954,188 +2032,201 @@ LIBMDBX_API int mdbx_env_get_maxreaders(const MDBX_env *env, unsigned *readers); * expensive: 7-120 words per transaction, and every mdbx_dbi_open() * does a linear search of the opened slots. * - * [in] env An environment handle returned by mdbx_env_create(). - * [in] dbs The maximum number of databases. + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [in] dbs The maximum number of databases. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_EINVAL = an invalid parameter was specified. - * - MDBX_EPERM = the environment is already open. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_EINVAL An invalid parameter was specified. + * \retval MDBX_EPERM The environment is already open. */ LIBMDBX_API int mdbx_env_set_maxdbs(MDBX_env *env, MDBX_dbi dbs); -/* Get the maximum size of keys and data we can write. +/** Get the maximum size of keys can write. * - * [in] env An environment handle returned by mdbx_env_create(). - * [in] flags Database options (MDBX_DUPSORT, MDBX_INTEGERKEY ans so on), - * see mdbx_dbi_open_ex() description. + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [in] flags Database options (MDBX_DUPSORT, MDBX_INTEGERKEY + * and so on), see mdbx_dbi_open_ex() description. * - * Returns The maximum size of a key we can write, - * or -1 if something is wrong. */ + * \returns The maximum size of a key can write, + * or -1 if something is wrong. */ LIBMDBX_API int mdbx_env_get_maxkeysize_ex(const MDBX_env *env, unsigned flags); + +/** Get the maximum size of data we can write. + * + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [in] flags Database options (MDBX_DUPSORT, MDBX_INTEGERKEY + * and so on), see mdbx_dbi_open_ex() description. + * + * \returns The maximum size of a data can write, + * or -1 if something is wrong. */ LIBMDBX_API int mdbx_env_get_maxvalsize_ex(const MDBX_env *env, unsigned flags); + +/** \deprecated Please use mdbx_env_get_maxkeysize_ex() + * and/or mdbx_env_get_maxvalsize_ex() */ MDBX_DEPRECATED LIBMDBX_API int mdbx_env_get_maxkeysize(const MDBX_env *env); -/* Set application information associated with the MDBX_env. +/** Set application information associated with the MDBX_env. * - * [in] env An environment handle returned by mdbx_env_create(). - * [in] ctx An arbitrary pointer for whatever the application needs. + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [in] ctx An arbitrary pointer for whatever the application needs. * - * Returns A non-zero error value on failure and 0 on success. */ + * \returns A non-zero error value on failure and 0 on success. */ LIBMDBX_API int mdbx_env_set_userctx(MDBX_env *env, void *ctx); -/* Get the application information associated with the MDBX_env. +/** Get the application information associated with the MDBX_env. * - * [in] env An environment handle returned by mdbx_env_create() - * Returns The pointer set by mdbx_env_set_userctx(). */ + * \param [in] env An environment handle returned by mdbx_env_create() + * \returns The pointer set by mdbx_env_set_userctx(). */ LIBMDBX_API void *mdbx_env_get_userctx(const MDBX_env *env); -/* Create a transaction for use with the environment. +/** Create a transaction for use with the environment. * * The transaction handle may be discarded using mdbx_txn_abort() * or mdbx_txn_commit(). * - * NOTE: A transaction and its cursors must only be used by a single thread, + * \note A transaction and its cursors must only be used by a single thread, * and a thread may only have a single transaction at a time. If MDBX_NOTLS is * in use, this does not apply to read-only transactions. * - * NOTE: Cursors may not span transactions. + * \note Cursors may not span transactions. * - * [in] env An environment handle returned by mdbx_env_create() - * [in] parent If this parameter is non-NULL, the new transaction will be - * a nested transaction, with the transaction indicated by parent - * as its parent. Transactions may be nested to any level. - * A parent transaction and its cursors may not issue any other - * operations than mdbx_txn_commit and mdbx_txn_abort while it - * has active child transactions. - * [in] flags Special options for this transaction. This parameter - * must be set to 0 or by bitwise OR'ing together one or more - * of the values described here. + * \param [in] env An environment handle returned by mdbx_env_create() + * \param [in] parent If this parameter is non-NULL, the new transaction will + * be a nested transaction, with the transaction indicated + * by parent as its parent. Transactions may be nested + * to any level. A parent transaction and its cursors may + * not issue any other operations than mdbx_txn_commit and + * mdbx_txn_abort() while it has active child transactions. + * \param [in] flags Special options for this transaction. This parameter + * must be set to 0 or by bitwise OR'ing together one + * or more of the values described here: + * - MDBX_RDONLY This transaction will not perform + * any write operations. * - * - MDBX_RDONLY - * This transaction will not perform any write operations. + * - MDBX_TRYTXN Do not block when starting + * a write transaction. * - * - MDBX_TRYTXN - * Do not block when starting a write transaction. + * - MDBX_SAFE_NOSYNC, MDBX_NOMETASYNC or MDBX_MAPASYNC + * Do not sync data to disk corresponding + * to MDBX_NOMETASYNC or MDBX_SAFE_NOSYNC description, + * see \ref sync_modes. * - * - MDBX_SAFE_NOSYNC, MDBX_NOMETASYNC or MDBX_MAPASYNC - * Do not sync data to disk corresponding to MDBX_NOMETASYNC - * or MDBX_SAFE_NOSYNC description (see abobe). + * \param [out] txn Address where the new MDBX_txn handle will be stored * - * [out] txn Address where the new MDBX_txn handle will be stored - * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_PANIC = a fatal error occurred earlier and the environment - * must be shut down. - * - MDBX_UNABLE_EXTEND_MAPSIZE - * = another process wrote data beyond this MDBX_env's - * mapsize and this environment's map must be resized - * as well. See mdbx_env_set_mapsize(). - * - MDBX_READERS_FULL = a read-only transaction was requested and the reader - * lock table is full. See mdbx_env_set_maxreaders(). - * - MDBX_ENOMEM = out of memory. - * - MDBX_BUSY = the write transaction is already started by the - * current thread. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_PANIC A fatal error occurred earlier and the + * environment must be shut down. + * \retval MDBX_UNABLE_EXTEND_MAPSIZE Another process wrote data beyond + * this MDBX_env's mapsize and this + * environment map must be resized as well. + * See mdbx_env_set_mapsize(). + * \retval MDBX_READERS_FULL A read-only transaction was requested and + * the reader lock table is full. + * See mdbx_env_set_maxreaders(). + * \retval MDBX_ENOMEM Out of memory. + * \retval MDBX_BUSY The write transaction is already started by the + * current thread. */ LIBMDBX_API int mdbx_txn_begin(MDBX_env *env, MDBX_txn *parent, unsigned flags, MDBX_txn **txn); -/* Information about the transaction */ -typedef struct MDBX_txn_info { - uint64_t txn_id; /* The ID of the transaction. For a READ-ONLY transaction, - this corresponds to the snapshot being read. */ +/** Information about the transaction */ +struct MDBX_txn_info { + /** The ID of the transaction. For a READ-ONLY transaction, this corresponds + to the snapshot being read. */ + uint64_t txn_id; - uint64_t - txn_reader_lag; /* For READ-ONLY transaction: the lag from a recent - MVCC-snapshot, i.e. the number of committed - transaction since read transaction started. - For WRITE transaction (provided if scan_rlt=true): the - lag of the oldest reader from current transaction (i.e. - atleast 1 if any reader running). */ + /** For READ-ONLY transaction: the lag from a recent MVCC-snapshot, i.e. the + number of committed transaction since read transaction started. For WRITE + transaction (provided if scan_rlt=true): the lag of the oldest reader from + current transaction (i.e. atleast 1 if any reader running). */ + uint64_t txn_reader_lag; - uint64_t txn_space_used; /* Used space by this transaction, i.e. corresponding - to the last used database page. */ + /** Used space by this transaction, i.e. corresponding to the last used + * database page. */ + uint64_t txn_space_used; - uint64_t txn_space_limit_soft; /* Current size of database file. */ + /** Current size of database file. */ + uint64_t txn_space_limit_soft; - uint64_t - txn_space_limit_hard; /* Upper bound for size the database file, - i.e. the value "size_upper" argument of the - approriate call of mdbx_env_set_geometry(). */ + /** Upper bound for size the database file, i.e. the value "size_upper" + argument of the approriate call of mdbx_env_set_geometry(). */ + uint64_t txn_space_limit_hard; - uint64_t txn_space_retired; /* For READ-ONLY transaction: The total size of - the database pages that were retired by - committed write transactions after the reader's - MVCC-snapshot, i.e. the space which would be - freed after the Reader releases the - MVCC-snapshot for reuse by completion read - transaction. - For WRITE transaction: The summarized size of - the database pages that were retired for now - due Copy-On-Write during this transaction. */ + /** For READ-ONLY transaction: The total size of the database pages that were + retired by committed write transactions after the reader's MVCC-snapshot, + i.e. the space which would be freed after the Reader releases the + MVCC-snapshot for reuse by completion read transaction. + For WRITE transaction: The summarized size of the database pages that were + retired for now due Copy-On-Write during this transaction. */ + uint64_t txn_space_retired; - uint64_t - txn_space_leftover; /* For READ-ONLY transaction: the space available for - writer(s) and that must be exhausted for reason to - call the OOM-killer for this read transaction. - For WRITE transaction: the space inside transaction - that left to MDBX_TXN_FULL error. */ + /** For READ-ONLY transaction: the space available for writer(s) and that must + be exhausted for reason to call the OOM-killer for this read transaction. + For WRITE transaction: the space inside transaction that left to + MDBX_TXN_FULL error. */ + uint64_t txn_space_leftover; - uint64_t txn_space_dirty; /* For READ-ONLY transaction (provided if - scan_rlt=true): The space that actually become - available for reuse when only this transaction - will be finished. - For WRITE transaction: The summarized size of the - dirty database pages that generated during this - transaction. */ -} MDBX_txn_info; + /** For READ-ONLY transaction (provided if scan_rlt=true): The space that + actually become available for reuse when only this transaction will be + finished. + For WRITE transaction: The summarized size of the dirty database + pages that generated during this transaction. */ + uint64_t txn_space_dirty; +}; +#ifndef __cplusplus +typedef struct MDBX_txn_info MDBX_txn_info; +#endif -/* Return information about the MDBX transaction. +/** Return information about the MDBX transaction. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [out] stat The address of an MDBX_txn_info structure - * where the information will be copied. - * [in] scan_rlt The boolean flag controls the scan of the read lock table to - * provide complete information. Such scan is relatively - * expensive and you can avoid it if corresponding fields are - * not needed (see description of MDBX_txn_info above). + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [out] info The address of an MDBX_txn_info structure + * where the information will be copied. + * \param [in] scan_rlt The boolean flag controls the scan of the read lock + * table to provide complete information. Such scan + * is relatively expensive and you can avoid it + * if corresponding fields are not needed. + * See description of MDBX_txn_info. * - * Returns A non-zero error value on failure and 0 on success. */ + * \returns A non-zero error value on failure and 0 on success. */ LIBMDBX_API int mdbx_txn_info(const MDBX_txn *txn, MDBX_txn_info *info, int scan_rlt); -/* Returns the transaction's MDBX_env. +/** Returns the transaction's MDBX_env. * - * [in] txn A transaction handle returned by mdbx_txn_begin() */ + * \param [in] txn A transaction handle returned by mdbx_txn_begin() */ LIBMDBX_API MDBX_env *mdbx_txn_env(const MDBX_txn *txn); -/* Return the transaction's flags. +/** Return the transaction's flags. * * This returns the flags associated with this transaction. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). * - * Returns A transaction flags, valid if input is an valid transaction, - * otherwise -1. */ + * \returns A transaction flags, valid if input is an valid transaction, + * otherwise -1. */ LIBMDBX_API int mdbx_txn_flags(const MDBX_txn *txn); -/* Return the transaction's ID. +/** Return the transaction's ID. * * This returns the identifier associated with this transaction. For a read-only * transaction, this corresponds to the snapshot being read; concurrent readers * will frequently have the same transaction ID. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). * - * Returns A transaction ID, valid if input is an active transaction, - * otherwise 0. */ + * \returns A transaction ID, valid if input is an active transaction, + * otherwise 0. */ LIBMDBX_API uint64_t mdbx_txn_id(const MDBX_txn *txn); -/* Commit all the operations of a transaction into the database. +/** Commit all the operations of a transaction into the database. * * If the current thread is not eligible to manage the transaction then * the MDBX_THREAD_MISMATCH error will returned. Otherwise the transaction * will be committed and its handle is freed. If the transaction cannot * be committed, it will be aborted with the corresponding error returned. + * * Thus, a result other than MDBX_THREAD_MISMATCH means that the transaction * is terminated: * - Resources are released; @@ -2146,26 +2237,27 @@ LIBMDBX_API uint64_t mdbx_txn_id(const MDBX_txn *txn); * or after transaction commit, either can be reused with mdbx_cursor_renew() * until it will be explicitly closed by mdbx_cursor_close(). * - * [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_RESULT_TRUE = transaction was aborted since it should be aborted - * due to previous errors. - * - MDBX_PANIC = a fatal error occurred earlier and the environment - * must be shut down. - * - MDBX_BAD_TXN = transaction is already fihished or never began. - * - MDBX_EBADSIGN = transaction object has invalid signature, - * e.g. transaction was already terminated - * or memory was corrupted. - * - MDBX_THREAD_MISMATCH = given transaction is not owned by current thread. - * - MDBX_EINVAL = transaction handle is NULL. - * - MDBX_ENOSPC = no more disk space. - * - MDBX_EIO = a system-level I/O error occurred while writing. - * - MDBX_ENOMEM = out of memory. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_RESULT_TRUE Transaction was aborted since it should + * be aborted due to previous errors. + * \retval MDBX_PANIC A fatal error occurred earlier + * and the environment must be shut down. + * \retval MDBX_BAD_TXN Transaction is already fihished or never began. + * \retval MDBX_EBADSIGN Transaction object has invalid signature, + * e.g. transaction was already terminated + * or memory was corrupted. + * \retval MDBX_THREAD_MISMATCH Given transaction is not owned + * by current thread. + * \retval MDBX_EINVAL Transaction handle is NULL. + * \retval MDBX_ENOSPC No more disk space. + * \retval MDBX_EIO A system-level I/O error occurred. + * \retval MDBX_ENOMEM Out of memory. */ LIBMDBX_API int mdbx_txn_commit(MDBX_txn *txn); -/* Abandon all the operations of the transaction instead of saving them. +/** Abandon all the operations of the transaction instead of saving them. * * The transaction handle is freed. It and its cursors must not be used again * after this call, except with mdbx_cursor_renew() and mdbx_cursor_close(). @@ -2182,21 +2274,22 @@ LIBMDBX_API int mdbx_txn_commit(MDBX_txn *txn); * or after transaction abort, either can be reused with mdbx_cursor_renew() * until it will be explicitly closed by mdbx_cursor_close(). * - * [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_PANIC = a fatal error occurred earlier and the environment - * must be shut down. - * - MDBX_BAD_TXN = transaction is already fihished or never began. - * - MDBX_EBADSIGN = transaction object has invalid signature, - * e.g. transaction was already terminated - * or memory was corrupted. - * - MDBX_THREAD_MISMATCH = given transaction is not owned by current thread. - * - MDBX_EINVAL = transaction handle is NULL. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_PANIC A fatal error occurred earlier and + * the environment must be shut down. + * \retval MDBX_BAD_TXN Transaction is already fihished or never began. + * \retval MDBX_EBADSIGN Transaction object has invalid signature, + * e.g. transaction was already terminated + * or memory was corrupted. + * \retval MDBX_THREAD_MISMATCH Given transaction is not owned + * by current thread. + * \retval MDBX_EINVAL Transaction handle is NULL. */ LIBMDBX_API int mdbx_txn_abort(MDBX_txn *txn); -/* Reset a read-only transaction. +/** Reset a read-only transaction. * * Abort the read-only transaction like mdbx_txn_abort(), but keep the * transaction handle. Therefore mdbx_txn_renew() may reuse the handle. This @@ -2214,54 +2307,59 @@ LIBMDBX_API int mdbx_txn_abort(MDBX_txn *txn); * being reused when writers commit new data, and so under heavy load the * database size may grow much more rapidly than otherwise. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_PANIC = a fatal error occurred earlier and the environment - * must be shut down. - * - MDBX_BAD_TXN = transaction is already fihished or never began. - * - MDBX_EBADSIGN = transaction object has invalid signature, - * e.g. transaction was already terminated - * or memory was corrupted. - * - MDBX_THREAD_MISMATCH = given transaction is not owned by current thread. - * - MDBX_EINVAL = transaction handle is NULL. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_PANIC A fatal error occurred earlier and + * the environment must be shut down. + * \retval MDBX_BAD_TXN Transaction is already fihished or never began. + * \retval MDBX_EBADSIGN Transaction object has invalid signature, + * e.g. transaction was already terminated + * or memory was corrupted. + * \retval MDBX_THREAD_MISMATCH Given transaction is not owned + * by current thread. + * \retval MDBX_EINVAL Transaction handle is NULL. */ LIBMDBX_API int mdbx_txn_reset(MDBX_txn *txn); -/* Renew a read-only transaction. +/** Renew a read-only transaction. * * This acquires a new reader lock for a transaction handle that had been * released by mdbx_txn_reset(). It must be called before a reset transaction * may be used again. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_PANIC = a fatal error occurred earlier and the environment - * must be shut down. - * - MDBX_BAD_TXN = transaction is already fihished or never began. - * - MDBX_EBADSIGN = transaction object has invalid signature, - * e.g. transaction was already terminated - * or memory was corrupted. - * - MDBX_THREAD_MISMATCH = transaction is running by other thread. - * - MDBX_EINVAL = transaction handle is NULL. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_PANIC A fatal error occurred earlier and + * the environment must be shut down. + * \retval MDBX_BAD_TXN Transaction is already fihished or never began. + * \retval MDBX_EBADSIGN Transaction object has invalid signature, + * e.g. transaction was already terminated + * or memory was corrupted. + * \retval MDBX_THREAD_MISMATCH Given transaction is not owned + * by current thread. + * \retval MDBX_EINVAL Transaction handle is NULL. */ LIBMDBX_API int mdbx_txn_renew(MDBX_txn *txn); -/* The fours integers markers (aka "canary") associated with the environment. +/** The fours integers markers (aka "canary") associated with the environment. * * The `x`, `y` and `z` values could be set by mdbx_canary_put(), while the 'v' * will be always set to the transaction number. Updated values becomes visible * outside the current transaction only after it was committed. Current values * could be retrieved by mdbx_canary_get(). */ -typedef struct mdbx_canary { +struct MDBX_canary { uint64_t x, y, z, v; -} mdbx_canary; +}; +#ifndef __cplusplus +typedef struct MDBX_canary MDBX_canary; +#endif -/* Set integers markers (aka "canary") associated with the environment. +/** Set integers markers (aka "canary") associated with the environment. * - * [in] txn A transaction handle returned by mdbx_txn_begin() - * [in] canary A optional pointer to mdbx_canary structure for `x`, `y` + * \param [in] txn A transaction handle returned by mdbx_txn_begin() + * \param [in] canary A optional pointer to MDBX_canary structure for `x`, `y` * and `z` values from. * - If canary is NOT NULL then the `x`, `y` and `z` values will be * updated from given canary argument, but the 'v' be always set @@ -2273,23 +2371,23 @@ typedef struct mdbx_canary { * to the current transaction number without changes `x`, `y` nor * `z`. * - * Returns A non-zero error value on failure and 0 on success. */ -LIBMDBX_API int mdbx_canary_put(MDBX_txn *txn, const mdbx_canary *canary); + * \returns A non-zero error value on failure and 0 on success. */ +LIBMDBX_API int mdbx_canary_put(MDBX_txn *txn, const MDBX_canary *canary); -/* Returns fours integers markers (aka "canary") associated with the +/** Returns fours integers markers (aka "canary") associated with the * environment. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] canary The address of an mdbx_canary structure where the information - * will be copied. + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] canary The address of an MDBX_canary structure where the + * information will be copied. * - * Returns A non-zero error value on failure and 0 on success. */ -LIBMDBX_API int mdbx_canary_get(const MDBX_txn *txn, mdbx_canary *canary); + * \returns A non-zero error value on failure and 0 on success. */ +LIBMDBX_API int mdbx_canary_get(const MDBX_txn *txn, MDBX_canary *canary); -/* A callback function used to compare two keys in a database */ +/** A callback function used to compare two keys in a database */ typedef int(MDBX_cmp_func)(const MDBX_val *a, const MDBX_val *b); -/* Open a database in the environment. +/** Open a database in the environment. * * A database handle denotes the name and parameters of a database, * independently of whether such a database exists. The database handle may be @@ -2316,12 +2414,13 @@ typedef int(MDBX_cmp_func)(const MDBX_val *a, const MDBX_val *b); * must be called before opening the environment. Table names are * keys in the internal unnamed database, and may be read but not written. * - * [in] txn transaction handle returned by mdbx_txn_begin(). - * [in] name The name of the database to open. If only a single - * database is needed in the environment, this value may be NULL. - * [in] flags Special options for this database. This parameter must be set - * to 0 or by bitwise OR'ing together one or more of the values - * described here: + * \param [in] txn transaction handle returned by mdbx_txn_begin(). + * \param [in] name The name of the database to open. If only a single + * database is needed in the environment, + * this value may be NULL. + * \param [in] flags Special options for this database. This parameter must + * be set to 0 or by bitwise OR'ing together one or more + * of the values described here: * - MDBX_REVERSEKEY * Keys are strings to be compared in reverse order, from the end * of the strings to the beginning. By default, Keys are treated as @@ -2353,14 +2452,14 @@ typedef int(MDBX_cmp_func)(const MDBX_val *a, const MDBX_val *b); * Create the named database if it doesn't exist. This option is not * allowed in a read-only transaction or a read-only environment. * - * [out] dbi Address where the new MDBX_dbi handle will be stored. + * \param [out] dbi Address where the new MDBX_dbi handle will be stored. * * For mdbx_dbi_open_ex() additional arguments allow you to set custom * comparison functions for keys and values (for multimaps). * However, I recommend not using custom comparison functions, but instead * converting the keys to one of the forms that are suitable for built-in - * comparators (for instance take look to the mdbx_key_from_xxx() - * functions). The reasons to not using custom comparators are: + * comparators (for instance take look to the \ref value2key). + * The reasons to not using custom comparators are: * - The order of records could not be validated without your code. * So mdbx_chk utility will reports "wrong order" errors * and the '-i' option is required to ignore ones. @@ -2368,32 +2467,44 @@ typedef int(MDBX_cmp_func)(const MDBX_val *a, const MDBX_val *b); * So mdbx_load utility should be used with '-a' option to preserve * input data order. * - * [in] keycmp Optional custom key comparison function for a database. - * [in] datacmp Optional custom data comparison function for a database, takes - * effect only if database was opened with the MDB_DUPSORT flag. - * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_NOTFOUND = the specified database doesn't exist in the + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_NOTFOUND The specified database doesn't exist in the * environment and MDBX_CREATE was not specified. - * - MDBX_DBS_FULL = too many databases have been opened. + * \retval MDBX_DBS_FULL Too many databases have been opened. * See mdbx_env_set_maxdbs(). - * - MDBX_INCOMPATIBLE = Database is incompatible with given flags, + * \retval MDBX_INCOMPATIBLE Database is incompatible with given flags, * i.e. the passed flags is different with which the * database was created, or the database was already - * opened with a different comparison function(s). */ -MDBX_DEPRECATED LIBMDBX_API int -mdbx_dbi_open_ex(MDBX_txn *txn, const char *name, unsigned flags, MDBX_dbi *dbi, - MDBX_cmp_func *keycmp, MDBX_cmp_func *datacmp); + * opened with a different comparison function(s). + * \retval MDBX_THREAD_MISMATCH Given transaction is not owned + * by current thread. */ LIBMDBX_API int mdbx_dbi_open(MDBX_txn *txn, const char *name, unsigned flags, MDBX_dbi *dbi); -/* Key-making (value-to-key) functions to avoid custom comparators. +/** \deprecated Please avoid using custom comparators + * and use mdbx_dbi_open() instead. + * + * \param [in] txn transaction handle returned by mdbx_txn_begin(). + * \param [in] name The name of the database to open. If only a single + * database is needed in the environment, + * this value may be NULL. + * \param [in] flags Special options for this database. + * \param [in] keycmp Optional custom key comparison function for a database. + * \param [in] datacmp Optional custom data comparison function for a database. + * \param [out] dbi Address where the new MDBX_dbi handle will be stored. + * \returns A non-zero error value on failure and 0 on success. */ +MDBX_DEPRECATED LIBMDBX_API int +mdbx_dbi_open_ex(MDBX_txn *txn, const char *name, unsigned flags, MDBX_dbi *dbi, + MDBX_cmp_func *keycmp, MDBX_cmp_func *datacmp); +/** \defgroup value2key Value-to-Key functions to avoid custom comparators + * \see key2value + * @{ * * The mdbx_key_from_jsonInteger() build key which are comparable with * keys created by mdbx_key_from_double(). So this allow mix int64 and IEEE754 * double values in one index for JSON-numbers with restriction for integer - * numbers range corresponding to RFC-7159 (i.e. [-(2**53)+1, (2**53)-1]. + * numbers range corresponding to RFC-7159, i.e. \f$[-2^{53}+1, 2^{53}-1]\f$. * See bottom of page 6 at https://tools.ietf.org/html/rfc7159 */ LIBMDBX_API uint64_t mdbx_key_from_jsonInteger(const int64_t json_integer); LIBMDBX_API uint64_t mdbx_key_from_double(const double ieee754_64bit); @@ -2406,39 +2517,48 @@ __inline uint64_t mdbx_key_from_int64(const int64_t i64) { __inline uint32_t mdbx_key_from_int32(const int32_t i32) { return UINT32_C(0x80000000) + i32; } +/** @} */ -/* Key-reverse (key-to-value) functions to avoid custom comparators. */ +/** \defgroup key2value Key-to-Value functions to avoid custom comparators + * \see value2key + * @{ */ LIBMDBX_API int64_t mdbx_jsonInteger_from_key(const MDBX_val); LIBMDBX_API double mdbx_double_from_key(const MDBX_val); LIBMDBX_API float mdbx_float_from_key(const MDBX_val); LIBMDBX_API int32_t mdbx_int32_from_key(const MDBX_val); LIBMDBX_API int64_t mdbx_int64_from_key(const MDBX_val); +/** @} */ -/* Retrieve statistics for a database. +/** Retrieve statistics for a database. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] dbi A database handle returned by mdbx_dbi_open(). - * [out] stat The address of an MDBX_stat structure where the statistics - * will be copied. + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [out] stat The address of an MDBX_stat structure where + * the statistics will be copied. + * \param [in] bytes The size of MDBX_stat. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_THREAD_MISMATCH Given transaction is not owned + * by current thread. + * \retval MDBX_EINVAL An invalid parameter was specified. */ LIBMDBX_API int mdbx_dbi_stat(MDBX_txn *txn, MDBX_dbi dbi, MDBX_stat *stat, size_t bytes); -/* Retrieve depth (bitmask) information of nested dupsort (multi-value) B+trees - * for given database. +/** Retrieve depth (bitmask) information of nested dupsort (multi-value) + * B+trees for given database. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] dbi A database handle returned by mdbx_dbi_open(). - * [out] mask The address of an uint32_t value where the bitmask - * will be stored. + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [out] mask The address of an uint32_t value where the bitmask + * will be stored. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_EINVAL = an invalid parameter was specified. - * - MDBX_RESULT_TRUE = the dbi isn't a dupsort (multi-value) database. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_THREAD_MISMATCH Given transaction is not owned + * by current thread. + * \retval MDBX_EINVAL An invalid parameter was specified. + * \retval MDBX_RESULT_TRUE The dbi isn't a dupsort (multi-value) database. */ LIBMDBX_API int mdbx_dbi_dupsort_depthmask(MDBX_txn *txn, MDBX_dbi dbi, uint32_t *mask); @@ -2459,24 +2579,23 @@ typedef enum MDBX_dbi_state_t MDBX_dbi_state_t; DEFINE_ENUM_FLAG_OPERATORS(MDBX_dbi_state_t) #endif -/* Retrieve the DB flags and status for a database handle. +/** Retrieve the DB flags and status for a database handle. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] dbi A database handle returned by mdbx_dbi_open(). - * [out] flags Address where the flags will be returned. - * [out] state Address where the state will be returned. + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [out] flags Address where the flags will be returned. + * \param [out] state Address where the state will be returned. * - * Legacy mdbx_dbi_flags() correspond to calling mdbx_dbi_flags_ex() with - * discarding result from the last argument. - * - * Returns A non-zero error value on failure and 0 on success. */ + * \returns A non-zero error value on failure and 0 on success. */ LIBMDBX_API int mdbx_dbi_flags_ex(MDBX_txn *txn, MDBX_dbi dbi, unsigned *flags, unsigned *state); +/** The shortcut to calling mdbx_dbi_flags_ex() with state=NULL for discarding + * it result. */ LIBMDBX_API int mdbx_dbi_flags(MDBX_txn *txn, MDBX_dbi dbi, unsigned *flags); -/* Close a database handle. Normally unnecessary. +/** Close a database handle. Normally unnecessary. * - * NOTE: Use with care. + * \note Use with care. * This call is synchronized via mutex with mdbx_dbi_close(), but NOT with * other transactions running by other threads. The "next" version of libmdbx * (MithrilDB) will solve this issue. @@ -2491,25 +2610,25 @@ LIBMDBX_API int mdbx_dbi_flags(MDBX_txn *txn, MDBX_dbi dbi, unsigned *flags); * the handle value. Usually it's better to set a bigger mdbx_env_set_maxdbs(), * unless that value would be large. * - * [in] env An environment handle returned by mdbx_env_create(). - * [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). * - * Returns A non-zero error value on failure and 0 on success. */ + * \returns A non-zero error value on failure and 0 on success. */ LIBMDBX_API int mdbx_dbi_close(MDBX_env *env, MDBX_dbi dbi); -/* Empty or delete and close a database. +/** Empty or delete and close a database. * * See mdbx_dbi_close() for restrictions about closing the DB handle. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] dbi A database handle returned by mdbx_dbi_open(). - * [in] del 0 to empty the DB, 1 to delete it from the environment - * and close the DB handle. + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [in] del `false` to empty the DB, `true` to delete it + * from the environment and close the DB handle. * - * Returns A non-zero error value on failure and 0 on success. */ + * \returns A non-zero error value on failure and 0 on success. */ LIBMDBX_API int mdbx_drop(MDBX_txn *txn, MDBX_dbi dbi, int del); -/* Get items from a database. +/** Get items from a database. * * This function retrieves key/data pairs from the database. The address * and length of the data associated with the specified key are returned @@ -2518,27 +2637,30 @@ LIBMDBX_API int mdbx_drop(MDBX_txn *txn, MDBX_dbi dbi, int del); * first data item for the key will be returned. Retrieval of other * items requires the use of mdbx_cursor_get(). * - * NOTE: The memory pointed to by the returned values is owned by the + * \note The memory pointed to by the returned values is owned by the * database. The caller need not dispose of the memory, and may not * modify it in any way. For values returned in a read-only transaction * any modification attempts will cause a SIGSEGV. * - * NOTE: Values returned from the database are valid only until a + * \note Values returned from the database are valid only until a * subsequent update operation, or the end of the transaction. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] dbi A database handle returned by mdbx_dbi_open(). - * [in] key The key to search for in the database. - * [in,out] data The data corresponding to the key. + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [in] key The key to search for in the database. + * \param [in,out] data The data corresponding to the key. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_NOTFOUND = the key was not in the database. - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_THREAD_MISMATCH Given transaction is not owned + * by current thread. + * \retval MDBX_NOTFOUND = the key was not in the database. + * \retval MDBX_EINVAL = an invalid parameter was specified. */ LIBMDBX_API int mdbx_get(MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key, MDBX_val *data); -/* Get items from a database and optionaly number of data items for a given key. +/** Get items from a database + * and optionaly number of data items for a given key. * * Briefly this function does the same as mdbx_get() with a few differences: * 1. If values_count is NOT NULL, then returns the count @@ -2546,24 +2668,26 @@ LIBMDBX_API int mdbx_get(MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key, * 2. Updates BOTH the key and the data for pointing to the actual key-value * pair inside the database. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] dbi A database handle returned by mdbx_dbi_open(). - * [in,out] key The key to search for in the database. - * [in,out] data The data corresponding to the key. - * [out] values_count The optional address to return number of values - * associated with given key, i.e. - * = 0 - in case MDBX_NOTFOUND error; - * = 1 - exactly for databases WITHOUT MDBX_DUPSORT; - * >= 1 for databases WITH MDBX_DUPSORT. + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [in,out] key The key to search for in the database. + * \param [in,out] data The data corresponding to the key. + * \param [out] values_count The optional address to return number of values + * associated with given key, i.e. + * = 0 - in case MDBX_NOTFOUND error; + * = 1 - exactly for databases WITHOUT MDBX_DUPSORT; + * >= 1 for databases WITH MDBX_DUPSORT. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_NOTFOUND = the key was not in the database. - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_THREAD_MISMATCH Given transaction is not owned + * by current thread. + * \retval MDBX_NOTFOUND = the key was not in the database. + * \retval MDBX_EINVAL = an invalid parameter was specified. */ LIBMDBX_API int mdbx_get_ex(MDBX_txn *txn, MDBX_dbi dbi, MDBX_val *key, MDBX_val *data, size_t *values_count); -/* Get nearest items from a database. +/** Get nearest items from a database. * * Briefly this function does the same as mdbx_get() with a few differences: * 1. Return nearest (i.e. equal or great due comparison function) key-value @@ -2576,35 +2700,36 @@ LIBMDBX_API int mdbx_get_ex(MDBX_txn *txn, MDBX_dbi dbi, MDBX_val *key, * 3. Updates BOTH the key and the data for pointing to the actual key-value * pair inside the database. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] dbi A database handle returned by mdbx_dbi_open(). - * [in,out] key The key to search for in the database. - * [in,out] data The data corresponding to the key. + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [in,out] key The key to search for in the database. + * \param [in,out] data The data corresponding to the key. * - * Returns A non-zero error value on failure and MDBX_RESULT_TRUE (0) or - * MDBX_RESULT_TRUE on success (as described above). - * Some possible errors are: - * - MDBX_NOTFOUND = the key was not in the database. - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and MDBX_RESULT_TRUE(0) + * or MDBX_RESULT_TRUE(-1) on success (as described above). + * Some possible errors are: + * \retval MDBX_THREAD_MISMATCH Given transaction is not owned + * by current thread. + * \retval MDBX_NOTFOUND = the key was not in the database. + * \retval MDBX_EINVAL = an invalid parameter was specified. */ LIBMDBX_API int mdbx_get_nearest(MDBX_txn *txn, MDBX_dbi dbi, MDBX_val *key, MDBX_val *data); -/* Store items into a database. +/** Store items into a database. * * This function stores key/data pairs in the database. The default behavior * is to enter the new key/data pair, replacing any previously existing key * if duplicates are disallowed, or adding a duplicate data item if * duplicates are allowed (MDBX_DUPSORT). * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] dbi A database handle returned by mdbx_dbi_open(). - * [in] key The key to store in the database. - * [in,out] data The data to store. - * [in] flags Special options for this operation. This parameter must be - * set to 0 or by bitwise OR'ing together one or more of the - * values described here. - * - * - MDBX_NODUPDATA + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [in] key The key to store in the database. + * \param [in,out] data The data to store. + * \param [in] flags Special options for this operation. + * This parameter must be set to 0 or by bitwise OR'ing + * together one or more of the values described here: + * - MDBX_NODUPDATA * Enter the new key/data pair only if it does not already appear * in the database. This flag may only be specified if the database * was opened with MDBX_DUPSORT. The function will return MDBX_KEYEXIST @@ -2640,17 +2765,20 @@ LIBMDBX_API int mdbx_get_nearest(MDBX_txn *txn, MDBX_dbi dbi, MDBX_val *key, * - MDBX_APPENDDUP * As above, but for sorted dup data. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_KEYEXIST - * - MDBX_MAP_FULL = the database is full, see mdbx_env_set_mapsize(). - * - MDBX_TXN_FULL = the transaction has too many dirty pages. - * - MDBX_EACCES = an attempt was made to write in a read-only transaction. - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_THREAD_MISMATCH Given transaction is not owned + * by current thread. + * \retval MDBX_KEYEXIST The key/value pair already exists in the database. + * \retval MDBX_MAP_FULL The database is full, see mdbx_env_set_mapsize(). + * \retval MDBX_TXN_FULL The transaction has too many dirty pages. + * \retval MDBX_EACCES An attempt was made to write + * in a read-only transaction. + * \retval MDBX_EINVAL An invalid parameter was specified. */ LIBMDBX_API int mdbx_put(MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key, MDBX_val *data, unsigned flags); -/* Replace items in a database. +/** Replace items in a database. * * This function allows to update or delete an existing value at the same time * as the previous value is retrieved. If the argument new_data equal is NULL @@ -2671,30 +2799,31 @@ LIBMDBX_API int mdbx_put(MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key, * MDBX_NOOVERWRITE. This combination is chosen because it makes no sense, and * thus allows you to identify the request of such a scenario. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] dbi A database handle returned by mdbx_dbi_open(). - * [in] key The key to store in the database. - * [in,out] new_data The data to store, if NULL then deletion will be - * performed. - * [in,out] old_data The buffer for retrieve previous value as describe - * above. - * [in] flags Special options for this operation. This parameter must - * be set to 0 or by bitwise OR'ing together one or more of - * the values described in mdbx_put() description above, - * and additionally (MDBX_CURRENT | MDBX_NOOVERWRITE) - * combination for selection particular item from - * multi-value/duplicates. + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [in] key The key to store in the database. + * \param [in,out] new_data The data to store, if NULL then deletion will + * be performed. + * \param [in,out] old_data The buffer for retrieve previous value as describe + * above. + * \param [in] flags Special options for this operation. + * This parameter must be set to 0 or by bitwise + * OR'ing together one or more of the values + * described in mdbx_put() description above, + * and additionally (MDBX_CURRENT | MDBX_NOOVERWRITE) + * combination for selection particular item from + * multi-value/duplicates. * - * Returns A non-zero error value on failure and 0 on success. */ + * \returns A non-zero error value on failure and 0 on success. */ LIBMDBX_API int mdbx_replace(MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key, MDBX_val *new_data, MDBX_val *old_data, unsigned flags); -/* Delete items from a database. +/** Delete items from a database. * * This function removes key/data pairs from the database. * - * NOTE: The data parameter is NOT ignored regardless the database does + * \note The data parameter is NOT ignored regardless the database does * support sorted duplicate data items or not. If the data parameter * is non-NULL only the matching data item will be deleted. Otherwise, if data * parameter is NULL, any/all value(s) for specified key will be deleted. @@ -2702,19 +2831,20 @@ LIBMDBX_API int mdbx_replace(MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key, * This function will return MDBX_NOTFOUND if the specified key/data * pair is not in the database. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] dbi A database handle returned by mdbx_dbi_open(). - * [in] key The key to delete from the database. - * [in] data The data to delete. + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [in] key The key to delete from the database. + * \param [in] data The data to delete. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_EACCES = an attempt was made to write in a read-only transaction. - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_EACCES An attempt was made to write + * in a read-only transaction. + * \retval MDBX_EINVAL An invalid parameter was specified. */ LIBMDBX_API int mdbx_del(MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key, const MDBX_val *data); -/* Create a cursor handle. +/** Create a cursor handle. * * A cursor is associated with a specific transaction and database. A cursor * cannot be used when its database handle is closed. Nor when its transaction @@ -2724,66 +2854,70 @@ LIBMDBX_API int mdbx_del(MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key, * A cursor must be closed explicitly always, before or after its transaction * ends. It can be reused with mdbx_cursor_renew() before finally closing it. * - * NOTE: In contrast to LMDB, the MDBX required that any opened cursors can be + * \note In contrast to LMDB, the MDBX required that any opened cursors can be * reused and must be freed explicitly, regardless ones was opened in a * read-only or write transaction. The REASON for this is eliminates ambiguity * which helps to avoid errors such as: use-after-free, double-free, i.e. memory * corruption and segfaults. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] dbi A database handle returned by mdbx_dbi_open(). - * [out] cursor Address where the new MDBX_cursor handle will be stored. + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [out] cursor Address where the new MDBX_cursor handle will be stored. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_THREAD_MISMATCH Given transaction is not owned + * by current thread. + * \retval MDBX_EINVAL An invalid parameter was specified. */ LIBMDBX_API int mdbx_cursor_open(MDBX_txn *txn, MDBX_dbi dbi, MDBX_cursor **cursor); -/* Close a cursor handle. +/** Close a cursor handle. * * The cursor handle will be freed and must not be used again after this call, * but its transaction may still be live. * - * NOTE: In contrast to LMDB, the MDBX required that any opened cursors can be + * \note In contrast to LMDB, the MDBX required that any opened cursors can be * reused and must be freed explicitly, regardless ones was opened in a * read-only or write transaction. The REASON for this is eliminates ambiguity * which helps to avoid errors such as: use-after-free, double-free, i.e. memory * corruption and segfaults. * - * [in] cursor A cursor handle returned by mdbx_cursor_open(). */ + * \param [in] cursor A cursor handle returned by mdbx_cursor_open(). */ LIBMDBX_API void mdbx_cursor_close(MDBX_cursor *cursor); -/* Renew a cursor handle. +/** Renew a cursor handle. * * A cursor is associated with a specific transaction and database. The cursor * may be associated with a new transaction, and referencing the same database * handle as it was created with. This may be done whether the previous * transaction is live or dead. * - * NOTE: In contrast to LMDB, the MDBX allow any cursor to be re-used by using + * \note In contrast to LMDB, the MDBX allow any cursor to be re-used by using * mdbx_cursor_renew(), to avoid unnecessary malloc/free overhead until it freed * by mdbx_cursor_close(). * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] cursor A cursor handle returned by mdbx_cursor_open(). + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] cursor A cursor handle returned by mdbx_cursor_open(). * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_THREAD_MISMATCH Given transaction is not owned + * by current thread. + * \retval MDBX_EINVAL An invalid parameter was specified. */ LIBMDBX_API int mdbx_cursor_renew(MDBX_txn *txn, MDBX_cursor *cursor); -/* Return the cursor's transaction handle. +/** Return the cursor's transaction handle. * - * [in] cursor A cursor handle returned by mdbx_cursor_open(). */ + * \param [in] cursor A cursor handle returned by mdbx_cursor_open(). */ LIBMDBX_API MDBX_txn *mdbx_cursor_txn(const MDBX_cursor *cursor); -/* Return the cursor's database handle. +/** Return the cursor's database handle. * - * [in] cursor A cursor handle returned by mdbx_cursor_open(). */ + * \param [in] cursor A cursor handle returned by mdbx_cursor_open(). */ LIBMDBX_API MDBX_dbi mdbx_cursor_dbi(const MDBX_cursor *cursor); -/* Retrieve by cursor. +/** Retrieve by cursor. * * This function retrieves key/data pairs from the database. The address and * length of the key are returned in the object to which key refers (except @@ -2791,36 +2925,38 @@ LIBMDBX_API MDBX_dbi mdbx_cursor_dbi(const MDBX_cursor *cursor); * and the address and length of the data are returned in the object to which * data refers. See mdbx_get() for restrictions on using the output values. * - * [in] cursor A cursor handle returned by mdbx_cursor_open(). - * [in,out] key The key for a retrieved item. - * [in,out] data The data of a retrieved item. - * [in] op A cursor operation MDBX_cursor_op. + * \param [in] cursor A cursor handle returned by mdbx_cursor_open(). + * \param [in,out] key The key for a retrieved item. + * \param [in,out] data The data of a retrieved item. + * \param [in] op A cursor operation MDBX_cursor_op. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_NOTFOUND = no matching key found. - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_THREAD_MISMATCH Given transaction is not owned + * by current thread. + * \retval MDBX_NOTFOUND No matching key found. + * \retval MDBX_EINVAL An invalid parameter was specified. */ LIBMDBX_API int mdbx_cursor_get(MDBX_cursor *cursor, MDBX_val *key, MDBX_val *data, MDBX_cursor_op op); -/* Store by cursor. +/** Store by cursor. * * This function stores key/data pairs into the database. The cursor is * positioned at the new item, or on failure usually near it. * - * [in] cursor A cursor handle returned by mdbx_cursor_open(). - * [in] key The key operated on. - * [in,out] data The data operated on. - * [in] flags Options for this operation. This parameter - * must be set to 0 or by bitwise OR'ing together one or more of - * the values described here: + * \param [in] cursor A cursor handle returned by mdbx_cursor_open(). + * \param [in] key The key operated on. + * \param [in,out] data The data operated on. + * \param [in] flags Options for this operation. This parameter + * must be set to 0 or by bitwise OR'ing together + * one or more of the values described here: * * - MDBX_CURRENT * Replace the item at the current cursor position. The key parameter * must still be provided, and must match it, otherwise the function * return MDBX_EKEYMISMATCH. * - * NOTE: MDBX allows (unlike LMDB) you to change the size of the data and + * \note MDBX allows (unlike LMDB) you to change the size of the data and * automatically handles reordering for sorted duplicates (MDBX_DUPSORT). * * - MDBX_NODUPDATA @@ -2863,90 +2999,105 @@ LIBMDBX_API int mdbx_cursor_get(MDBX_cursor *cursor, MDBX_val *key, * field will be set to the count of the number of elements actually * written. The iov_base of the second MDBX_val is unused. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_EKEYMISMATCH - * - MDBX_MAP_FULL = the database is full, see mdbx_env_set_mapsize(). - * - MDBX_TXN_FULL = the transaction has too many dirty pages. - * - MDBX_EACCES = an attempt was made to write in a read-only transaction. - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_THREAD_MISMATCH Given transaction is not owned + * by current thread. + * \retval MDBX_EKEYMISMATCH The given key value is mismatched to the current + * cursor position + * \retval MDBX_MAP_FULL The database is full, see mdbx_env_set_mapsize(). + * \retval MDBX_TXN_FULL The transaction has too many dirty pages. + * \retval MDBX_EACCES An attempt was made to write in a read-only + * transaction. + * \retval MDBX_EINVAL An invalid parameter was specified. */ LIBMDBX_API int mdbx_cursor_put(MDBX_cursor *cursor, const MDBX_val *key, MDBX_val *data, unsigned flags); -/* Delete current key/data pair. +/** Delete current key/data pair. * * This function deletes the key/data pair to which the cursor refers. This does * not invalidate the cursor, so operations such as MDBX_NEXT can still be used * on it. Both MDBX_NEXT and MDBX_GET_CURRENT will return the same record after * this operation. * - * [in] cursor A cursor handle returned by mdbx_cursor_open(). - * [in] flags Options for this operation. This parameter must be set to 0 - * or one of the values described here. + * \param [in] cursor A cursor handle returned by mdbx_cursor_open(). + * \param [in] flags Options for this operation. This parameter must be set to + * 0 or one of the values described here. * * - MDBX_NODUPDATA * Delete all of the data items for the current key. This flag has effect * only for database(s) was created with MDBX_DUPSORT. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_EACCES = an attempt was made to write in a read-only transaction. - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_THREAD_MISMATCH Given transaction is not owned + * by current thread. + * \retval MDBX_MAP_FULL The database is full, see mdbx_env_set_mapsize(). + * \retval MDBX_TXN_FULL The transaction has too many dirty pages. + * \retval MDBX_EACCES An attempt was made to write in a read-only + * transaction. + * \retval MDBX_EINVAL An invalid parameter was specified. */ LIBMDBX_API int mdbx_cursor_del(MDBX_cursor *cursor, unsigned flags); -/* Return count of duplicates for current key. +/** Return count of duplicates for current key. * * This call is valid for all databases, but reasonable only for that support * sorted duplicate data items MDBX_DUPSORT. * - * [in] cursor A cursor handle returned by mdbx_cursor_open(). - * [out] countp Address where the count will be stored. + * \param [in] cursor A cursor handle returned by mdbx_cursor_open(). + * \param [out] pcount Address where the count will be stored. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_EINVAL = cursor is not initialized, or an invalid parameter - * was specified. */ -LIBMDBX_API int mdbx_cursor_count(const MDBX_cursor *cursor, size_t *countp); + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_THREAD_MISMATCH Given transaction is not owned + * by current thread. + * \retval MDBX_EINVAL Cursor is not initialized, or an invalid parameter + * was specified. */ +LIBMDBX_API int mdbx_cursor_count(const MDBX_cursor *cursor, size_t *pcount); -/* Determines whether the cursor is pointed to a key-value pair or not, +/** Determines whether the cursor is pointed to a key-value pair or not, * i.e. was not positioned or points to the end of data. * - * [in] cursor A cursor handle returned by mdbx_cursor_open(). + * \param [in] cursor A cursor handle returned by mdbx_cursor_open(). * - * Returns: - * - MDBX_RESULT_TRUE = no more data available or cursor not positioned; - * - MDBX_RESULT_FALSE = data available; - * - Otherwise the error code. */ -LIBMDBX_API int mdbx_cursor_eof(const MDBX_cursor *mc); + * \returns A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, + * otherwise the error code: + * \retval MDBX_RESULT_TRUE No more data available or cursor not + * positioned + * \retval MDBX_RESULT_FALSE A data is available + * \retval Otherwise the error code */ +LIBMDBX_API int mdbx_cursor_eof(const MDBX_cursor *cursor); -/* Determines whether the cursor is pointed to the first key-value pair or not. +/** Determines whether the cursor is pointed to the first key-value pair or not. * - * [in] cursor A cursor handle returned by mdbx_cursor_open(). + * \param [in] cursor A cursor handle returned by mdbx_cursor_open(). * - * Returns: - * - MDBX_RESULT_TRUE = cursor positioned to the first key-value pair. - * - MDBX_RESULT_FALSE = cursor NOT positioned to the first key-value pair. - * - Otherwise the error code. */ -LIBMDBX_API int mdbx_cursor_on_first(const MDBX_cursor *mc); + * \returns A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, + * otherwise the error code: + * \retval MDBX_RESULT_TRUE Cursor positioned to the first key-value pair + * \retval MDBX_RESULT_FALSE Cursor NOT positioned to the first key-value pair + * \retval Otherwise the error code */ +LIBMDBX_API int mdbx_cursor_on_first(const MDBX_cursor *cursor); -/* Determines whether the cursor is pointed to the last key-value pair or not. +/** Determines whether the cursor is pointed to the last key-value pair or not. * - * [in] cursor A cursor handle returned by mdbx_cursor_open(). + * \param [in] cursor A cursor handle returned by mdbx_cursor_open(). * - * Returns: - * - MDBX_RESULT_TRUE = cursor positioned to the last key-value pair. - * - MDBX_RESULT_FALSE = cursor NOT positioned to the last key-value pair. - * - Otherwise the error code. */ -LIBMDBX_API int mdbx_cursor_on_last(const MDBX_cursor *mc); + * \returns A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, + * otherwise the error code: + * \retval MDBX_RESULT_TRUE Cursor positioned to the last key-value pair + * \retval MDBX_RESULT_FALSE Cursor NOT positioned to the last key-value pair + * \retval Otherwise the error code */ +LIBMDBX_API int mdbx_cursor_on_last(const MDBX_cursor *cursor); -/* Estimates the distance between cursors as a number of elements. The results +/** Estimates the distance between cursors as a number of elements. The results * of such estimation can be used to build and/or optimize query execution * plans. * * This function performs a rough estimate based only on b-tree pages that are * common for the both cursor's stacks. * - * NOTE: The result varies greatly depending on the filling of specific pages + * \note The result varies greatly depending on the filling of specific pages * and the overall balance of the b-tree: * * 1. The number of items is estimated by analyzing the height and fullness of @@ -2973,61 +3124,64 @@ LIBMDBX_API int mdbx_cursor_on_last(const MDBX_cursor *mc); * Both cursors must be initialized for the same database and the same * transaction. * - * [in] first The first cursor for estimation. - * [in] last The second cursor for estimation. - * [out] distance_items A pointer to store estimated distance value, - * i.e. *distance_items = distance(first, last). + * \param [in] first The first cursor for estimation. + * \param [in] last The second cursor for estimation. + * \param [out] distance_items The pointer to store estimated distance value, + * i.e. *distance_items = distance(first, last). * - * Returns A non-zero error value on failure and 0 on success. */ + * \returns A non-zero error value on failure and 0 on success. */ LIBMDBX_API int mdbx_estimate_distance(const MDBX_cursor *first, const MDBX_cursor *last, ptrdiff_t *distance_items); -/* Estimates the move distance, i.e. between the current cursor position and +/** Estimates the move distance, i.e. between the current cursor position and * next position after the specified move-operation with given key and data. * The results of such estimation can be used to build and/or optimize query * execution plans. Current cursor position and state are preserved. * * Please see notes on accuracy of the result in mdbx_estimate_distance() - * description above. + * description. * - * [in] cursor Cursor for estimation. - * [in,out] key The key for a retrieved item. - * [in,out] data The data of a retrieved item. - * [in] op A cursor operation MDBX_cursor_op. - * [out] distance_items A pointer to store estimated move distance - * as the number of elements. + * \param [in] cursor Cursor for estimation. + * \param [in,out] key The key for a retrieved item. + * \param [in,out] data The data of a retrieved item. + * \param [in] move_op A cursor operation MDBX_cursor_op. + * \param [out] distance_items A pointer to store estimated move distance + * as the number of elements. * - * Returns A non-zero error value on failure and 0 on success. */ + * \returns A non-zero error value on failure and 0 on success. */ LIBMDBX_API int mdbx_estimate_move(const MDBX_cursor *cursor, MDBX_val *key, MDBX_val *data, MDBX_cursor_op move_op, ptrdiff_t *distance_items); -/* Estimates the size of a range as a number of elements. The results +/** Estimates the size of a range as a number of elements. The results * of such estimation can be used to build and/or optimize query execution * plans. * * Please see notes on accuracy of the result in mdbx_estimate_distance() - * description above. + * description. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] dbi A database handle returned by mdbx_dbi_open(). - * [in] begin_key The key of range beginning or NULL for explicit FIRST. - * [in] begin_data Optional additional data to seeking among sorted - * duplicates. Only for MDBX_DUPSORT, NULL otherwise. - * [in] end_key The key of range ending or NULL for explicit LAST. - * [in] end_data Optional additional data to seeking among sorted - * duplicates. Only for MDBX_DUPSORT, NULL otherwise. - * [out] distance_items A pointer to store range estimation result. + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [in] begin_key The key of range beginning + * or NULL for explicit FIRST. + * \param [in] begin_data Optional additional data to seeking among sorted + * duplicates. Only for MDBX_DUPSORT, NULL otherwise. + * \param [in] end_key The key of range ending or NULL for explicit LAST. + * \param [in] end_data Optional additional data to seeking among sorted + * duplicates. Only for MDBX_DUPSORT, NULL otherwise. + * \param [out] distance_items A pointer to store range estimation result. * - * Returns A non-zero error value on failure and 0 on success. */ -#define MDBX_EPSILON ((MDBX_val *)((ptrdiff_t)-1)) + * \returns A non-zero error value on failure and 0 on success. */ LIBMDBX_API int mdbx_estimate_range(MDBX_txn *txn, MDBX_dbi dbi, MDBX_val *begin_key, MDBX_val *begin_data, MDBX_val *end_key, MDBX_val *end_data, - ptrdiff_t *size_items); + ptrdiff_t *distance_items); -/* Determines whether the given address is on a dirty database page of the +/** The EPSILON value for mdbx_estimate_range() */ +#define MDBX_EPSILON ((MDBX_val *)((ptrdiff_t)-1)) + +/** Determines whether the given address is on a dirty database page of the * transaction or not. Ultimately, this allows to avoid copy data from non-dirty * pages. * @@ -3042,24 +3196,25 @@ LIBMDBX_API int mdbx_estimate_range(MDBX_txn *txn, MDBX_dbi dbi, * validation stage. Thus, mdbx_is_dirty() allows you to get rid of unnecessary * copying, and perform a more complete check of the arguments. * - * NOTE: The address passed must point to the beginning of the data. This is the + * \note The address passed must point to the beginning of the data. This is the * only way to ensure that the actual page header is physically located in the * same memory page, including for multi-pages with long data. * - * NOTE: In rare cases the function may return a false positive answer + * \note In rare cases the function may return a false positive answer * (DBX_RESULT_TRUE when data is NOT on a dirty page), but never a false * negative if the arguments are correct. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] ptr The address of data to check. + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] ptr The address of data to check. * - * Returns: - * - MDBX_RESULT_TRUE = given address is on the dirty page. - * - MDBX_RESULT_FALSE = given address is NOT on the dirty page. - * - Otherwise the error code. */ + * \returns A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, + * otherwise the error code: + * \retval MDBX_RESULT_TRUE Given address is on the dirty page. + * \retval MDBX_RESULT_FALSE Given address is NOT on the dirty page. + * \retval Otherwise the error code. */ LIBMDBX_API int mdbx_is_dirty(const MDBX_txn *txn, const void *ptr); -/* Sequence generation for a database. +/** Sequence generation for a database. * * The function allows to create a linear sequence of unique positive integers * for each database. The function can be called for a read transaction to @@ -3067,110 +3222,123 @@ LIBMDBX_API int mdbx_is_dirty(const MDBX_txn *txn, const void *ptr); * Sequence changes become visible outside the current write transaction after * it is committed, and discarded on abort. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] dbi A database handle returned by mdbx_dbi_open(). - * [out] result The optional address where the value of sequence before the - * change will be stored. - * [in] increment Value to increase the sequence, - * must be 0 for read-only transactions. + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [out] result The optional address where the value of sequence + * before the change will be stored. + * \param [in] increment Value to increase the sequence, + * must be 0 for read-only transactions. * - * Returns A non-zero error value on failure and 0 on success, - * some possible errors are: - * - MDBX_RESULT_TRUE = Increasing the sequence has resulted in an overflow - * and therefore cannot be executed. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_RESULT_TRUE Increasing the sequence has resulted in an + * overflow and therefore cannot be executed. */ LIBMDBX_API int mdbx_dbi_sequence(MDBX_txn *txn, MDBX_dbi dbi, uint64_t *result, uint64_t increment); -/* Compare two data items according to a particular database. +/** Compare two data items according to a particular database. * * This returns a comparison as if the two data items were keys in the * specified database. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] dbi A database handle returned by mdbx_dbi_open(). - * [in] a The first item to compare. - * [in] b The second item to compare. + * \warning There ss a Undefined behavior if one of arguments is invalid. * - * Returns < 0 if a < b, 0 if a == b, > 0 if a > b */ + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [in] a The first item to compare. + * \param [in] b The second item to compare. + * + * \returns < 0 if a < b, 0 if a == b, > 0 if a > b */ LIBMDBX_API int mdbx_cmp(const MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *a, const MDBX_val *b); + +/** Returns default internal key's comparator for given database flags */ LIBMDBX_API MDBX_cmp_func *mdbx_get_keycmp(unsigned flags); -/* Compare two data items according to a particular database. +/** Compare two data items according to a particular database. * * This returns a comparison as if the two items were data items of the - * specified database. The database must have the MDBX_DUPSORT flag. + * specified database. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] dbi A database handle returned by mdbx_dbi_open(). - * [in] a The first item to compare. - * [in] b The second item to compare. + * \warning There ss a Undefined behavior if one of arguments is invalid. * - * Returns < 0 if a < b, 0 if a == b, > 0 if a > b */ + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [in] a The first item to compare. + * \param [in] b The second item to compare. + * + * \returns < 0 if a < b, 0 if a == b, > 0 if a > b */ LIBMDBX_API int mdbx_dcmp(const MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *a, const MDBX_val *b); + +/** Returns default internal data's comparator for given database flags */ LIBMDBX_API MDBX_cmp_func *mdbx_get_datacmp(unsigned flags); -/* A callback function used to enumerate the reader lock table. +/** A callback function used to enumerate the reader lock table. * - * [in] ctx An arbitrary context pointer for the callback. - * [in] num The serial number during enumeration, starting from 1. - * [in] slot The reader lock table slot number. - * [in] txnid The ID of the transaction being read, - * i.e. the MVCC-snaphot number. - * [in] lag The lag from a recent MVCC-snapshot, i.e. the number of - * committed transaction since read transaction started. - * [in] pid The reader process ID. - * [in] thread The reader thread ID. - * [in] bytes_used The number of last used page in the MVCC-snapshot which - * being read, i.e. database file can't shrinked beyond this. - * [in] bytes_retired The total size of the database pages that were retired by - * committed write transactions after the reader's - * MVCC-snapshot, i.e. the space which would be freed after - * the Reader releases the MVCC-snapshot for reuse by - * completion read transaction. + * \param [in] ctx An arbitrary context pointer for the callback. + * \param [in] num The serial number during enumeration, + * starting from 1. + * \param [in] slot The reader lock table slot number. + * \param [in] txnid The ID of the transaction being read, + * i.e. the MVCC-snaphot number. + * \param [in] lag The lag from a recent MVCC-snapshot, + * i.e. the number of committed write transactions + * since the current read transaction started. + * \param [in] pid The reader process ID. + * \param [in] thread The reader thread ID. + * \param [in] bytes_used The number of last used page in the MVCC-snapshot + * which being read, + * i.e. database file can't shrinked beyond this. + * \param [in] bytes_retired The total size of the database pages that were + * retired by committed write transactions after + * the reader's MVCC-snapshot, + * i.e. the space which would be freed after + * the Reader releases the MVCC-snapshot + * for reuse by completion read transaction. * - * Returns < 0 on failure, >= 0 on success. */ + * \returns < 0 on failure, >= 0 on success. */ typedef int(MDBX_reader_list_func)(void *ctx, int num, int slot, mdbx_pid_t pid, mdbx_tid_t thread, uint64_t txnid, uint64_t lag, size_t bytes_used, size_t bytes_retained); -/* Enumarete the entries in the reader lock table. +/** Enumarete the entries in the reader lock table. * - * [in] env An environment handle returned by mdbx_env_create(). - * [in] func A MDBX_reader_list_func function. - * [in] ctx An arbitrary context pointer for the enumeration function. + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [in] func A MDBX_reader_list_func function. + * \param [in] ctx An arbitrary context pointer for the enumeration + * function. * - * Returns A non-zero error value on failure and 0 on success, + * \returns A non-zero error value on failure and 0 on success, * or MDBX_RESULT_TRUE (-1) if the reader lock table is empty. */ LIBMDBX_API int mdbx_reader_list(const MDBX_env *env, MDBX_reader_list_func *func, void *ctx); -/* Check for stale entries in the reader lock table. +/** Check for stale entries in the reader lock table. * - * [in] env An environment handle returned by mdbx_env_create(). - * [out] dead Number of stale slots that were cleared. + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [out] dead Number of stale slots that were cleared. * - * Returns A non-zero error value on failure and 0 on success, + * \returns A non-zero error value on failure and 0 on success, * or MDBX_RESULT_TRUE (-1) if a dead reader(s) found or mutex was recovered. */ LIBMDBX_API int mdbx_reader_check(MDBX_env *env, int *dead); -/* Returns a lag of the reading for the given transaction. +/** Returns a lag of the reading for the given transaction. * * Returns an information for estimate how much given read-only * transaction is lagging relative the to actual head. * This is deprecated function, use mdbx_txn_info() instead. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [out] percent Percentage of page allocation in the database. + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [out] percent Percentage of page allocation in the database. * - * Returns Number of transactions committed after the given was started for - * read, or negative value on failure. */ + * \returns Number of transactions committed after the given was started for + * read, or negative value on failure. */ MDBX_DEPRECATED LIBMDBX_API int mdbx_txn_straggler(const MDBX_txn *txn, int *percent); -/* A lack-of-space callback function to resolve issues with a laggard readers. +/** A lack-of-space callback function to resolve issues with a laggard readers. * * Read transactions prevent reuse of pages freed by newer write transactions, * thus the database can grow quickly. This callback will be called when there @@ -3183,69 +3351,72 @@ MDBX_DEPRECATED LIBMDBX_API int mdbx_txn_straggler(const MDBX_txn *txn, * action. In doing so it is important that the returned code always corresponds * to the performed action. * - * [in] env An environment handle returned by mdbx_env_create(). - * [in] pid A pid of the reader process. - * [in] tid A thread_id of the reader thread. - * [in] txn A transaction number on which stalled. - * [in] gap A lag from the last commited txn. - * [in] space A space that actually become available for reuse after this - * reader finished. The callback function can take this value into - * account to evaluate the impact that a long-running transaction - * has. - * [in] retry A retry number starting from 0. if callback has returned 0 - * at least once, then at end of current OOM-handler loop callback - * will be called additionally with negative value to notify about - * the end of loop. The callback function can use this value to - * implement timeout logic while waiting for readers. + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [in] pid A pid of the reader process. + * \param [in] tid A thread_id of the reader thread. + * \param [in] txn A transaction number on which stalled. + * \param [in] gap A lag from the last commited txn. + * \param [in] space A space that actually become available for reuse after + * this reader finished. The callback function can take + * this value into account to evaluate the impact that + * a long-running transaction has. + * \param [in] retry A retry number starting from 0. + * If callback has returned 0 at least once, then at end + * of current OOM-handler loop callback will be called + * additionally with negative value to notify about the + * end of loop. The callback function can use this value + * to implement timeout logic while waiting for readers. * - * The RETURN CODE determines the further actions libmdbx and must match the - * action which was executed by the callback: + * \returns The RETURN CODE determines the further actions libmdbx and must + * match the action which was executed by the callback: * - * -2 or less = An error condition and the reader was not killed. + * \retval -2 or less An error condition and the reader was not killed. * - * -1 = The callback was unable to solve the problem and agreed - * on MDBX_MAP_FULL error, libmdbx should increase the - * database size or return MDBX_MAP_FULL error. + * \retval -1 The callback was unable to solve the problem and + * agreed on MDBX_MAP_FULL error; + * libmdbx should increase the database size or + * return MDBX_MAP_FULL error. * - * 0 (zero) = The callback solved the problem or just waited for + * \retval 0 (zero) The callback solved the problem or just waited for * a while, libmdbx should rescan the reader lock table and * retry. This also includes a situation when corresponding * transaction terminated in normal way by mdbx_txn_abort() * or mdbx_txn_reset(), and my be restarted. I.e. reader * slot don't needed to be cleaned from transaction. * - * 1 = Transaction aborted asynchronous and reader slot should - * be cleared immediately, i.e. read transaction will not - * continue but mdbx_txn_abort() or mdbx_txn_reset() will - * be called later. + * \retval 1 Transaction aborted asynchronous and reader slot + * should be cleared immediately, i.e. read transaction + * will not continue but mdbx_txn_abort() + * or mdbx_txn_reset() will be called later. * - * 2 or great = The reader process was terminated or killed, and libmdbx - * should entirely reset reader registration. */ + * \retval 2 or great The reader process was terminated or killed, + * and libmdbx should entirely reset reader registration. */ typedef int(MDBX_oom_func)(MDBX_env *env, mdbx_pid_t pid, mdbx_tid_t tid, uint64_t txn, unsigned gap, size_t space, int retry); -/* Set the OOM callback. +/** Set the OOM callback. * * The callback will only be triggered on lack of space to resolve issues with * lagging reader(s) (i.e. to kill it) for resume reuse pages from the garbage * collector. * - * [in] env An environment handle returned by mdbx_env_create(). - * [in] oom_func A MDBX_oom_func function or NULL to disable. + * \param [in] env An environment handle returned by mdbx_env_create(). + * \param [in] oom_func A MDBX_oom_func function or NULL to disable. * - * Returns A non-zero error value on failure and 0 on success. */ + * \returns A non-zero error value on failure and 0 on success. */ LIBMDBX_API int mdbx_env_set_oomfunc(MDBX_env *env, MDBX_oom_func *oom_func); -/* Get the current oom_func callback. +/** Get the current oom_func callback. * - * [in] env An environment handle returned by mdbx_env_create(). + * \param [in] env An environment handle returned by mdbx_env_create(). * - * Returns A MDBX_oom_func function or NULL if disabled. */ + * \returns A MDBX_oom_func function or NULL if disabled. */ LIBMDBX_API MDBX_oom_func *mdbx_env_get_oomfunc(const MDBX_env *env); -/**** B-tree Traversal ********************************************************* +/** \defgroup btree_traversal B-tree Traversal * This is internal API for mdbx_chk tool. You should avoid to use it, except - * some extremal special cases. */ + * some extremal special cases. + * @{ */ /** Page types for traverse the b-tree. */ enum MDBX_page_type_t { @@ -3262,11 +3433,14 @@ enum MDBX_page_type_t { typedef enum MDBX_page_type_t MDBX_page_type_t; #endif +/** Pseudo-name for MainDB */ #define MDBX_PGWALK_MAIN ((const char *)((ptrdiff_t)0)) +/** Pseudo-name for GarbageCollectorDB */ #define MDBX_PGWALK_GC ((const char *)((ptrdiff_t)-1)) +/** Pseudo-name for MetaPages */ #define MDBX_PGWALK_META ((const char *)((ptrdiff_t)-2)) -/* Callback function for traverse the b-tree. */ +/** Callback function for traverse the b-tree. */ typedef int MDBX_pgvisitor_func(const uint64_t pgno, const unsigned number, void *const ctx, const int deep, const char *const dbi, @@ -3274,29 +3448,31 @@ MDBX_pgvisitor_func(const uint64_t pgno, const unsigned number, void *const ctx, const size_t nentries, const size_t payload_bytes, const size_t header_bytes, const size_t unused_bytes); -/* B-tree traversal function. */ +/** B-tree traversal function. */ LIBMDBX_API int mdbx_env_pgwalk(MDBX_txn *txn, MDBX_pgvisitor_func *visitor, void *ctx, int dont_check_keys_ordering); +/** @} B-tree Traversal */ /**** Attribute support functions for Nexenta *********************************/ -#ifdef MDBX_NEXENTA_ATTRS +#if defined(MDBX_NEXENTA_ATTRS) || defined(DOXYGEN) +/** \defgroup nexenta Attribute support functions for Nexenta + * @{ */ typedef uint_fast64_t mdbx_attr_t; -/* Store by cursor with attribute. +/** Store by cursor with attribute. * * This function stores key/data pairs into the database. The cursor is * positioned at the new item, or on failure usually near it. * - * NOTE: Internally based on MDBX_RESERVE feature, + * \note Internally based on MDBX_RESERVE feature, * therefore doesn't support MDBX_DUPSORT. * - * [in] cursor A cursor handle returned by mdbx_cursor_open() - * [in] key The key operated on. - * [in] data The data operated on. - * [in] attr The attribute. - * [in] flags Options for this operation. This parameter must be set to 0 - * or one of the values described here: - * + * \param [in] cursor A cursor handle returned by mdbx_cursor_open() + * \param [in] key The key operated on. + * \param [in] data The data operated on. + * \param [in] attr The attribute. + * \param [in] flags Options for this operation. This parameter must be set to + * 0 or one of the values described here: * - MDBX_CURRENT * Replace the item at the current cursor position. The key parameter * must still be provided, and must match it, otherwise the function @@ -3308,35 +3484,35 @@ typedef uint_fast64_t mdbx_attr_t; * keys are already known to be in the correct order. Loading unsorted * keys with this flag will cause a MDBX_KEYEXIST error. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_EKEYMISMATCH - * - MDBX_MAP_FULL = the database is full, see mdbx_env_set_mapsize(). - * - MDBX_TXN_FULL = the transaction has too many dirty pages. - * - MDBX_EACCES = an attempt was made to write in a read-only transaction. - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_EKEYMISMATCH + * \retval MDBX_MAP_FULL The database is full, see mdbx_env_set_mapsize(). + * \retval MDBX_TXN_FULL The transaction has too many dirty pages. + * \retval MDBX_EACCES An attempt was made to write in a read-only + * transaction. + * \retval MDBX_EINVAL an invalid parameter was specified. */ LIBMDBX_API int mdbx_cursor_put_attr(MDBX_cursor *cursor, MDBX_val *key, MDBX_val *data, mdbx_attr_t attr, unsigned flags); -/* Store items and attributes into a database. +/** Store items and attributes into a database. * * This function stores key/data pairs in the database. The default behavior * is to enter the new key/data pair, replacing any previously existing key * if duplicates are disallowed. * - * NOTE: Internally based on MDBX_RESERVE feature, + * \note Internally based on MDBX_RESERVE feature, * therefore doesn't support MDBX_DUPSORT. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] dbi A database handle returned by mdbx_dbi_open(). - * [in] key The key to store in the database. - * [in] attr The attribute to store in the database. - * [in,out] data The data to store. - * [in] flags Special options for this operation. This parameter must be - * set to 0 or by bitwise OR'ing together one or more of the - * values described here: - * + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [in] key The key to store in the database. + * \param [in] attr The attribute to store in the database. + * \param [in,out] data The data to store. + * \param [in] flags Special options for this operation. This parameter must + * be set to 0 or by bitwise OR'ing together one + * or more of the values described here: * - MDBX_NOOVERWRITE * Enter the new key/data pair only if the key does not already appear * in the database. The function will return MDBX_KEYEXIST if the key @@ -3354,37 +3530,38 @@ LIBMDBX_API int mdbx_cursor_put_attr(MDBX_cursor *cursor, MDBX_val *key, * correct order. Loading unsorted keys with this flag will cause * a MDBX_EKEYMISMATCH error. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_KEYEXIST - * - MDBX_MAP_FULL = the database is full, see mdbx_env_set_mapsize(). - * - MDBX_TXN_FULL = the transaction has too many dirty pages. - * - MDBX_EACCES = an attempt was made to write in a read-only transaction. - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_KEYEXIST + * \retval MDBX_MAP_FULL The database is full, see mdbx_env_set_mapsize(). + * \retval MDBX_TXN_FULL The transaction has too many dirty pages. + * \retval MDBX_EACCES An attempt was made to write + * in a read-only transaction. + * \retval MDBX_EINVAL An invalid parameter was specified. */ LIBMDBX_API int mdbx_put_attr(MDBX_txn *txn, MDBX_dbi dbi, MDBX_val *key, MDBX_val *data, mdbx_attr_t attr, unsigned flags); -/* Set items attribute from a database. +/** Set items attribute from a database. * * This function stores key/data pairs attribute to the database. * - * NOTE: Internally based on MDBX_RESERVE feature, + * \note Internally based on MDBX_RESERVE feature, * therefore doesn't support MDBX_DUPSORT. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] dbi A database handle returned by mdbx_dbi_open(). - * [in] key The key to search for in the database. - * [in] data The data to be stored or NULL to save previous value. - * [in] attr The attribute to be stored. + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [in] key The key to search for in the database. + * \param [in] data The data to be stored or NULL to save previous value. + * \param [in] attr The attribute to be stored. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_NOTFOUND = the key-value pair was not in the database. - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_NOTFOUND The key-value pair was not in the database. + * \retval MDBX_EINVAL An invalid parameter was specified. */ LIBMDBX_API int mdbx_set_attr(MDBX_txn *txn, MDBX_dbi dbi, MDBX_val *key, MDBX_val *data, mdbx_attr_t attr); -/* Get items attribute from a database cursor. +/** Get items attribute from a database cursor. * * This function retrieves key/data pairs from the database. The address and * length of the key are returned in the object to which key refers (except @@ -3392,20 +3569,21 @@ LIBMDBX_API int mdbx_set_attr(MDBX_txn *txn, MDBX_dbi dbi, MDBX_val *key, * and the address and length of the data are returned in the object to which * data refers. See mdbx_get() for restrictions on using the output values. * - * [in] cursor A cursor handle returned by mdbx_cursor_open(). - * [in,out] key The key for a retrieved item. - * [in,out] data The data of a retrieved item. - * [in] op A cursor operation MDBX_cursor_op. + * \param [in] cursor A cursor handle returned by mdbx_cursor_open(). + * \param [in,out] key The key for a retrieved item. + * \param [in,out] data The data of a retrieved item. + * \param [out] pattr The pointer to retrieve attribute. + * \param [in] op A cursor operation MDBX_cursor_op. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_NOTFOUND = no matching key found. - * - MDBX_EINVAL = an invalid parameter was specified. */ -LIBMDBX_API int mdbx_cursor_get_attr(MDBX_cursor *mc, MDBX_val *key, - MDBX_val *data, mdbx_attr_t *attrptr, + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_NOTFOUND No matching key found. + * \retval MDBX_EINVAL An invalid parameter was specified. */ +LIBMDBX_API int mdbx_cursor_get_attr(MDBX_cursor *cursor, MDBX_val *key, + MDBX_val *data, mdbx_attr_t *pattr, MDBX_cursor_op op); -/* Get items attribute from a database. +/** Get items attribute from a database. * * This function retrieves key/data pairs from the database. The address * and length of the data associated with the specified key are returned @@ -3414,25 +3592,27 @@ LIBMDBX_API int mdbx_cursor_get_attr(MDBX_cursor *mc, MDBX_val *key, * first data item for the key will be returned. Retrieval of other * items requires the use of mdbx_cursor_get(). * - * NOTE: The memory pointed to by the returned values is owned by the + * \note The memory pointed to by the returned values is owned by the * database. The caller need not dispose of the memory, and may not * modify it in any way. For values returned in a read-only transaction * any modification attempts will cause a SIGSEGV. * - * NOTE: Values returned from the database are valid only until a + * \note Values returned from the database are valid only until a * subsequent update operation, or the end of the transaction. * - * [in] txn A transaction handle returned by mdbx_txn_begin(). - * [in] dbi A database handle returned by mdbx_dbi_open(). - * [in] key The key to search for in the database. - * [in,out] data The data corresponding to the key. + * \param [in] txn A transaction handle returned by mdbx_txn_begin(). + * \param [in] dbi A database handle returned by mdbx_dbi_open(). + * \param [in] key The key to search for in the database. + * \param [in,out] data The data corresponding to the key. + * \param [out] pattr The pointer to retrieve attribute. * - * Returns A non-zero error value on failure and 0 on success, some - * possible errors are: - * - MDBX_NOTFOUND = the key was not in the database. - * - MDBX_EINVAL = an invalid parameter was specified. */ + * \returns A non-zero error value on failure and 0 on success, + * some possible errors are: + * \retval MDBX_NOTFOUND The key was not in the database. + * \retval MDBX_EINVAL An invalid parameter was specified. */ LIBMDBX_API int mdbx_get_attr(MDBX_txn *txn, MDBX_dbi dbi, MDBX_val *key, - MDBX_val *data, mdbx_attr_t *attrptr); + MDBX_val *data, mdbx_attr_t *pattr); +/** @} The end of Attribute support functions for Nexenta */ #endif /* MDBX_NEXENTA_ATTRS */ /** @} The end of C API */ diff --git a/src/core.c b/src/core.c index 4b78aae4..fa2d81af 100644 --- a/src/core.c +++ b/src/core.c @@ -15708,7 +15708,7 @@ static int __cold mdbx_env_compact(MDBX_env *env, MDBX_txn *read_txn, MDBX_meta *const meta = mdbx_init_metas(env, buffer); mdbx_meta_set_txnid(env, meta, read_txn->mt_txnid); - if (flags & MDBX_CP_FORCE_RESIZEABLE) + if (flags & MDBX_CP_FORCE_DYNAMIC_SIZE) make_sizeable(meta); /* copy canary sequenses if present */ @@ -15864,7 +15864,7 @@ static int __cold mdbx_env_copy_asis(MDBX_env *env, MDBX_txn *read_txn, (MDBX_meta *)(buffer + ((uint8_t *)mdbx_meta_head(env) - env->me_map)); mdbx_txn_unlock(env); - if (flags & MDBX_CP_FORCE_RESIZEABLE) + if (flags & MDBX_CP_FORCE_DYNAMIC_SIZE) make_sizeable(headcopy); /* Update signature to steady */ headcopy->mm_datasync_sign = mdbx_meta_sign(headcopy); @@ -17666,7 +17666,7 @@ int __cold mdbx_env_pgwalk(MDBX_txn *txn, MDBX_pgvisitor_func *visitor, return rc; } -int mdbx_canary_put(MDBX_txn *txn, const mdbx_canary *canary) { +int mdbx_canary_put(MDBX_txn *txn, const MDBX_canary *canary) { int rc = check_txn_rw(txn, MDBX_TXN_BLOCKED); if (unlikely(rc != MDBX_SUCCESS)) return rc; @@ -17685,7 +17685,7 @@ int mdbx_canary_put(MDBX_txn *txn, const mdbx_canary *canary) { return MDBX_SUCCESS; } -int mdbx_canary_get(const MDBX_txn *txn, mdbx_canary *canary) { +int mdbx_canary_get(const MDBX_txn *txn, MDBX_canary *canary) { int rc = check_txn(txn, MDBX_TXN_BLOCKED); if (unlikely(rc != MDBX_SUCCESS)) return rc; diff --git a/src/internals.h b/src/internals.h index e6cb21b6..4795e534 100644 --- a/src/internals.h +++ b/src/internals.h @@ -304,7 +304,7 @@ typedef struct MDBX_meta { #define mm_psize mm_dbs[FREE_DBI].md_xsize /* Any persistent environment flags, see mdbx_env */ #define mm_flags mm_dbs[FREE_DBI].md_flags - mdbx_canary mm_canary; + MDBX_canary mm_canary; #define MDBX_DATASIGN_NONE 0u #define MDBX_DATASIGN_WEAK 1u @@ -770,7 +770,7 @@ struct MDBX_txn { * don't decrement it when individual DB handles are closed. */ MDBX_dbi mt_numdbs; size_t mt_owner; /* thread ID that owns this transaction */ - mdbx_canary mt_canary; + MDBX_canary mt_canary; union { struct { diff --git a/src/mdbx_dump.c b/src/mdbx_dump.c index b921a813..e5ae3283 100644 --- a/src/mdbx_dump.c +++ b/src/mdbx_dump.c @@ -138,7 +138,7 @@ static int dump_sdb(MDBX_txn *txn, MDBX_dbi dbi, char *name) { printf("mapsize=%" PRIu64 "\n", info.mi_geo.upper); printf("maxreaders=%u\n", info.mi_maxreaders); - mdbx_canary canary; + MDBX_canary canary; rc = mdbx_canary_get(txn, &canary); if (unlikely(rc != MDBX_SUCCESS)) { error("mdbx_canary_get", rc); diff --git a/src/mdbx_load.c b/src/mdbx_load.c index 53e5c08d..bcd5a30f 100644 --- a/src/mdbx_load.c +++ b/src/mdbx_load.c @@ -109,7 +109,7 @@ static char *subname = nullptr; static int dbi_flags; static txnid_t txnid; static uint64_t sequence; -static mdbx_canary canary; +static MDBX_canary canary; static MDBX_envinfo envinfo; #define PRINT 1 diff --git a/test/test.cc b/test/test.cc index 9af04ac9..272a50b5 100644 --- a/test/test.cc +++ b/test/test.cc @@ -411,7 +411,7 @@ bool testcase::should_continue(bool check_timeout_only) const { } void testcase::fetch_canary() { - mdbx_canary canary_now; + MDBX_canary canary_now; log_trace(">> fetch_canary"); int rc = mdbx_canary_get(txn_guard.get(), &canary_now); @@ -434,7 +434,7 @@ void testcase::fetch_canary() { } void testcase::update_canary(uint64_t increment) { - mdbx_canary canary_now = last.canary; + MDBX_canary canary_now = last.canary; log_trace(">> update_canary: sequence %" PRIu64 " += %" PRIu64, canary_now.y, increment); diff --git a/test/test.h b/test/test.h index 43c6c038..babbdd92 100644 --- a/test/test.h +++ b/test/test.h @@ -155,7 +155,7 @@ protected: keygen::maker keyvalue_maker; struct { - mdbx_canary canary; + MDBX_canary canary; } last; SET speculum{ItemCompare(this)}, speculum_commited{ItemCompare(this)};