libmdbx  0.12.2.11 (2022-11-19T23:19:30+03:00)
One of the fastest compact embeddable key-value ACID database without WAL.
C API

Modules

 Error handling
 
 Opening & Closing
 
 Transactions
 
 Databases
 
 Create/Read/Update/Delete (see Quick Reference in details)
 
 Cursors
 
 Statistics & Information
 
 Settings
 
 Logging and runtime debug
 
 Range query estimation
 
 Extra operations
 
 Value-to-Key functions
 Value-to-Key functions to avoid using custom comparators.
 
 Key-to-Value functions
 Key-to-Value functions to avoid using custom comparators.
 
 B-tree Traversal
 

Classes

struct  MDBX_version_info
 libmdbx version information More...
 
struct  MDBX_build_info
 libmdbx build information More...
 
struct  MDBX_stat
 Statistics for a database in the environment. More...
 
struct  MDBX_envinfo
 Information about the environment. More...
 
struct  MDBX_txn_info
 Information about the transaction. More...
 
struct  MDBX_commit_latency
 Latency of commit stages in 1/65536 of seconds units. More...
 
struct  MDBX_canary
 The fours integers markers (aka "canary") associated with the environment. More...
 
struct  MDBX_version_info.git
 
struct  MDBX_envinfo.mi_geo
 
struct  MDBX_envinfo.mi_bootid
 A mostly unique ID that is regenerated on each boot. More...
 
struct  MDBX_envinfo.mi_bootid.current
 
struct  MDBX_envinfo.mi_bootid.meta0
 
struct  MDBX_envinfo.mi_bootid.meta1
 
struct  MDBX_envinfo.mi_bootid.meta2
 
struct  MDBX_envinfo.mi_pgop_stat
 
struct  MDBX_commit_latency.gc_prof
 Информация для профилирования работы GC. More...
 

Macros

#define MDBX_VERSION_MAJOR   0
 
#define MDBX_VERSION_MINOR   12
 
#define LIBMDBX_API
 
#define LIBMDBX_API_TYPE
 
#define LIBMDBX_VERINFO_API   __dll_export
 
#define MDBX_LOCKNAME   "/mdbx.lck"
 The name of the lock file in the environment without using MDBX_NOSUBDIR. More...
 
#define MDBX_DATANAME   "/mdbx.dat"
 The name of the data file in the environment without using MDBX_NOSUBDIR. More...
 
#define MDBX_LOCK_SUFFIX   "-lck"
 The suffix of the lock file when MDBX_NOSUBDIR is used. More...
 
#define MDBX_MAP_RESIZED   MDBX_MAP_RESIZED_is_deprecated()
 

Typedefs

typedef int mdbx_filehandle_t
 
typedef pid_t mdbx_pid_t
 
typedef pthread_t mdbx_tid_t
 
typedef mode_t mdbx_mode_t
 
typedef struct MDBX_env MDBX_env
 Opaque structure for a database environment. More...
 
typedef struct iovec MDBX_val
 Generic structure used for passing keys and data in and out of the database. . More...
 
typedef enum MDBX_txn_flags_t MDBX_txn_flags_t
 
typedef enum MDBX_warmup_flags_t MDBX_warmup_flags_t
 
typedef int(* MDBX_preserve_func) (void *context, MDBX_val *target, const void *src, size_t bytes)
 

Enumerations

enum  MDBX_constants { MDBX_MAX_DBI = UINT32_C(32765) , MDBX_MAXDATASIZE = UINT32_C(0x7fff0000) , MDBX_MIN_PAGESIZE = 256 , MDBX_MAX_PAGESIZE = 65536 }
 
