mirror of
https://github.com/isar/libmdbx.git
synced 2025-01-30 22:47:16 +08:00
mdbx: partial cleanup/reformat comments.
Change-Id: Ia96a5b307dc065b4d1920234c3cce93a0e585876
This commit is contained in:
Leo Yuriev
parent
333e5fada3
commit
7ec571c9a0
162
mdbx.h
162
mdbx.h
@ -309,12 +309,10 @@ typedef enum MDB_cursor_op {
|
||||
/* Database contents grew beyond environment mapsize */
|
||||
#define MDB_MAP_RESIZED (-30785)
|
||||
/* Operation and DB incompatible, or DB type changed. This can mean:
|
||||
* - The operation expects an MDB_DUPSORT / MDB_DUPFIXED database.
|
||||
* - Opening a named DB when the unnamed DB has
|
||||
*MDB_DUPSORT/MDB_INTEGERKEY.
|
||||
* - Accessing a data record as a database, or vice versa.
|
||||
* - The database was dropped and recreated with different flags.
|
||||
*/
|
||||
* - The operation expects an MDB_DUPSORT / MDB_DUPFIXED database.
|
||||
* - Opening a named DB when the unnamed DB has MDB_DUPSORT/MDB_INTEGERKEY.
|
||||
* - Accessing a data record as a database, or vice versa.
|
||||
* - The database was dropped and recreated with different flags. */
|
||||
#define MDB_INCOMPATIBLE (-30784)
|
||||
/* Invalid reuse of reader locktable slot */
|
||||
#define MDB_BAD_RSLOT (-30783)
|
||||
@ -365,12 +363,9 @@ typedef struct MDBX_envinfo {
|
||||
|
||||
/* Return the LMDB library version information.
|
||||
*
|
||||
* [out] major if non-NULL, the library major version number is copied
|
||||
* here
|
||||
* [out] minor if non-NULL, the library minor version number is copied
|
||||
* here
|
||||
* [out] patch if non-NULL, the library patch version number is copied
|
||||
* here
|
||||
* [out] major if non-NULL, the library major version number is copied here
|
||||
* [out] minor if non-NULL, the library minor version number is copied here
|
||||
* [out] patch if non-NULL, the library patch version number is copied here
|
||||
* Returns "version string" The library version as a string
|
||||
*/
|
||||
LIBMDBX_API const char *mdbx_version(int *major, int *minor, int *patch);
|
||||
@ -381,8 +376,10 @@ LIBMDBX_API const char *mdbx_version(int *major, int *minor, int *patch);
|
||||
* 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 LMDB library error is
|
||||
* returned. See errors for a list of LMDB-specific error codes.
|
||||
* returned. See errors for a list of MDBX-specific error codes.
|
||||
*
|
||||
* [in] err The error code
|
||||
*
|
||||
* Returns "error message" The description of the error
|
||||
*/
|
||||
LIBMDBX_API const char *mdbx_strerror(int errnum);
|
||||
@ -395,54 +392,50 @@ LIBMDBX_API const char *mdbx_strerror_r(int errnum, char *buf, size_t buflen);
|
||||
* Before the handle may be used, it must be opened using mdbx_env_open().
|
||||
* Various other options may also need to be set before opening the handle,
|
||||
* e.g. mdbx_env_set_mapsize(), mdbx_env_set_maxreaders(),
|
||||
* mdbx_env_set_maxdbs(),
|
||||
* depending on usage requirements.
|
||||
* mdbx_env_set_maxdbs(), depending on usage requirements.
|
||||
*
|
||||
* [out] env The address where the new handle will be stored
|
||||
*
|
||||
* Returns A non-zero error value on failure and 0 on success.
|
||||
*/
|
||||
LIBMDBX_API int mdbx_env_create(MDB_env **env);
|
||||
|
||||
/* Open an environment handle.
|
||||
*
|
||||
* If this function fails, mdbx_env_close() must be called to discard the
|
||||
*MDB_env handle.
|
||||
* [in] env An environment handle returned by mdbx_env_create()
|
||||
* [in] path The directory in which the database files reside. This
|
||||
* directory must already exist and be writable.
|
||||
* If this function fails, mdbx_env_close() must be called to discard
|
||||
* the MDB_env handle.
|
||||
* [in] env An environment handle returned by mdbx_env_create()
|
||||
* [in] path 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 here.
|
||||
* Flags set by mdbx_env_set_flags() are also used.
|
||||
* - MDB_NOSUBDIR
|
||||
* By default, LMDB creates its environment in a directory whose
|
||||
* pathname is given in \b path, and creates its data and lock
|
||||
*files
|
||||
* under that directory. With this option, \b path is used as-is
|
||||
*for
|
||||
* the database main data file. The database lock file is the \b
|
||||
*path
|
||||
* with "-lock" appended.
|
||||
* - MDB_RDONLY
|
||||
* Open the environment in read-only mode. No write operations will
|
||||
*be
|
||||
* allowed. LMDB will still modify the lock file - except on
|
||||
*read-only
|
||||
* filesystems, where LMDB does not use locks.
|
||||
* - MDB_WRITEMAP
|
||||
* Use a writeable memory map unless MDB_RDONLY is set. This uses
|
||||
* fewer mallocs 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.
|
||||
* Incompatible with nested transactions.
|
||||
* Do not mix processes with and without MDB_WRITEMAP on the same
|
||||
* environment. This can defeat durability (mdbx_env_sync etc).
|
||||
* - MDB_NOMETASYNC
|
||||
* Flush system buffers to disk only once per transaction, omit
|
||||
*the
|
||||
* metadata flush. Defer that until the system flushes files to
|
||||
* must be set to 0 or by bitwise OR'ing together one
|
||||
* or more of the values described here.
|
||||
*
|
||||
* Flags set by mdbx_env_set_flags() are also used:
|
||||
* - MDB_NOSUBDIR
|
||||
* By default, LMDB 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 "-lock" appended.
|
||||
*
|
||||
* - MDB_RDONLY
|
||||
* Open the environment in read-only mode. No write operations will
|
||||
* be allowed. LMDB will still modify the lock file - except on
|
||||
* read-only filesystems, where MDBX does not use locks.
|
||||
*
|
||||
* - MDB_WRITEMAP
|
||||
* Use a writeable memory map unless MDB_RDONLY is set. This uses fewer
|
||||
* mallocs 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.
|
||||
* Incompatible with nested transactions.
|
||||
* Do not mix processes with and without MDB_WRITEMAP on the same
|
||||
* environment. This can defeat durability (mdbx_env_sync etc).
|
||||
* - MDB_NOMETASYNC
|
||||
* 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-MDB_RDONLY commit or mdbx_env_sync(). This
|
||||
*optimization
|
||||
@ -1492,11 +1485,11 @@ LIBMDBX_API int mdbx_cursor_del(MDB_cursor *cursor, unsigned flags);
|
||||
* data items MDB_DUPSORT.
|
||||
* [in] cursor A cursor handle returned by mdbx_cursor_open()
|
||||
* [out] countp Address where the count will be stored
|
||||
* Returns A non-zero error value on failure and 0 on success. Some possible
|
||||
* errors are:
|
||||
* - EINVAL - cursor is not initialized, or an invalid parameter was
|
||||
*specified.
|
||||
*/
|
||||
*
|
||||
* Returns A non-zero error value on failure and 0 on success.
|
||||
* Some possible errors are:
|
||||
* - EINVAL - cursor is not initialized,
|
||||
* or an invalid parameter was specified. */
|
||||
LIBMDBX_API int mdbx_cursor_count(MDB_cursor *cursor, size_t *countp);
|
||||
|
||||
/* Compare two data items according to a particular database.
|
||||
@ -1507,8 +1500,8 @@ LIBMDBX_API int mdbx_cursor_count(MDB_cursor *cursor, size_t *countp);
|
||||
* [in] dbi A database handle returned by mdbx_dbi_open()
|
||||
* [in] a The first item to compare
|
||||
* [in] b The second item to compare
|
||||
* Returns < 0 if a < b, 0 if a == b, > 0 if a > b
|
||||
*/
|
||||
*
|
||||
* Returns < 0 if a < b, 0 if a == b, > 0 if a > b */
|
||||
LIBMDBX_API int mdbx_cmp(MDB_txn *txn, MDB_dbi dbi, const MDB_val *a,
|
||||
const MDB_val *b);
|
||||
|
||||
@ -1520,8 +1513,8 @@ LIBMDBX_API int mdbx_cmp(MDB_txn *txn, MDB_dbi dbi, const MDB_val *a,
|
||||
* [in] dbi A database handle returned by mdbx_dbi_open()
|
||||
* [in] a The first item to compare
|
||||
* [in] b The second item to compare
|
||||
* Returns < 0 if a < b, 0 if a == b, > 0 if a > b
|
||||
*/
|
||||
*
|
||||
* Returns < 0 if a < b, 0 if a == b, > 0 if a > b */
|
||||
LIBMDBX_API int mdbx_dcmp(MDB_txn *txn, MDB_dbi dbi, const MDB_val *a,
|
||||
const MDB_val *b);
|
||||
|
||||
@ -1529,8 +1522,8 @@ LIBMDBX_API int mdbx_dcmp(MDB_txn *txn, MDB_dbi dbi, const MDB_val *a,
|
||||
*
|
||||
* [in] msg The string to be printed.
|
||||
* [in] ctx An arbitrary context pointer for the callback.
|
||||
* Returns < 0 on failure, >= 0 on success.
|
||||
*/
|
||||
*
|
||||
* Returns < 0 on failure, >= 0 on success. */
|
||||
typedef int(MDB_msg_func)(const char *msg, void *ctx);
|
||||
|
||||
/* Dump the entries in the reader lock table.
|
||||
@ -1538,16 +1531,16 @@ typedef int(MDB_msg_func)(const char *msg, void *ctx);
|
||||
* [in] env An environment handle returned by mdbx_env_create()
|
||||
* [in] func A MDB_msg_func function
|
||||
* [in] ctx Anything the message function needs
|
||||
* Returns < 0 on failure, >= 0 on success.
|
||||
*/
|
||||
*
|
||||
* Returns < 0 on failure, >= 0 on success. */
|
||||
LIBMDBX_API int mdbx_reader_list(MDB_env *env, MDB_msg_func *func, void *ctx);
|
||||
|
||||
/* 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
|
||||
* Returns 0 on success, non-zero on failure.
|
||||
*/
|
||||
*
|
||||
* Returns 0 on success, non-zero on failure. */
|
||||
LIBMDBX_API int mdbx_reader_check(MDB_env *env, int *dead);
|
||||
|
||||
LIBMDBX_API char *mdbx_dkey(MDB_val *key, char *buf, const size_t bufsize);
|
||||
@ -1568,9 +1561,9 @@ LIBMDBX_API int mdbx_env_close_ex(MDB_env *env, int dont_sync);
|
||||
*
|
||||
* [in] env An environment handle returned by mdbx_env_create()
|
||||
* [in] bytes 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.
|
||||
*/
|
||||
* when a synchronous flush would be made.
|
||||
*
|
||||
* Returns A non-zero error value on failure and 0 on success. */
|
||||
LIBMDBX_API int mdbx_env_set_syncbytes(MDB_env *env, size_t bytes);
|
||||
|
||||
/* Returns a lag of the reading.
|
||||
@ -1580,9 +1573,9 @@ LIBMDBX_API int mdbx_env_set_syncbytes(MDB_env *env, size_t bytes);
|
||||
*
|
||||
* [in] txn A transaction handle returned by mdbx_txn_begin()
|
||||
* [out] percent Percentage of page allocation in the database.
|
||||
*
|
||||
* Returns Number of transactions committed after the given was started for
|
||||
* read, or -1 on failure.
|
||||
*/
|
||||
* read, or -1 on failure. */
|
||||
LIBMDBX_API int mdbx_txn_straggler(MDB_txn *txn, int *percent);
|
||||
|
||||
/* A callback function for killing a laggard readers,
|
||||
@ -1594,11 +1587,11 @@ LIBMDBX_API int mdbx_txn_straggler(MDB_txn *txn, int *percent);
|
||||
* [in] txn Transaction number on which stalled.
|
||||
* [in] gap a lag from the last commited txn.
|
||||
* [in] retry a retry number, less that zero for notify end of OOM-loop.
|
||||
*
|
||||
* Returns -1 on failure (reader is not killed),
|
||||
* 0 on a race condition (no such reader),
|
||||
* 1 on success (reader was killed),
|
||||
* >1 on success (reader was SURE killed).
|
||||
*/
|
||||
* 0 on a race condition (no such reader),
|
||||
* 1 on success (reader was killed),
|
||||
* >1 on success (reader was SURE killed). */
|
||||
typedef int(MDBX_oom_func)(MDB_env *env, int pid, mdbx_tid_t thread_id,
|
||||
size_t txn, unsigned gap, int retry);
|
||||
|
||||
@ -1608,8 +1601,7 @@ typedef int(MDBX_oom_func)(MDB_env *env, int pid, mdbx_tid_t thread_id,
|
||||
* a laggard readers to allowing reclaiming of freeDB.
|
||||
*
|
||||
* [in] env An environment handle returned by mdbx_env_create().
|
||||
* [in] oomfunc A #MDBX_oom_func function or NULL to disable.
|
||||
*/
|
||||
* [in] oomfunc A #MDBX_oom_func function or NULL to disable. */
|
||||
LIBMDBX_API void mdbx_env_set_oomfunc(MDB_env *env, MDBX_oom_func *oom_func);
|
||||
|
||||
/* Get the current oom_func callback.
|
||||
@ -1618,8 +1610,7 @@ LIBMDBX_API void mdbx_env_set_oomfunc(MDB_env *env, MDBX_oom_func *oom_func);
|
||||
* a laggard readers to allowing reclaiming of freeDB.
|
||||
*
|
||||
* [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(MDB_env *env);
|
||||
|
||||
#define MDBX_DBG_ASSERT 1
|
||||
@ -1651,10 +1642,11 @@ LIBMDBX_API int mdbx_canary_put(MDB_txn *txn, const mdbx_canary *canary);
|
||||
LIBMDBX_API int mdbx_canary_get(MDB_txn *txn, mdbx_canary *canary);
|
||||
|
||||
/* Returns:
|
||||
* - MDBX_RESULT_TRUE when no more data available
|
||||
* or cursor not positioned;
|
||||
* - MDBX_RESULT_FALSE when data available;
|
||||
* - Otherwise the error code. */
|
||||
* - MDBX_RESULT_TRUE
|
||||
* when no more data available or cursor not positioned;
|
||||
* - MDBX_RESULT_FALSE
|
||||
* when data available;
|
||||
* - Otherwise the error code. */
|
||||
LIBMDBX_API int mdbx_cursor_eof(MDB_cursor *mc);
|
||||
|
||||
/* Returns: MDBX_RESULT_TRUE, MDBX_RESULT_FALSE or Error code. */
|
||||
|
||||
77
src/bits.h
77
src/bits.h
@ -368,8 +368,8 @@ typedef struct MDBX_lockinfo {
|
||||
#endif
|
||||
|
||||
/* The number of slots that have been used in the reader table.
|
||||
* This always records the maximum count, it is not decremented
|
||||
* when readers release their slots. */
|
||||
* This always records the maximum count, it is not decremented
|
||||
* when readers release their slots. */
|
||||
__cache_aligned volatile unsigned mti_numreaders;
|
||||
#ifdef MDBX_OSAL_LOCK
|
||||
/* Mutex protecting access to this table. */
|
||||
@ -380,19 +380,17 @@ typedef struct MDBX_lockinfo {
|
||||
|
||||
#pragma pack(pop)
|
||||
|
||||
/** Auxiliary DB info.
|
||||
* The information here is mostly static/read-only. There is
|
||||
* only a single copy of this record in the environment.
|
||||
*/
|
||||
/* Auxiliary DB info.
|
||||
* The information here is mostly static/read-only. There is
|
||||
* only a single copy of this record in the environment. */
|
||||
typedef struct MDB_dbx {
|
||||
MDB_val md_name; /**< name of the database */
|
||||
MDB_cmp_func *md_cmp; /**< function for comparing keys */
|
||||
MDB_cmp_func *md_dcmp; /**< function for comparing data items */
|
||||
} MDB_dbx;
|
||||
|
||||
/** A database transaction.
|
||||
* Every operation requires a transaction handle.
|
||||
*/
|
||||
/* A database transaction.
|
||||
* Every operation requires a transaction handle. */
|
||||
struct MDB_txn {
|
||||
#define MDBX_MT_SIGNATURE (0x93D53A31)
|
||||
unsigned mt_signature;
|
||||
@ -400,40 +398,37 @@ struct MDB_txn {
|
||||
/** Nested txn under this txn, set together with flag #MDB_TXN_HAS_CHILD */
|
||||
MDB_txn *mt_child;
|
||||
pgno_t mt_next_pgno; /**< next unallocated page */
|
||||
/** The ID of this transaction. IDs are integers incrementing from 1.
|
||||
* Only committed write transactions increment the ID. If a transaction
|
||||
* aborts, the ID may be re-used by the next writer.
|
||||
*/
|
||||
/* The ID of this transaction. IDs are integers incrementing from 1.
|
||||
* Only committed write transactions increment the ID. If a transaction
|
||||
* aborts, the ID may be re-used by the next writer. */
|
||||
txnid_t mt_txnid;
|
||||
MDB_env *mt_env; /**< the DB environment */
|
||||
/** The list of reclaimed txns from freeDB */
|
||||
MDB_IDL mt_lifo_reclaimed;
|
||||
/** The list of pages that became unused during this transaction.
|
||||
*/
|
||||
/* The list of pages that became unused during this transaction. */
|
||||
MDB_IDL mt_free_pgs;
|
||||
/** The list of loose pages that became unused and may be reused
|
||||
* in this transaction, linked through #NEXT_LOOSE_PAGE(page).
|
||||
*/
|
||||
/* The list of loose pages that became unused and may be reused
|
||||
* in this transaction, linked through #NEXT_LOOSE_PAGE(page). */
|
||||
MDB_page *mt_loose_pgs;
|
||||
/** Number of loose pages (#mt_loose_pgs) */
|
||||
int mt_loose_count;
|
||||
/** The sorted list of dirty pages we temporarily wrote to disk
|
||||
* because the dirty list was full. page numbers in here are
|
||||
* shifted left by 1, deleted slots have the LSB set.
|
||||
*/
|
||||
/* The sorted list of dirty pages we temporarily wrote to disk
|
||||
* because the dirty list was full. page numbers in here are
|
||||
* shifted left by 1, deleted slots have the LSB set. */
|
||||
MDB_IDL mt_spill_pgs;
|
||||
union {
|
||||
/** For write txns: Modified pages. Sorted when not MDB_WRITEMAP. */
|
||||
/* For write txns: Modified pages. Sorted when not MDB_WRITEMAP. */
|
||||
MDB_ID2L dirty_list;
|
||||
/** For read txns: This thread/txn's reader table slot, or NULL. */
|
||||
/* For read txns: This thread/txn's reader table slot, or NULL. */
|
||||
MDB_reader *reader;
|
||||
} mt_u;
|
||||
/** Array of records for each DB known in the environment. */
|
||||
/* Array of records for each DB known in the environment. */
|
||||
MDB_dbx *mt_dbxs;
|
||||
/** Array of MDB_db records for each known DB */
|
||||
/* Array of MDB_db records for each known DB */
|
||||
MDB_db *mt_dbs;
|
||||
/** Array of sequence numbers for each DB handle */
|
||||
/* Array of sequence numbers for each DB handle */
|
||||
unsigned *mt_dbiseqs;
|
||||
|
||||
/** @defgroup mt_dbflag Transaction DB Flags
|
||||
* @ingroup internal
|
||||
* @{
|
||||
@ -609,20 +604,20 @@ struct MDB_env {
|
||||
unsigned me_maxreaders; /**< size of the reader table */
|
||||
/** Max #MDBX_lockinfo.mti_numreaders of interest to #mdbx_env_close() */
|
||||
unsigned me_close_readers;
|
||||
MDB_dbi me_numdbs; /**< number of DBs opened */
|
||||
MDB_dbi me_maxdbs; /**< size of the DB table */
|
||||
mdbx_pid_t me_pid; /**< process ID of this env */
|
||||
char *me_path; /**< path to the DB files */
|
||||
char *me_map; /**< the memory map of the data file */
|
||||
MDBX_lockinfo *me_txns; /**< the memory map of the lock file, never NULL */
|
||||
void *me_pbuf; /**< scratch area for DUPSORT put() */
|
||||
MDB_txn *me_txn; /**< current write transaction */
|
||||
MDB_txn *me_txn0; /**< prealloc'd write transaction */
|
||||
size_t me_mapsize; /**< size of the data memory map */
|
||||
pgno_t me_maxpg; /**< me_mapsize / me_psize */
|
||||
MDB_dbx *me_dbxs; /**< array of static DB info */
|
||||
uint16_t *me_dbflags; /**< array of flags from MDB_db.md_flags */
|
||||
unsigned *me_dbiseqs; /**< array of dbi sequence numbers */
|
||||
MDB_dbi me_numdbs; /**< number of DBs opened */
|
||||
MDB_dbi me_maxdbs; /**< size of the DB table */
|
||||
mdbx_pid_t me_pid; /**< process ID of this env */
|
||||
char *me_path; /**< path to the DB files */
|
||||
char *me_map; /**< the memory map of the data file */
|
||||
MDBX_lockinfo *me_lck; /**< the memory map of the lock file, never NULL */
|
||||
void *me_pbuf; /**< scratch area for DUPSORT put() */
|
||||
MDB_txn *me_txn; /**< current write transaction */
|
||||
MDB_txn *me_txn0; /**< prealloc'd write transaction */
|
||||
size_t me_mapsize; /**< size of the data memory map */
|
||||
pgno_t me_maxpg; /**< me_mapsize / me_psize */
|
||||
MDB_dbx *me_dbxs; /**< array of static DB info */
|
||||
uint16_t *me_dbflags; /**< array of flags from MDB_db.md_flags */
|
||||
unsigned *me_dbiseqs; /**< array of dbi sequence numbers */
|
||||
mdbx_thread_key_t me_txkey; /**< thread-key for readers */
|
||||
txnid_t me_pgoldest; /**< ID of oldest reader last time we looked */
|
||||
MDB_pgstate me_pgstate; /**< state of old pages from freeDB */
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user