ISAR/libmdbx
3
0
Fork 0
mirror of https://github.com/isar/libmdbx.git synced 2025-01-30 22:47:16 +08:00
Code Issues Packages Projects Releases Wiki Activity

mdbx-docs: fix typos & add refs for Doxygen.

Browse Source
This commit is contained in:
Leonid Yuriev 2020-07-29 16:56:27 +03:00
parent dcd61289d8
commit 67d27c81d7
1 changed files with 59 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

103
mdbx.h
View File

@ -399,7 +399,7 @@ struct MDBX_cursor;
* update operation, or the end of the transaction. Do not modify or * update operation, or the end of the transaction. Do not modify or
* free them, they commonly point into the database itself. * free them, they commonly point into the database itself.
* *
* Key sizes must be between 0 and mdbx_env_get_maxkeysize() inclusive. * Key sizes must be between 0 and \ref mdbx_env_get_maxkeysize() inclusive.
* The same applies to data sizes in databases with the \ref MDBX_DUPSORT flag. * The same applies to data sizes in databases with the \ref MDBX_DUPSORT flag.
* Other data items can in theory be from 0 to \ref MDBX_MAXDATASIZE bytes long. * Other data items can in theory be from 0 to \ref MDBX_MAXDATASIZE bytes long.
* *
@ -490,7 +490,7 @@ enum MDBX_log_level_t {
and all other log-messages */ and all other log-messages */
MDBX_LOG_EXTRA = 7, MDBX_LOG_EXTRA = 7,
/** for mdbx_setup_debug() only: Don't change current settings */ /** for \ref mdbx_setup_debug() only: Don't change current settings */
MDBX_LOG_DONTCHANGE = -1 MDBX_LOG_DONTCHANGE = -1
}; };
#ifndef __cplusplus #ifndef __cplusplus
@ -537,7 +537,7 @@ DEFINE_ENUM_FLAG_OPERATORS(MDBX_debug_flags_t)
/** A debug-logger callback function, /** A debug-logger callback function,
* called before printing the message and aborting. * called before printing the message and aborting.
* *
* \param [in] env An environment handle returned by mdbx_env_create(). * \param [in] env An environment handle returned by \ref mdbx_env_create().
* \param [in] msg The assertion message, not including newline. */ * \param [in] msg The assertion message, not including newline. */
typedef void MDBX_debug_func(MDBX_log_level_t loglevel, const char *function, typedef void MDBX_debug_func(MDBX_log_level_t loglevel, const char *function,
int line, const char *msg, va_list args); int line, const char *msg, va_list args);
@ -571,7 +571,15 @@ typedef void MDBX_assert_func(const MDBX_env *env, const char *msg,
* \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); LIBMDBX_API int mdbx_env_set_assert(MDBX_env *env, MDBX_assert_func *func);
/** Dump given MDBX_val to the buffer */ /** Dump given MDBX_val to the buffer
*
* Dumps it as string if value is printable (all bytes in the range 0x20..0x7E),
* otherwise made hexadecimal dump. Requires at least 4 byte length buffer.
*
* \returns One of:
* - NULL if given buffer size less than 4 bytes;
* - pointer to constant string if given value NULL or empty;
* - otherwise pointer to given buffer. */
LIBMDBX_API const char *mdbx_dump_val(const MDBX_val *key, char *const buf, LIBMDBX_API const char *mdbx_dump_val(const MDBX_val *key, char *const buf,
const size_t bufsize); const size_t bufsize);
@ -596,7 +604,7 @@ enum MDBX_env_flags_t {
* - without `MDBX_NOSUBDIR` = in a filesystem we have the MDBX-directory with * - without `MDBX_NOSUBDIR` = in a filesystem we have the MDBX-directory with
* given pathname, within that a pair of MDBX-files with predefined names. * given pathname, within that a pair of MDBX-files with predefined names.
* *
* This flag affects only at new environment creating by mdbx_env_open(), * This flag affects only at new environment creating by \ref mdbx_env_open(),
* otherwise at opening an existing environment libmdbx will choice this * otherwise at opening an existing environment libmdbx will choice this
* automatically. */ * automatically. */
MDBX_NOSUBDIR = UINT32_C(0x4000), MDBX_NOSUBDIR = UINT32_C(0x4000),
@ -681,13 +689,12 @@ enum MDBX_env_flags_t {
* by single system call, without any memory management nor copying. * by single system call, without any memory management nor copying.
* *
* - without `MDBX_WRITEMAP` = data will be mapped into memory in the * - without `MDBX_WRITEMAP` = data will be mapped into memory in the
read-only * read-only mode. This requires stocking all modified database pages in
* mode. This requires stocking all modified database pages in memory and * memory and then writing them to disk through file operations.
* then writing them to disk through file operations.
* *
* \warning On the other hand, `MDBX_WRITEMAP` adds the possibility for stray * \warning On the other hand, `MDBX_WRITEMAP` adds the possibility for stray
* application writes thru pointers to silently corrupt the database. * application writes thru pointers to silently corrupt the database.
*
* \note The `MDBX_WRITEMAP` mode is incompatible with nested transactions, * \note The `MDBX_WRITEMAP` mode is incompatible with nested transactions,
* since this is unreasonable. I.e. nested transactions requires mallocation * since this is unreasonable. I.e. nested transactions requires mallocation
* of database pages and more work for tracking ones, which neuters a * of database pages and more work for tracking ones, which neuters a
@ -995,7 +1002,7 @@ enum MDBX_env_flags_t {
* \ref mdbx_txn_begin() for particular write transaction. \see sync_modes */ * \ref mdbx_txn_begin() for particular write transaction. \see sync_modes */
MDBX_UTTERLY_NOSYNC = MDBX_SAFE_NOSYNC | MDBX_MAPASYNC, MDBX_UTTERLY_NOSYNC = MDBX_SAFE_NOSYNC | MDBX_MAPASYNC,
/** @} end of SYNC_MODES */ /** @} end of SYNC MODES */
/** Do not block when starting a write transaction */ /** Do not block when starting a write transaction */
MDBX_TRYTXN = UINT32_C(0x10000000), MDBX_TRYTXN = UINT32_C(0x10000000),
@ -1020,16 +1027,16 @@ enum MDBX_db_flags_t {
MDBX_DUPSORT = UINT32_C(0x04), MDBX_DUPSORT = UINT32_C(0x04),
/** Numeric keys in native byte order either uint32_t or uint64_t. The keys /** 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 * must all be of the same size and must be aligned while passing as
arguments. */ * arguments. */
MDBX_INTEGERKEY = UINT32_C(0x08), MDBX_INTEGERKEY = UINT32_C(0x08),
/** With \ref MDBX_DUPSORT; sorted dup items have fixed size */ /** With \ref MDBX_DUPSORT; sorted dup items have fixed size */
MDBX_DUPFIXED = UINT32_C(0x10), MDBX_DUPFIXED = UINT32_C(0x10),
/** With \ref MDBX_DUPSORT; dups are \ref MDBX_INTEGERKEY -style integers. The /** With \ref MDBX_DUPSORT; dups are \ref MDBX_INTEGERKEY -style integers. The
data values must all be of the same size and must be aligned while passing * data values must all be of the same size and must be aligned while passing
as arguments. */ * as arguments. */
MDBX_INTEGERDUP = UINT32_C(0x20), MDBX_INTEGERDUP = UINT32_C(0x20),
/** With \ref MDBX_DUPSORT; use reverse string comparison */ /** With \ref MDBX_DUPSORT; use reverse string comparison */
@ -1054,23 +1061,24 @@ enum MDBX_put_flags_t {
MDBX_NOOVERWRITE = UINT32_C(0x10), MDBX_NOOVERWRITE = UINT32_C(0x10),
/** Only for \ref MDBX_DUPSORT. For upsertion: don't write if the key/data /** Only for \ref MDBX_DUPSORT. For upsertion: don't write if the key/data
pair already exist. For deletion: remove all duplicate data items. */ * pair already exist. For deletion: remove all duplicate data items. */
MDBX_NODUPDATA = UINT32_C(0x20), MDBX_NODUPDATA = UINT32_C(0x20),
/** For upsertion: overwrite the current key/data pair. MDBX allows this flag /** For upsertion: overwrite the current key/data pair.
for mdbx_put() for explicit overwrite/update without insertion. */ * MDBX allows this flag for \ref mdbx_put() for explicit overwrite/update
* without insertion. */
MDBX_CURRENT = UINT32_C(0x40), MDBX_CURRENT = UINT32_C(0x40),
/** For upsertion: Just reserve space for data, don't copy it. Return a /** For upsertion: Just reserve space for data, don't copy it.
pointer to the reserved space. */ * Return a pointer to the reserved space. */
MDBX_RESERVE = UINT32_C(0x10000), MDBX_RESERVE = UINT32_C(0x10000),
/** Data is being appended. Don't split full pages, continue on a new instead. /** Data is being appended.
*/ * Don't split full pages, continue on a new instead. */
MDBX_APPEND = UINT32_C(0x20000), MDBX_APPEND = UINT32_C(0x20000),
/** Duplicate data is being appended. Don't split full pages, continue on a /** Duplicate data is being appended.
new instead. */ * Don't split full pages, continue on a new instead. */
MDBX_APPENDDUP = UINT32_C(0x40000), MDBX_APPENDDUP = UINT32_C(0x40000),
/** Store multiple data items in one call. Only for \ref MDBX_DUPFIXED. */ /** Store multiple data items in one call. Only for \ref MDBX_DUPFIXED. */
@ -1089,7 +1097,7 @@ enum MDBX_copy_flags_t {
MDBX_CP_DEFAULTS = 0, 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 */ * pages sequentially */
MDBX_CP_COMPACT = 1u, MDBX_CP_COMPACT = 1u,
/** Force to make resizeable copy, i.e. dynamic size instead of fixed */ /** Force to make resizeable copy, i.e. dynamic size instead of fixed */
@ -1116,15 +1124,15 @@ enum MDBX_cursor_op {
MDBX_GET_BOTH, MDBX_GET_BOTH,
/** \ref MDBX_DUPSORT -only: Position at given key and at first data greater /** \ref MDBX_DUPSORT -only: Position at given key and at first data greater
than or equal to specified data. */ * than or equal to specified data. */
MDBX_GET_BOTH_RANGE, MDBX_GET_BOTH_RANGE,
/** Return key/data at current cursor position */ /** Return key/data at current cursor position */
MDBX_GET_CURRENT, MDBX_GET_CURRENT,
/** \ref MDBX_DUPFIXED -only: Return up to a page of duplicate data items from /** \ref MDBX_DUPFIXED -only: Return up to a page of duplicate data items
current cursor position. Move cursor to prepare for \ref * from current cursor position. Move cursor to prepare
MDBX_NEXT_MULTIPLE. */ * for \ref MDBX_NEXT_MULTIPLE. */
MDBX_GET_MULTIPLE, MDBX_GET_MULTIPLE,
/** Position at last key/data item */ /** Position at last key/data item */
@ -1139,9 +1147,9 @@ enum MDBX_cursor_op {
/** \ref MDBX_DUPSORT -only: Position at next data item of current key. */ /** \ref MDBX_DUPSORT -only: Position at next data item of current key. */
MDBX_NEXT_DUP, MDBX_NEXT_DUP,
/** \ref MDBX_DUPFIXED -only: Return up to a page of duplicate data items from /** \ref MDBX_DUPFIXED -only: Return up to a page of duplicate data items
next cursor position. Move cursor to prepare for \ref MDBX_NEXT_MULTIPLE. * from next cursor position. Move cursor to prepare
*/ * for \ref MDBX_NEXT_MULTIPLE. */
MDBX_NEXT_MULTIPLE, MDBX_NEXT_MULTIPLE,
/** Position at first data item of next key */ /** Position at first data item of next key */
@ -1165,8 +1173,8 @@ enum MDBX_cursor_op {
/** Position at first key greater than or equal to specified key. */ /** Position at first key greater than or equal to specified key. */
MDBX_SET_RANGE, MDBX_SET_RANGE,
/** \ref MDBX_DUPFIXED -only: Position at previous page and return up to a /** \ref MDBX_DUPFIXED -only: Position at previous page and return up to
page of duplicate data items. */ * a page of duplicate data items. */
MDBX_PREV_MULTIPLE MDBX_PREV_MULTIPLE
}; };
#ifndef __cplusplus #ifndef __cplusplus
@ -1200,8 +1208,8 @@ enum MDBX_error_t {
/** Database is corrupted (page was wrong type and so on) */ /** Database is corrupted (page was wrong type and so on) */
MDBX_CORRUPTED = -30796, 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, MDBX_PANIC = -30795,
/** DB file version mismatch with libmdbx */ /** DB file version mismatch with libmdbx */
@ -1354,7 +1362,7 @@ MDBX_DEPRECATED static __inline int MDBX_MAP_RESIZED_is_deprecated() {
* returned. See errors for a list of MDBX-specific error codes. * returned. See errors for a list of MDBX-specific error codes.
* *
* `mdbx_strerror()` is NOT thread-safe because may share common internal buffer * `mdbx_strerror()` is NOT thread-safe because may share common internal buffer
* for system maessages. The returned string must NOT be modified by the * for system messages. The returned string must NOT be modified by the
* application, but MAY be modified by a subsequent call to * application, but MAY be modified by a subsequent call to
* \ref mdbx_strerror(), `strerror()` and other related functions. * \ref mdbx_strerror(), `strerror()` and other related functions.
* \see mdbx_strerror_r() * \see mdbx_strerror_r()
@ -1637,7 +1645,8 @@ struct MDBX_envinfo {
/** Time since the last readers check in 1/65536 of second, /** Time since the last readers check in 1/65536 of second,
* see \ref mdbx_reader_check(). */ * see \ref mdbx_reader_check(). */
uint32_t mi_since_reader_check_seconds16dot16; uint32_t mi_since_reader_check_seconds16dot16;
/** Current environment mode, the same as mdbx_env_get_flags() returns. */ /** Current environment mode.
* The same as \ref mdbx_env_get_flags() returns. */
uint32_t mi_mode; uint32_t mi_mode;
}; };
#ifndef __cplusplus #ifndef __cplusplus
@ -1825,6 +1834,7 @@ LIBMDBX_API int mdbx_env_close(MDBX_env *env);
* *
* This may be used to set some flags in addition to those from * This may be used to set some flags in addition to those from
* mdbx_env_open(), or to unset these flags. * mdbx_env_open(), or to unset these flags.
* \see mdbx_env_get_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 * changing the flags. Therefore this function will be blocked while a write
@ -1843,6 +1853,7 @@ LIBMDBX_API int mdbx_env_set_flags(MDBX_env *env, unsigned flags, int onoff);
/** Get environment flags. /** Get environment flags.
* \ingroup c_statinfo * \ingroup c_statinfo
* \see mdbx_env_set_flags()
* *
* \param [in] env An environment handle returned by \ref mdbx_env_create(). * \param [in] env An environment handle returned by \ref mdbx_env_create().
* \param [out] flags The address of an integer to store the flags. * \param [out] flags The address of an integer to store the flags.
@ -2137,6 +2148,7 @@ LIBMDBX_API intptr_t mdbx_limits_txnsize_max(intptr_t pagesize);
* \ref MDBX_txn object until it or the \ref MDBX_env object is destroyed. * \ref MDBX_txn object until it or the \ref MDBX_env object is destroyed.
* This function may only be called after \ref mdbx_env_create() and before * This function may only be called after \ref mdbx_env_create() and before
* \ref mdbx_env_open(). * \ref mdbx_env_open().
* \see mdbx_env_get_maxreaders()
* *
* \param [in] env An environment handle returned * \param [in] env An environment handle returned
* by \ref mdbx_env_create(). * by \ref mdbx_env_create().
@ -2150,6 +2162,7 @@ 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.
* \ingroup c_statinfo * \ingroup c_statinfo
* \see mdbx_env_set_maxreaders()
* *
* \param [in] env An environment handle returned * \param [in] env An environment handle returned
* by \ref mdbx_env_create(). * by \ref mdbx_env_create().
@ -2211,6 +2224,7 @@ MDBX_DEPRECATED LIBMDBX_API int mdbx_env_get_maxkeysize(const MDBX_env *env);
/** Set application information associated with the \ref MDBX_env. /** Set application information associated with the \ref MDBX_env.
* \ingroup c_settings * \ingroup c_settings
* \see mdbx_env_get_userctx()
* *
* \param [in] env An environment handle returned by \ref mdbx_env_create(). * \param [in] env An environment handle returned by \ref mdbx_env_create().
* \param [in] ctx An arbitrary pointer for whatever the application needs. * \param [in] ctx An arbitrary pointer for whatever the application needs.
@ -2220,6 +2234,7 @@ 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.
* \ingroup c_statinfo * \ingroup c_statinfo
* \see mdbx_env_set_userctx()
* *
* \param [in] env An environment handle returned by \ref mdbx_env_create() * \param [in] env An environment handle returned by \ref mdbx_env_create()
* \returns The pointer set by \ref mdbx_env_set_userctx(). */ * \returns The pointer set by \ref mdbx_env_set_userctx(). */
@ -2598,14 +2613,14 @@ typedef int(MDBX_cmp_func)(const MDBX_val *a, const MDBX_val *b);
* Keys are strings to be compared in reverse order, from the end * Keys are strings to be compared in reverse order, from the end
* of the strings to the beginning. By default, Keys are treated as * of the strings to the beginning. By default, Keys are treated as
* strings and compared from beginning to end. * strings and compared from beginning to end.
* - \ref MDBX_INTEGERKEY
* Keys are binary integers in native byte order, either uint32_t or
* uint64_t, and will be sorted as such. The keys must all be of the
* same size and must be aligned while passing as arguments.
* - \ref MDBX_DUPSORT * - \ref MDBX_DUPSORT
* Duplicate keys may be used in the database. Or, from another point of * Duplicate keys may be used in the database. Or, from another point of
* view, keys may have multiple data items, stored in sorted order. By * view, keys may have multiple data items, stored in sorted order. By
* default keys must be unique and may have only a single data item. * default keys must be unique and may have only a single data item.
* - \ref MDBX_INTEGERKEY
* Keys are binary integers in native byte order, either uin32_t or
* uint64_t, and will be sorted as such. The keys must all be of the
* same size and must be aligned while passing as arguments.
* - \ref MDBX_DUPFIXED * - \ref MDBX_DUPFIXED
* This flag may only be used in combination with \ref MDBX_DUPSORT. This * This flag may only be used in combination with \ref MDBX_DUPSORT. This
* option tells the library that the data items for this database are * option tells the library that the data items for this database are
@ -2678,9 +2693,9 @@ mdbx_dbi_open_ex(MDBX_txn *txn, const char *name, unsigned flags, MDBX_dbi *dbi,
* \see key2value * \see key2value
* @{ * @{
* *
* The \ref mdbx_key_from_jsonInteger() build key which are comparable with * The \ref mdbx_key_from_jsonInteger() build a keys which are comparable with
* keys created by \ref mdbx_key_from_double(). So this allow mix `int64_t` and * keys created by \ref mdbx_key_from_double(). So this allows mixing `int64_t`
* IEEE754 `double` values in one index for JSON-numbers with restriction for * and IEEE754 double values in one index for JSON-numbers with restriction for
* integer numbers range corresponding to RFC-7159, i.e. \f$[-2^{53}+1, * integer 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 */ * 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_jsonInteger(const int64_t json_integer);