enum  MDBX_option_t {
  MDBX_opt_max_db , MDBX_opt_max_readers , MDBX_opt_sync_bytes , MDBX_opt_sync_period ,
  MDBX_opt_rp_augment_limit , MDBX_opt_loose_limit , MDBX_opt_dp_reserve_limit , MDBX_opt_txn_dp_limit ,
  MDBX_opt_txn_dp_initial , MDBX_opt_spill_max_denominator , MDBX_opt_spill_min_denominator , MDBX_opt_spill_parent4child_denominator ,
  MDBX_opt_merge_threshold_16dot16_percent
}
 MDBX environment options. More...
 

Functions

LIBMDBX_API const char * mdbx_liberr2str (int errnum)
 
LIBMDBX_API int mdbx_replace_ex (MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key, MDBX_val *new_data, MDBX_val *old_data, MDBX_put_flags_t flags, MDBX_preserve_func preserver, void *preserver_context)
 
LIBMDBX_API MDBX_hsr_funcmdbx_env_get_hsr (const MDBX_env *env)
 Gets current Handle-Slow-Readers callback used to resolve database full/overflow issue due to a reader(s) which prevents the old data from being recycled. More...
 

Variables

LIBMDBX_VERINFO_API const struct MDBX_version_info mdbx_version
 libmdbx version information More...
 
LIBMDBX_VERINFO_API const struct MDBX_build_info mdbx_build
 libmdbx build information More...
 

Detailed Description


Class Documentation

◆ MDBX_version_info

struct MDBX_version_info

libmdbx version information

Class Members
struct MDBX_version_info git

source information from git

uint8_t major

Major version number

uint8_t minor

Minor version number

uint16_t release

Release number of Major.Minor

uint32_t revision

Revision number of Release

const char * sourcery

sourcery anchor for pinning

◆ MDBX_build_info

struct MDBX_build_info

libmdbx build information

Attention
Some strings could be NULL in case no corresponding information was provided at build time (i.e. flags).
Class Members
const char * compiler

compiler

const char * datetime

build timestamp (ISO-8601 or DATE TIME)

const char * flags

CFLAGS and CXXFLAGS

const char * options

mdbx-related options

const char * target

cpu/arch-system-config triplet

◆ MDBX_stat

struct MDBX_stat

Statistics for a database in the environment.

See also
mdbx_env_stat_ex()
mdbx_dbi_stat()
Class Members
uint64_t ms_branch_pages

Number of internal (non-leaf) pages

uint32_t ms_depth

Depth (height) of the B-tree

uint64_t ms_entries

Number of data items

uint64_t ms_leaf_pages

Number of leaf pages

uint64_t ms_mod_txnid

Transaction ID of committed last modification

uint64_t ms_overflow_pages

Number of overflow pages

uint32_t ms_psize

Size of a database page. This is the same for all databases.

◆ MDBX_envinfo

struct MDBX_envinfo

Information about the environment.

See also
mdbx_env_info_ex()
Class Members
uint32_t mi_autosync_period_seconds16dot16

Current auto-sync period in 1/65536 of second, see mdbx_env_set_syncperiod().

uint64_t mi_autosync_threshold

Current auto-sync threshold, see mdbx_env_set_syncbytes().

struct MDBX_envinfo mi_bootid 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.

uint32_t mi_dxb_pagesize

Database pagesize

struct MDBX_envinfo mi_geo
uint64_t mi_last_pgno

Number of the last used page

uint64_t mi_latter_reader_txnid

ID of the last reader transaction

uint64_t mi_mapsize

Size of the data memory map

uint32_t mi_maxreaders

Total reader slots in the environment

uint64_t mi_meta0_sign
uint64_t mi_meta0_txnid
uint64_t mi_meta1_sign
uint64_t mi_meta1_txnid
uint64_t mi_meta2_sign
uint64_t mi_meta2_txnid
uint32_t mi_mode

Current environment mode. The same as mdbx_env_get_flags() returns.

uint32_t mi_numreaders

Max reader slots used in the environment

struct MDBX_envinfo mi_pgop_stat

Statistics of page operations.

Overall statistics of page operations of all (running, completed and aborted) transactions in the current multi-process session (since the first process opened the database after everyone had previously closed it).

uint64_t mi_recent_txnid

ID of the last committed transaction

uint64_t mi_self_latter_reader_txnid

ID of the last reader transaction of caller process

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_since_sync_seconds16dot16

Time since entering to a "dirty" out-of-sync state in units of 1/65536 of second. In other words, this is the time since the last non-steady commit or zero if it was steady.

uint32_t mi_sys_pagesize

System pagesize

uint64_t mi_unsync_volume

Bytes not explicitly synchronized to disk

◆ MDBX_txn_info

struct MDBX_txn_info

Information about the transaction.

See also
mdbx_txn_info
Class Members
uint64_t txn_id

The ID of the transaction. For a READ-ONLY transaction, this corresponds to the snapshot being read.

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. at least 1 if any reader running).

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.

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 Handle-Slow-Readers callback for this read transaction. For WRITE transaction: the space inside transaction that left to MDBX_TXN_FULL error.

uint64_t txn_space_limit_hard

Upper bound for size the database file, i.e. the value size_upper argument of the appropriate call of mdbx_env_set_geometry().

uint64_t txn_space_limit_soft

Current size of database file.

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.

uint64_t txn_space_used

Used space by this transaction, i.e. corresponding to the last used database page.

◆ MDBX_commit_latency

struct MDBX_commit_latency

Latency of commit stages in 1/65536 of seconds units.

Warning
This structure may be changed in future releases.
See also
mdbx_txn_commit_ex()
Class Members
uint32_t audit Duration of internal audit if enabled.
uint32_t ending Duration of transaction ending (releasing resources).
uint32_t gc_cputime User-mode CPU time spent on GC update.
struct MDBX_commit_latency gc_prof Информация для профилирования работы GC.
Note
Статистика является общей для всех процессов работающих с одним файлом БД и хранится в LCK-файле. Данные аккумулируются при фиксации всех транзакций, но только в сборках libmdbx c установленной опцией MDBX_ENABLE_PROFGC. Собранная статистика возвращаются любому процессу при использовании mdbx_txn_commit_ex() и одновременно обнуляется при завершении транзакций верхнего уровня (не вложенных).
uint32_t gc_wallclock Duration of GC update by wall clock.
uint32_t preparation Duration of preparation (commit child transactions, update sub-databases records and cursors destroying).
uint32_t sync Duration of syncing written data to the disk/storage, i.e. the duration of a fdatasync() or a msync() syscall during commit.
uint32_t whole The total duration of a commit.
uint32_t write Duration of writing dirty/modified data pages to a filesystem, i.e. the summary duration of a write() syscalls during commit.

◆ MDBX_canary

struct MDBX_canary

The fours integers markers (aka "canary") associated with the environment.

See also
mdbx_canary_set()
mdbx_canary_get()

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

Class Members
uint64_t v
uint64_t x
uint64_t y
uint64_t z

◆ MDBX_version_info.git

struct MDBX_version_info.git
Class Members
const char * commit

tree hash, i.e. digest of the source code

const char * datetime

committer date, strict ISO-8601 format

const char * describe

git-describe string

const char * tree

commit hash (hexadecimal digits)

◆ MDBX_envinfo.mi_geo

struct MDBX_envinfo.mi_geo
Class Members
uint64_t current

Current datafile size

uint64_t grow

Growth step for datafile

uint64_t lower

Lower limit for datafile size

uint64_t shrink

Shrink threshold for datafile

uint64_t upper

Upper limit for datafile size

◆ MDBX_envinfo.mi_bootid

struct MDBX_envinfo.mi_bootid

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.

Class Members
mi_bootid current
mi_bootid meta0
mi_bootid meta1
mi_bootid meta2

◆ MDBX_envinfo.mi_bootid.current

struct MDBX_envinfo.mi_bootid.current
Class Members
uint64_t x
uint64_t y

◆ MDBX_envinfo.mi_bootid.meta0

struct MDBX_envinfo.mi_bootid.meta0
Class Members
uint64_t x
uint64_t y

◆ MDBX_envinfo.mi_bootid.meta1

struct MDBX_envinfo.mi_bootid.meta1
Class Members
uint64_t x
uint64_t y

◆ MDBX_envinfo.mi_bootid.meta2

struct MDBX_envinfo.mi_bootid.meta2
Class Members
uint64_t x
uint64_t y

◆ MDBX_envinfo.mi_pgop_stat

struct MDBX_envinfo.mi_pgop_stat

Statistics of page operations.

Overall statistics of page operations of all (running, completed and aborted) transactions in the current multi-process session (since the first process opened the database after everyone had previously closed it).

Class Members
uint64_t clone

Quantity of parent's dirty pages clones for nested transactions

uint64_t cow

Quantity of pages copied for update

uint64_t fsync

Number of explicit fsync-to-disk operations (not a pages)

uint64_t merge

Page merges

uint64_t msync

Number of explicit msync-to-disk operations (not a pages)

uint64_t newly

Quantity of a new pages added

uint64_t spill

Quantity of spilled dirty pages

uint64_t split

Page splits

uint64_t unspill

Quantity of unspilled/reloaded pages

uint64_t wops

Number of explicit write operations (not a pages) to a disk

◆ MDBX_commit_latency.gc_prof

struct MDBX_commit_latency.gc_prof

Информация для профилирования работы GC.

Note
Статистика является общей для всех процессов работающих с одним файлом БД и хранится в LCK-файле. Данные аккумулируются при фиксации всех транзакций, но только в сборках libmdbx c установленной опцией MDBX_ENABLE_PROFGC. Собранная статистика возвращаются любому процессу при использовании mdbx_txn_commit_ex() и одновременно обнуляется при завершении транзакций верхнего уровня (не вложенных).
Class Members
uint32_t coalescences Количество итераций слияния записей GC.
uint32_t flushes Количество принудительных фиксаций на диск во избежания приращения БД при работе вне режима MDBX_UTTERLY_NOSYNC.
uint32_t kicks Количество обращений к механизму Handle-Slow-Readers во избежания приращения БД.
See also
MDBX_hsr_func
uint32_t self_counter Счетчик выполнения по медленному пути (slow path execution count) GC для целей поддержки и обновления самой GC.
uint32_t self_majflt Количество страничных промахов (page faults) внутри GC при выделении и подготовки страниц для самой GC.
uint32_t self_rsteps Количество итераций поиска внутри GC при выделении страниц для целей поддержки и обновления самой GC.
uint32_t self_rtime_cpu Время ЦПУ в режиме пользователе затраченное на чтение и поиск внтури GC для целей поддержки и обновления самой GC.
uint32_t self_rtime_monotonic Время "по настенным часам" затраченное на чтение и поиск внутри GC для целей поддержки и обновления самой GC.
uint32_t self_xpages Количество запросов на выделение последовательностей страниц для самой GC.
uint32_t self_xtime_monotonic Монотонное время по "настенным часам" затраченное на подготовку страниц извлекаемых из GC для целей поддержки и обновления самой GC, включая подкачку с диска.
uint32_t wipes Количество уничтожений предыдущих надежных/устойчивых точек фиксации при работе в режиме MDBX_UTTERLY_NOSYNC.
uint32_t wloops Количество итераций обновления GC, больше 1 если были повторы/перезапуски.
uint32_t work_counter Счетчик выполнения по медленному пути (slow path execution count) GC ради данных пользователя.
uint32_t work_majflt Количество страничных промахов (page faults) внутри GC при выделении и подготовки страниц для данных пользователя.
uint32_t work_rsteps Количество итераций поиска внутри GC при выделении страниц ради данных пользователя.
uint32_t work_rtime_cpu Время ЦПУ в режиме пользователе затраченное на чтение и поиск внтури GC ради данных пользователя.
uint32_t work_rtime_monotonic Время "по настенным часам" затраченное на чтение и поиск внутри GC ради данных пользователя.
uint32_t work_xpages Количество запросов на выделение последовательностей страниц ради данных пользователя.
uint32_t work_xtime_monotonic Монотонное время по "настенным часам" затраченное на подготовку страниц извлекаемых из GC для данных пользователя, включая подкачку с диска.

Macro Definition Documentation

◆ LIBMDBX_API

#define LIBMDBX_API

◆ LIBMDBX_API_TYPE

#define LIBMDBX_API_TYPE

◆ LIBMDBX_VERINFO_API

#define LIBMDBX_VERINFO_API   __dll_export

◆ MDBX_DATANAME

#define MDBX_DATANAME   "/mdbx.dat"

The name of the data file in the environment without using MDBX_NOSUBDIR.

◆ MDBX_LOCK_SUFFIX

#define MDBX_LOCK_SUFFIX   "-lck"

The suffix of the lock file when MDBX_NOSUBDIR is used.

◆ MDBX_LOCKNAME

#define MDBX_LOCKNAME   "/mdbx.lck"

The name of the lock file in the environment without using MDBX_NOSUBDIR.

◆ MDBX_MAP_RESIZED

#define MDBX_MAP_RESIZED   MDBX_MAP_RESIZED_is_deprecated()

◆ MDBX_VERSION_MAJOR

#define MDBX_VERSION_MAJOR   0

◆ MDBX_VERSION_MINOR

#define MDBX_VERSION_MINOR   12

Typedef Documentation

◆ MDBX_env

typedef struct MDBX_env MDBX_env

Opaque structure for a database environment.

An environment supports multiple key-value sub-databases (aka key-value spaces or tables), all residing in the same shared-memory map.

See also
mdbx_env_create()
mdbx_env_close()

◆ mdbx_filehandle_t

typedef int mdbx_filehandle_t

◆ mdbx_mode_t

typedef mode_t mdbx_mode_t

◆ mdbx_pid_t

typedef pid_t mdbx_pid_t

◆ MDBX_preserve_func

typedef int(* MDBX_preserve_func) (void *context, MDBX_val *target, const void *src, size_t bytes)

◆ mdbx_tid_t

typedef pthread_t mdbx_tid_t

◆ MDBX_txn_flags_t

◆ MDBX_val

typedef struct iovec MDBX_val

Generic structure used for passing keys and data in and out of the database. .

See also
mdbx::slice
mdbx::buffer

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.

Key sizes must be between 0 and mdbx_env_get_maxkeysize() inclusive. The same applies to data sizes in databases with the MDBX_DUPSORT flag. Other data items can in theory be from 0 to MDBX_MAXDATASIZE bytes long.

Note
The notable difference between MDBX and LMDB is that MDBX support zero length keys.

◆ MDBX_warmup_flags_t

Enumeration Type Documentation

◆ MDBX_constants

Enumerator
MDBX_MAX_DBI 

The hard limit for DBI handles

MDBX_MAXDATASIZE 

The maximum size of a data item.

MDBX_MIN_PAGESIZE 

The minimal database page size in bytes.

MDBX_MAX_PAGESIZE 

The maximal database page size in bytes.

◆ MDBX_option_t

MDBX environment options.

Enumerator
MDBX_opt_max_db 

Controls the maximum number of named databases for the environment.

By default only unnamed key-value database could used and appropriate value should set by MDBX_opt_max_db to using any more named subDB(s). To reduce overhead, use the minimum sufficient value. This option may only set after mdbx_env_create() and before mdbx_env_open().

See also
mdbx_env_set_maxdbs()
mdbx_env_get_maxdbs()
MDBX_opt_max_readers 

Defines the maximum number of threads/reader slots for all processes interacting with the database.

This defines the number of slots in the lock table that is used to track readers in the the environment. The default is about 100 for 4K system page size. Starting a read-only transaction normally ties a lock table slot to the current thread until the environment closes or the thread exits. If MDBX_NOTLS is in use, mdbx_txn_begin() instead ties the slot to the MDBX_txn object until it or the MDBX_env object is destroyed. This option may only set after mdbx_env_create() and before mdbx_env_open(), and has an effect only when the database is opened by the first process interacts with the database.

See also
mdbx_env_set_maxreaders()
mdbx_env_get_maxreaders()
MDBX_opt_sync_bytes 

Controls interprocess/shared threshold to force flush the data buffers to disk, if MDBX_SAFE_NOSYNC is used.

See also
mdbx_env_set_syncbytes()
mdbx_env_get_syncbytes()
MDBX_opt_sync_period 

Controls interprocess/shared relative period since the last unsteady commit to force flush the data buffers to disk, if MDBX_SAFE_NOSYNC is used.

See also
mdbx_env_set_syncperiod()
mdbx_env_get_syncperiod()
MDBX_opt_rp_augment_limit 

Controls the in-process limit to grow a list of reclaimed/recycled page's numbers for finding a sequence of contiguous pages for large data items.

A long values requires allocation of contiguous database pages. To find such sequences, it may be necessary to accumulate very large lists, especially when placing very long values (more than a megabyte) in a large databases (several tens of gigabytes), which is much expensive in extreme cases. This threshold allows you to avoid such costs by allocating new pages at the end of the database (with its possible growth on disk), instead of further accumulating/reclaiming Garbage Collection records.

On the other hand, too small threshold will lead to unreasonable database growth, or/and to the inability of put long values.

The MDBX_opt_rp_augment_limit controls described limit for the current process. Default is 262144, it is usually enough for most cases.

MDBX_opt_loose_limit 

Controls the in-process limit to grow a cache of dirty pages for reuse in the current transaction.

A 'dirty page' refers to a page that has been updated in memory only, the changes to a dirty page are not yet stored on disk. To reduce overhead, it is reasonable to release not all such pages immediately, but to leave some ones in cache for reuse in the current transaction.

The MDBX_opt_loose_limit allows you to set a limit for such cache inside the current process. Should be in the range 0..255, default is 64.

MDBX_opt_dp_reserve_limit 

Controls the in-process limit of a pre-allocated memory items for dirty pages.

A 'dirty page' refers to a page that has been updated in memory only, the changes to a dirty page are not yet stored on disk. Without MDBX_WRITEMAP dirty pages are allocated from memory and released when a transaction is committed. To reduce overhead, it is reasonable to release not all ones, but to leave some allocations in reserve for reuse in the next transaction(s).

The MDBX_opt_dp_reserve_limit allows you to set a limit for such reserve inside the current process. Default is 1024.

MDBX_opt_txn_dp_limit 

Controls the in-process limit of dirty pages for a write transaction.

A 'dirty page' refers to a page that has been updated in memory only, the changes to a dirty page are not yet stored on disk. Without MDBX_WRITEMAP dirty pages are allocated from memory and will be busy until are written to disk. Therefore for a large transactions is reasonable to limit dirty pages collecting above an some threshold but spill to disk instead.

The MDBX_opt_txn_dp_limit controls described threshold for the current process. Default is 65536, it is usually enough for most cases.

MDBX_opt_txn_dp_initial 

Controls the in-process initial allocation size for dirty pages list of a write transaction. Default is 1024.

MDBX_opt_spill_max_denominator 

Controls the in-process how maximal part of the dirty pages may be spilled when necessary.

The MDBX_opt_spill_max_denominator defines the denominator for limiting from the top for part of the current dirty pages may be spilled when the free room for a new dirty pages (i.e. distance to the MDBX_opt_txn_dp_limit threshold) is not enough to perform requested operation. Exactly max_pages_to_spill = dirty_pages - dirty_pages / N, where N is the value set by MDBX_opt_spill_max_denominator.

Should be in the range 0..255, where zero means no limit, i.e. all dirty pages could be spilled. Default is 8, i.e. no more than 7/8 of the current dirty pages may be spilled when reached the condition described above.

MDBX_opt_spill_min_denominator 

Controls the in-process how minimal part of the dirty pages should be spilled when necessary.

The MDBX_opt_spill_min_denominator defines the denominator for limiting from the bottom for part of the current dirty pages should be spilled when the free room for a new dirty pages (i.e. distance to the MDBX_opt_txn_dp_limit threshold) is not enough to perform requested operation. Exactly min_pages_to_spill = dirty_pages / N, where N is the value set by MDBX_opt_spill_min_denominator.

Should be in the range 0..255, where zero means no restriction at the bottom. Default is 8, i.e. at least the 1/8 of the current dirty pages should be spilled when reached the condition described above.

MDBX_opt_spill_parent4child_denominator 

Controls the in-process how much of the parent transaction dirty pages will be spilled while start each child transaction.

The MDBX_opt_spill_parent4child_denominator defines the denominator to determine how much of parent transaction dirty pages will be spilled explicitly while start each child transaction. Exactly pages_to_spill = dirty_pages / N, where N is the value set by MDBX_opt_spill_parent4child_denominator.

For a stack of nested transactions each dirty page could be spilled only once, and parent's dirty pages couldn't be spilled while child transaction(s) are running. Therefore a child transaction could reach MDBX_TXN_FULL when parent(s) transaction has spilled too less (and child reach the limit of dirty pages), either when parent(s) has spilled too more (since child can't spill already spilled pages). So there is no universal golden ratio.

Should be in the range 0..255, where zero means no explicit spilling will be performed during starting nested transactions. Default is 0, i.e. by default no spilling performed during starting nested transactions, that correspond historically behaviour.

MDBX_opt_merge_threshold_16dot16_percent 

Controls the in-process threshold of semi-empty pages merge.

Warning
This is experimental option and subject for change or removal.

This option controls the in-process threshold of minimum page fill, as used space of percentage of a page. Neighbour pages emptier than this value are candidates for merging. The threshold value is specified in 1/65536 of percent, which is equivalent to the 16-dot-16 fixed point format. The specified value must be in the range from 12.5% (almost empty) to 50% (half empty) which corresponds to the range from 8192 and to 32768 in units respectively.

Function Documentation

◆ mdbx_env_get_hsr()

LIBMDBX_API MDBX_hsr_func* mdbx_env_get_hsr ( const MDBX_env env)

Gets current Handle-Slow-Readers callback used to resolve database full/overflow issue due to a reader(s) which prevents the old data from being recycled.

See also
MDBX_hsr_func
mdbx_env_set_hsr()
Long-lived read transactions
Parameters
[in]envAn environment handle returned by mdbx_env_create().
Returns
A MDBX_hsr_func function or NULL if disabled or something wrong.

◆ mdbx_liberr2str()

LIBMDBX_API const char* mdbx_liberr2str ( int  errnum)

◆ mdbx_replace_ex()

LIBMDBX_API int mdbx_replace_ex ( MDBX_txn txn,
MDBX_dbi  dbi,
const MDBX_val key,
MDBX_val new_data,
MDBX_val old_data,
MDBX_put_flags_t  flags,
MDBX_preserve_func  preserver,
void *  preserver_context 
)

Variable Documentation

◆ mdbx_build

LIBMDBX_VERINFO_API const struct MDBX_build_info mdbx_build

libmdbx build information

◆ mdbx_version

LIBMDBX_VERINFO_API const struct MDBX_version_info mdbx_version

libmdbx version information