Classes
struct	MDBX_stat
	Statistics for a table 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_gc_info_t
	Information about Garbage Collection and page usage. More...
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.meta
struct	MDBX_envinfo.mi_pgop_stat
struct	MDBX_envinfo.mi_dxbid
struct	MDBX_commit_latency.gc_prof
	Information for GC profiling. More...
struct	MDBX_commit_latency.gc_prof.pnl_merge_work
	Metrics of the amount of work and cost of merging lists of pages. More...
struct	MDBX_commit_latency.gc_prof.pnl_merge_self
	Metrics of the amount of work and cost of merging lists of pages. More...
struct	MDBX_gc_info_t.gc_reclaimable

Typedefs
typedef int(*	MDBX_table_enum_func) (void ctx, const MDBX_txn txn, const MDBX_val name, MDBX_db_flags_t flags, const struct MDBX_stat stat, MDBX_dbi dbi) noexcept
	A callback function for listing user's named tables.
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) noexcept
	A callback function used to enumerate the reader lock table.
typedef int(*	MDBX_gc_iter_func) (void ctx, const MDBX_txn txn, uint64_t span_txnid, size_t span_pgno, size_t span_length, bool span_is_reclaimable) noexcept
	A callback function for iterating GC entries.

Enumerations
enum	MDBX_dbi_state_t { MDBX_DBI_DIRTY = 0x01 , MDBX_DBI_STALE = 0x02 , MDBX_DBI_FRESH = 0x04 , MDBX_DBI_CREAT = 0x08 }
	DBI state bits returted by mdbx_dbi_flags_ex(). More...

Functions
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.
int	mdbx_env_stat (const MDBX_env env, MDBX_stat stat, size_t bytes)
	Return statistics about the MDBX environment.
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.
int	mdbx_env_info (const MDBX_env env, MDBX_envinfo info, size_t bytes)
	Return information about the MDBX environment.
int	mdbx_env_get_syncbytes (const MDBX_env env, size_t threshold)
	Get threshold to force flush the data buffers to disk, even any of MDBX_SAFE_NOSYNC flag in the environment.
int	mdbx_env_get_syncperiod (const MDBX_env env, unsigned period_seconds_16dot16)
	Get relative period since the last unsteady commit to force flush the data buffers to disk, even of MDBX_SAFE_NOSYNC flag in the environment.
LIBMDBX_API int	mdbx_env_get_flags (const MDBX_env env, unsigned flags)
	Get environment flags.
LIBMDBX_API int	mdbx_env_get_path (const MDBX_env env, const char *dest)
	Return the path that was used in mdbx_env_open().
LIBMDBX_API int	mdbx_env_get_pathW (const MDBX_env env, const wchar_t *dest)
	Return the path that was used in mdbx_env_open().
LIBMDBX_API int	mdbx_env_get_fd (const MDBX_env env, mdbx_filehandle_t fd)
	Return the file descriptor for the given environment.
intptr_t	mdbx_limits_pgsize_min (void)
	Returns the minimal database page size in bytes.
intptr_t	mdbx_limits_pgsize_max (void)
	Returns the maximal database page size in bytes.
LIBMDBX_API intptr_t	mdbx_limits_dbsize_min (intptr_t pagesize)
	Returns minimal 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 database size in bytes for given page size, or -1 if pagesize is invalid.
LIBMDBX_API intptr_t	mdbx_limits_keysize_max (intptr_t pagesize, MDBX_db_flags_t flags)
	Returns maximal key size in bytes for given page size and table flags, or -1 if pagesize is invalid.
LIBMDBX_API intptr_t	mdbx_limits_keysize_min (MDBX_db_flags_t flags)
	Returns minimal key size in bytes for given table flags.
LIBMDBX_API intptr_t	mdbx_limits_valsize_max (intptr_t pagesize, MDBX_db_flags_t flags)
	Returns maximal data size in bytes for given page size and table flags, or -1 if pagesize is invalid.
LIBMDBX_API intptr_t	mdbx_limits_valsize_min (MDBX_db_flags_t flags)
	Returns minimal data size in bytes for given table flags.
LIBMDBX_API intptr_t	mdbx_limits_pairsize4page_max (intptr_t pagesize, MDBX_db_flags_t flags)
	Returns maximal size of key-value pair to fit in a single page with the given size and table flags, or -1 if pagesize is invalid.
LIBMDBX_API intptr_t	mdbx_limits_valsize4page_max (intptr_t pagesize, MDBX_db_flags_t flags)
	Returns maximal data size in bytes to fit in a leaf-page or single large/overflow-page with the given page size and table flags, or -1 if pagesize is invalid.
LIBMDBX_API intptr_t	mdbx_limits_txnsize_max (intptr_t pagesize)
	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.
int	mdbx_env_get_maxreaders (const MDBX_env env, unsigned readers)
	Get the maximum number of threads/reader slots for the environment.
int	mdbx_env_get_maxdbs (const MDBX_env env, MDBX_dbi dbs)
	Get the maximum number of named tables for the environment.
LIBMDBX_API size_t	mdbx_default_pagesize (void)
	Returns the default size of database page for the current system.
LIBMDBX_API int	mdbx_get_sysraminfo (intptr_t page_size, intptr_t total_pages, intptr_t *avail_pages)
	Returns basic information about system RAM. This function provides a portable way to get information about available RAM and can be useful in that it returns the same information that libmdbx uses internally to adjust various options and control readahead.
LIBMDBX_API int	mdbx_env_get_maxkeysize_ex (const MDBX_env *env, MDBX_db_flags_t flags)
	Returns the maximum size of keys can put.
LIBMDBX_API int	mdbx_env_get_maxvalsize_ex (const MDBX_env *env, MDBX_db_flags_t flags)
	Returns the maximum size of data we can put.
LIBMDBX_API int	mdbx_env_get_maxkeysize (const MDBX_env *env)
LIBMDBX_API int	mdbx_env_get_pairsize4page_max (const MDBX_env *env, MDBX_db_flags_t flags)
	Returns maximal size of key-value pair to fit in a single page for specified table flags.
LIBMDBX_API int	mdbx_env_get_valsize4page_max (const MDBX_env *env, MDBX_db_flags_t flags)
	Returns maximal data size in bytes to fit in a leaf-page or single large/overflow-page for specified table flags.
LIBMDBX_API void *	mdbx_env_get_userctx (const MDBX_env *env)
	Returns an application information (a context pointer) associated with the environment.
LIBMDBX_API int	mdbx_txn_info (const MDBX_txn txn, MDBX_txn_info info, bool scan_rlt)
	Return information about the MDBX transaction.
LIBMDBX_API uint64_t	mdbx_txn_id (const MDBX_txn *txn)
	Return the transaction's ID.
LIBMDBX_API int	mdbx_enumerate_tables (const MDBX_txn txn, MDBX_table_enum_func func, void ctx)
	Enumerates user's named tables in a database.
LIBMDBX_API int	mdbx_dbi_stat (const MDBX_txn txn, MDBX_dbi dbi, MDBX_stat stat, size_t bytes)
	Retrieve statistics for a table.
LIBMDBX_API int	mdbx_dbi_dupsort_depthmask (const MDBX_txn txn, MDBX_dbi dbi, uint32_t mask)
	Retrieve depth (bitmask) information of nested dupsort (multi-value) B+trees for given table.
LIBMDBX_API int	mdbx_dbi_flags_ex (const MDBX_txn txn, MDBX_dbi dbi, unsigned flags, unsigned *state)
	Retrieve the DB flags and status for a table handle.
int	mdbx_dbi_flags (const MDBX_txn txn, MDBX_dbi dbi, unsigned flags)
	The shortcut to calling mdbx_dbi_flags_ex() with state=NULL for discarding it result.
LIBMDBX_API int	mdbx_is_dirty (const MDBX_txn txn, const void ptr)
	Determines whether the given address is on a dirty database page of the transaction or not.
LIBMDBX_API int	mdbx_reader_list (const MDBX_env env, MDBX_reader_list_func func, void ctx)
	Enumerate the entries in the reader lock table.
LIBMDBX_API int	mdbx_txn_straggler (const MDBX_txn txn, int percent)
	Returns a lag of the reading for the given transaction.
LIBMDBX_API int	mdbx_gc_info (MDBX_txn txn, MDBX_gc_info_t info, size_t bytes, MDBX_gc_iter_func iter_func, void *iter_ctx)
	Provides information of Garbage Collection and page usage.

Detailed Description

Class Documentation

◆ MDBX_stat

struct MDBX_stat

Statistics for a table 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 large/overflow pages
uint32_t	ms_psize	Size of a table page. This is the same for all tables in a database.

◆ MDBX_envinfo

struct MDBX_envinfo

Information about the environment.

See also: mdbx_env_info_ex()

Public Attributes
struct {
uint64_t	lower
uint64_t	upper
uint64_t	current
uint64_t	shrink
uint64_t	grow
}	mi_geo
uint64_t	mi_mapsize
uint64_t	mi_dxb_fsize
uint64_t	mi_dxb_fallocated
uint64_t	mi_last_pgno
uint64_t	mi_recent_txnid
uint64_t	mi_latter_reader_txnid
uint64_t	mi_self_latter_reader_txnid
uint64_t	mi_meta_txnid [3]
uint64_t	mi_meta_sign [3]
uint32_t	mi_maxreaders
uint32_t	mi_numreaders
uint32_t	mi_dxb_pagesize
uint32_t	mi_sys_pagesize
uint32_t	mi_sys_upcblk
uint32_t	mi_sys_ioblk
struct {
struct {
uint64_t	x
uint64_t	y
}	current
struct {
uint64_t	x
uint64_t	y
}	meta [3]
}	mi_bootid
	A mostly unique ID that is regenerated on each boot.
uint64_t	mi_unsync_volume
uint64_t	mi_autosync_threshold
uint32_t	mi_since_sync_seconds16dot16
uint32_t	mi_autosync_period_seconds16dot16
uint32_t	mi_since_reader_check_seconds16dot16
uint32_t	mi_mode
struct {
uint64_t	newly
uint64_t	cow
uint64_t	clone
uint64_t	split
uint64_t	merge
uint64_t	spill
uint64_t	unspill
uint64_t	wops
uint64_t	prefault
uint64_t	mincore
uint64_t	msync
uint64_t	fsync
}	mi_pgop_stat
struct {
uint64_t	x
uint64_t	y
}	mi_dxbid

Member Data Documentation

◆ mi_autosync_period_seconds16dot16

uint32_t MDBX_envinfo::mi_autosync_period_seconds16dot16

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

◆ mi_autosync_threshold

uint64_t MDBX_envinfo::mi_autosync_threshold

Current auto-sync threshold, see mdbx_env_set_syncbytes().

◆ [struct]

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.

◆ mi_dxb_fallocated

uint64_t MDBX_envinfo::mi_dxb_fallocated

Space allocated for the database file in a filesystem

◆ mi_dxb_fsize

uint64_t MDBX_envinfo::mi_dxb_fsize

Current database file size

◆ mi_dxb_pagesize

uint32_t MDBX_envinfo::mi_dxb_pagesize

Database pagesize

◆ [struct]

struct { ... } MDBX_envinfo::mi_dxbid

◆ [struct]

struct { ... } MDBX_envinfo::mi_geo

◆ mi_last_pgno

uint64_t MDBX_envinfo::mi_last_pgno

Number of the last used page

◆ mi_latter_reader_txnid

uint64_t MDBX_envinfo::mi_latter_reader_txnid

ID of the last reader transaction

◆ mi_mapsize

uint64_t MDBX_envinfo::mi_mapsize

Size of the database memory map

◆ mi_maxreaders

uint32_t MDBX_envinfo::mi_maxreaders

Total reader slots in the environment

◆ mi_meta_sign

uint64_t MDBX_envinfo::mi_meta_sign[3]

◆ mi_meta_txnid

uint64_t MDBX_envinfo::mi_meta_txnid[3]

◆ mi_mode

uint32_t MDBX_envinfo::mi_mode

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

◆ mi_numreaders

uint32_t MDBX_envinfo::mi_numreaders

Max reader slots used in the environment

◆ [struct]

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

◆ mi_recent_txnid

uint64_t MDBX_envinfo::mi_recent_txnid

ID of the last committed transaction

◆ mi_self_latter_reader_txnid

uint64_t MDBX_envinfo::mi_self_latter_reader_txnid

ID of the last reader transaction of this/current process

◆ mi_since_reader_check_seconds16dot16

uint32_t MDBX_envinfo::mi_since_reader_check_seconds16dot16

Time since the last readers check in 1/65536 of second, see mdbx_reader_check().

◆ mi_since_sync_seconds16dot16

uint32_t MDBX_envinfo::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.

◆ mi_sys_ioblk

uint32_t MDBX_envinfo::mi_sys_ioblk

Filesystem I/O block size

◆ mi_sys_pagesize

uint32_t MDBX_envinfo::mi_sys_pagesize

System pagesize

◆ mi_sys_upcblk

uint32_t MDBX_envinfo::mi_sys_upcblk

System "Unified Page Cache" block size

◆ mi_unsync_volume

uint64_t MDBX_envinfo::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_pget	Number of page get operations within this transaction if corresponding statistics enabled via MDBX_ENABLE_PGET_STAT build option.
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()

Public Attributes
uint32_t	preparation
	Duration of preparation (commit child transactions, update table's records and cursors destroying).
uint32_t	gc_wallclock
	Duration of GC update by wall clock.
uint32_t	audit
	Duration of internal audit if enabled.
uint32_t	write
	Duration of writing dirty/modified data pages to a filesystem, i.e. the summary duration of a write() syscalls during commit.
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	ending
	Duration of transaction ending (releasing resources).
uint32_t	whole
	The total duration of a commit.
uint32_t	gc_cputime
	User-mode CPU time spent on GC update.
struct {
uint32_t	wloops
	The number of GC update iterations is greater than 1 if there were repeats/restarts.
uint32_t	coalescences
	The number of iterations of merging GC items.
uint32_t	wipes
	The number of previous reliable/stable committed points erased when working in MDBX_UTTERLY_NOSYNC mode.
uint32_t	flushes
	The number of forced commits to disk to avoid the database growth when working outside of MDBX_UTTERLY_NOSYNC mode.
uint32_t	kicks
	The number of accesses to the Handle-Slow-Readers mechanism to avoid void the database growth.
uint32_t	work_counter
	Number of slow/deep path GC search for the sake of placement user's data.
uint32_t	work_rtime_monotonic
	The time "by the wall clock" spent reading and searching inside the GC for the user's data.
uint32_t	work_xtime_cpu
	The CPU time in user mode spent for preparing pages taken from the GC for user data, including paging ones from disk.
uint32_t	work_rsteps
	The number of search iterations inside GC when allocating pages for the sake of user's data.
uint32_t	work_xpages
	The number of requests to allocate page sequences for the sake of user's data.
uint32_t	work_majflt
	The number of page faults inside the GC when allocating and preparing pages for user's data.
uint32_t	self_counter
	The GC's slow path execution count is for the purposes of maintaining and updating the GC itself.
uint32_t	self_rtime_monotonic
	The time "by the wall clock" spent reading and searching inside the GC for the purposes of maintaining and updating the GC itself.
uint32_t	self_xtime_cpu
	The CPU time in user mode spent preparing pages taken from the GC for the purposes of maintaining and updating the GC itself, including swapping from disk.
uint32_t	self_rsteps
	The number of search iterations inside the GC when allocating pages for the purposes of maintaining and updating the GC itself.
uint32_t	self_xpages
	The number of page sequences allocation requests for the GC itself.
uint32_t	self_majflt
	The number of page faults within the GC when allocating and preparing pages for the GC itself.
struct {
uint32_t	time
uint64_t	volume
uint32_t	calls
}	pnl_merge_work
	Metrics of the amount of work and cost of merging lists of pages.
struct {
uint32_t	time
uint64_t	volume
uint32_t	calls
}	pnl_merge_self
uint32_t	max_reader_lag
	The maximum observed difference between the latest and oldest readed MVCC-snapshots.
uint32_t	max_retained_pages
	The maximum noticed number of pages withheld from reclaimed due to reading old MVCC-snapshots.
}	gc_prof
	Information for GC profiling.

Member Data Documentation

◆ audit

uint32_t MDBX_commit_latency::audit

Duration of internal audit if enabled.

◆ ending

uint32_t MDBX_commit_latency::ending

Duration of transaction ending (releasing resources).

◆ gc_cputime

uint32_t MDBX_commit_latency::gc_cputime

User-mode CPU time spent on GC update.

◆ [struct]

struct { ... } MDBX_commit_latency::gc_prof

Information for GC profiling.

Note: This data is shared for all processes working with a given database and stored in LCK-file.

Statistic is accumulated when all transactions are committed, but only in libmdbx builds with the MDBX_ENABLE_PROFGC option enabled. The collected statistics are returned to any process when using mdbx_txn_commit_ex() or mdbx_txn_checkpoint(), and at the same time they are reset to zero when top-level transactions (not nested) are committed.

◆ gc_wallclock

uint32_t MDBX_commit_latency::gc_wallclock

Duration of GC update by wall clock.

◆ preparation

uint32_t MDBX_commit_latency::preparation

Duration of preparation (commit child transactions, update table's records and cursors destroying).

◆ sync

uint32_t MDBX_commit_latency::sync

Duration of syncing written data to the disk/storage, i.e. the duration of a fdatasync() or a msync() syscall during commit.

◆ whole

uint32_t MDBX_commit_latency::whole

The total duration of a commit.

◆ write

uint32_t MDBX_commit_latency::write

Duration of writing dirty/modified data pages to a filesystem, i.e. the summary duration of a write() syscalls during commit.

◆ MDBX_gc_info_t

struct MDBX_gc_info_t

Information about Garbage Collection and page usage.

See also: mdbx_gc_info

Public Attributes
size_t	pages_total
size_t	pages_backed
size_t	pages_allocated
size_t	pages_gc
struct {
size_t	pages
struct MDBX_chk_histogram	span_histogram
struct MDBX_chk_histogram	pgno_distribution
}	gc_reclaimable
size_t	max_reader_lag
size_t	max_retained_pages

Member Data Documentation

◆ [struct]

struct { ... } MDBX_gc_info_t::gc_reclaimable

◆ max_reader_lag

size_t MDBX_gc_info_t::max_reader_lag

◆ max_retained_pages

size_t MDBX_gc_info_t::max_retained_pages

◆ pages_allocated

size_t MDBX_gc_info_t::pages_allocated

Number of pages currently allocated

◆ pages_backed

size_t MDBX_gc_info_t::pages_backed

Number of pages currently backed by a database file

◆ pages_gc

size_t MDBX_gc_info_t::pages_gc

Number of all pages within GC, includes a pages formes the B-tree structure of GC itself

◆ pages_total

size_t MDBX_gc_info_t::pages_total

Total number of pages in a database, i.e. the upper limit defined by geometry

◆ 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.

Public Attributes
struct {
uint64_t	x
uint64_t	y
}	current
struct {
uint64_t	x
uint64_t	y
}	meta [3]

Member Data Documentation

◆ current

◆ meta

◆ MDBX_envinfo.mi_bootid.current

struct MDBX_envinfo.mi_bootid.current

Class Members
uint64_t	x
uint64_t	y

◆ MDBX_envinfo.mi_bootid.meta

struct MDBX_envinfo.mi_bootid.meta

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	mincore	Number of mincore() calls
uint64_t	msync	Number of explicit msync-to-disk operations (not a pages)
uint64_t	newly	Quantity of a new pages added
uint64_t	prefault	Number of prefault write operations (not a pages)
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_envinfo.mi_dxbid

struct MDBX_envinfo.mi_dxbid

Class Members
uint64_t	x
uint64_t	y

◆ MDBX_commit_latency.gc_prof

struct MDBX_commit_latency.gc_prof

Information for GC profiling.

Note: This data is shared for all processes working with a given database and stored in LCK-file.

Statistic is accumulated when all transactions are committed, but only in libmdbx builds with the MDBX_ENABLE_PROFGC option enabled. The collected statistics are returned to any process when using mdbx_txn_commit_ex() or mdbx_txn_checkpoint(), and at the same time they are reset to zero when top-level transactions (not nested) are committed.

Public Attributes
uint32_t	wloops
	The number of GC update iterations is greater than 1 if there were repeats/restarts.
uint32_t	coalescences
	The number of iterations of merging GC items.
uint32_t	wipes
	The number of previous reliable/stable committed points erased when working in MDBX_UTTERLY_NOSYNC mode.
uint32_t	flushes
	The number of forced commits to disk to avoid the database growth when working outside of MDBX_UTTERLY_NOSYNC mode.
uint32_t	kicks
	The number of accesses to the Handle-Slow-Readers mechanism to avoid void the database growth.
uint32_t	work_counter
	Number of slow/deep path GC search for the sake of placement user's data.
uint32_t	work_rtime_monotonic
	The time "by the wall clock" spent reading and searching inside the GC for the user's data.
uint32_t	work_xtime_cpu
	The CPU time in user mode spent for preparing pages taken from the GC for user data, including paging ones from disk.
uint32_t	work_rsteps
	The number of search iterations inside GC when allocating pages for the sake of user's data.
uint32_t	work_xpages
	The number of requests to allocate page sequences for the sake of user's data.
uint32_t	work_majflt
	The number of page faults inside the GC when allocating and preparing pages for user's data.
uint32_t	self_counter
	The GC's slow path execution count is for the purposes of maintaining and updating the GC itself.
uint32_t	self_rtime_monotonic
	The time "by the wall clock" spent reading and searching inside the GC for the purposes of maintaining and updating the GC itself.
uint32_t	self_xtime_cpu
	The CPU time in user mode spent preparing pages taken from the GC for the purposes of maintaining and updating the GC itself, including swapping from disk.
uint32_t	self_rsteps
	The number of search iterations inside the GC when allocating pages for the purposes of maintaining and updating the GC itself.
uint32_t	self_xpages
	The number of page sequences allocation requests for the GC itself.
uint32_t	self_majflt
	The number of page faults within the GC when allocating and preparing pages for the GC itself.
struct {
uint32_t	time
uint64_t	volume
uint32_t	calls
}	pnl_merge_work
	Metrics of the amount of work and cost of merging lists of pages.
struct {
uint32_t	time
uint64_t	volume
uint32_t	calls
}	pnl_merge_self
uint32_t	max_reader_lag
	The maximum observed difference between the latest and oldest readed MVCC-snapshots.
uint32_t	max_retained_pages
	The maximum noticed number of pages withheld from reclaimed due to reading old MVCC-snapshots.

Member Data Documentation

◆ coalescences

The number of iterations of merging GC items.

◆ flushes

The number of forced commits to disk to avoid the database growth when working outside of MDBX_UTTERLY_NOSYNC mode.

◆ kicks

The number of accesses to the Handle-Slow-Readers mechanism to avoid void the database growth.

See also: MDBX_hsr_func

◆ max_reader_lag

The maximum observed difference between the latest and oldest readed MVCC-snapshots.

◆ max_retained_pages

The maximum noticed number of pages withheld from reclaimed due to reading old MVCC-snapshots.

◆ pnl_merge_self

◆ pnl_merge_work

Metrics of the amount of work and cost of merging lists of pages.

◆ self_counter

The GC's slow path execution count is for the purposes of maintaining and updating the GC itself.

◆ self_majflt

The number of page faults within the GC when allocating and preparing pages for the GC itself.

◆ self_rsteps

The number of search iterations inside the GC when allocating pages for the purposes of maintaining and updating the GC itself.

◆ self_rtime_monotonic

The time "by the wall clock" spent reading and searching inside the GC for the purposes of maintaining and updating the GC itself.

◆ self_xpages

The number of page sequences allocation requests for the GC itself.

◆ self_xtime_cpu

The CPU time in user mode spent preparing pages taken from the GC for the purposes of maintaining and updating the GC itself, including swapping from disk.

◆ wipes

The number of previous reliable/stable committed points erased when working in MDBX_UTTERLY_NOSYNC mode.

◆ wloops

The number of GC update iterations is greater than 1 if there were repeats/restarts.

◆ work_counter

Number of slow/deep path GC search for the sake of placement user's data.

◆ work_majflt

The number of page faults inside the GC when allocating and preparing pages for user's data.

◆ work_rsteps

The number of search iterations inside GC when allocating pages for the sake of user's data.

◆ work_rtime_monotonic

The time "by the wall clock" spent reading and searching inside the GC for the user's data.

◆ work_xpages

The number of requests to allocate page sequences for the sake of user's data.

◆ work_xtime_cpu

The CPU time in user mode spent for preparing pages taken from the GC for user data, including paging ones from disk.

◆ MDBX_commit_latency.gc_prof.pnl_merge_work

struct MDBX_commit_latency.gc_prof.pnl_merge_work

Metrics of the amount of work and cost of merging lists of pages.

Class Members
uint32_t	calls
uint32_t	time
uint64_t	volume

◆ MDBX_commit_latency.gc_prof.pnl_merge_self

struct MDBX_commit_latency.gc_prof.pnl_merge_self

Metrics of the amount of work and cost of merging lists of pages.

Class Members
uint32_t	calls
uint32_t	time
uint64_t	volume

◆ MDBX_gc_info_t.gc_reclaimable

struct MDBX_gc_info_t.gc_reclaimable

Class Members
size_t	pages	Number of reclaimable pages, including pending reserve within a current write transaction
struct MDBX_chk_histogram	pgno_distribution	Distribution of a reclaimable pages over the file of a database
struct MDBX_chk_histogram	span_histogram	Histogram of the spans length of a sequence(s) adjacent reclaimable pages

Typedef Documentation

◆ MDBX_gc_iter_func

typedef int(* MDBX_gc_iter_func) (void *ctx, const MDBX_txn *txn, uint64_t span_txnid, size_t span_pgno, size_t span_length, bool span_is_reclaimable) noexcept

noexcept

A callback function for iterating GC entries.

See also: mdbx_gc_info()

The callback function is called for each sequence of an adjacent pages inside GC, including single pages.

Note: This API has not been frozen yet, and there may be improvements and changes in subsequent versions.

Parameters

[in]	ctx	A pointer to the context passed by a similar parameter in mdbx_gc_info().
[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	span_txnid	A transaction ID and the same as MVCC-snapshot number of which the span is associated in reclaiming order.
[in]	span_pgno	The starting page number of a span.
[in]	span_length	The number of pages in a span, it is 1 for a single pages.
[in]	span_is_reclaimable	A boolean flag indicates the span is reclaimable for now either no.

Returns: Zero if an enumeration step is successful and should be continues, if another value is returned, it will be immediately returned to the caller without continuing an enumeration.

◆ MDBX_reader_list_func

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) noexcept

noexcept

A callback function used to enumerate the reader lock table.

Parameters

[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-snapshot number.
[in]	lag	The lag from a recent MVCC-snapshot, i.e. the number of committed write transactions since the current 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 be shrunk beyond this.
[in]	bytes_retained	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.

See also: mdbx_reader_list()

◆ MDBX_table_enum_func

typedef int(* MDBX_table_enum_func) (void *ctx, const MDBX_txn *txn, const MDBX_val *name, MDBX_db_flags_t flags, const struct MDBX_stat *stat, MDBX_dbi dbi) noexcept

noexcept

A callback function for listing user's named tables.

See also: mdbx_enumerate_tables()

Parameters

[in]	ctx	A pointer to the context passed by a similar parameter in mdbx_enumerate_tables().
[in]	txn	A transaction handle.
[in]	name	The name of a table.
[in]	flags	The MDBX_db_flags_t of a table
[in]	stat	Basic statistics MDBX_stat of a table.
[in]	dbi	The value of the DBI descriptor other than 0, if one was opened for this table. Either 0 if there is no such open descriptor.

Returns: Zero if an enumeration step is successful and should be continues, if another value is returned, it will be immediately returned to the caller without continuing an enumeration.

Enumeration Type Documentation

◆ MDBX_dbi_state_t

enum MDBX_dbi_state_t

DBI state bits returted by mdbx_dbi_flags_ex().

See also: mdbx_dbi_flags_ex()

Enumerator
MDBX_DBI_DIRTY	DB was written in this txn
MDBX_DBI_STALE	Cached Named-DB record is older than txnID
MDBX_DBI_FRESH	Named-DB handle opened in this txn
MDBX_DBI_CREAT	Named-DB handle created in this txn

Function Documentation

◆ mdbx_dbi_dupsort_depthmask()

LIBMDBX_API int mdbx_dbi_dupsort_depthmask	(	const MDBX_txn *	txn,
		MDBX_dbi	dbi,
		uint32_t *	mask )

Retrieve depth (bitmask) information of nested dupsort (multi-value) B+trees for given table.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dbi	A table handle returned by mdbx_dbi_open().
[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:

Return values

MDBX_THREAD_MISMATCH	Given transaction is not owned by current thread.
MDBX_EINVAL	An invalid parameter was specified.
MDBX_RESULT_TRUE	The dbi isn't a dupsort (multi-value) table.

◆ mdbx_dbi_flags()

int mdbx_dbi_flags	(	const MDBX_txn *	txn,
		MDBX_dbi	dbi,
		unsigned *	flags )

inline

The shortcut to calling mdbx_dbi_flags_ex() with state=NULL for discarding it result.

See also: MDBX_db_flags_t

◆ mdbx_dbi_flags_ex()

LIBMDBX_API int mdbx_dbi_flags_ex	(	const MDBX_txn *	txn,
		MDBX_dbi	dbi,
		unsigned *	flags,
		unsigned *	state )

Retrieve the DB flags and status for a table handle.

See also: MDBX_db_flags_t; MDBX_dbi_state_t

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dbi	A table handle returned by mdbx_dbi_open().
[out]	flags	Address where the flags will be returned.
[out]	state	Address where the state will be returned.

Returns: A non-zero error value on failure and 0 on success.

◆ mdbx_dbi_stat()

LIBMDBX_API int mdbx_dbi_stat	(	const MDBX_txn *	txn,
		MDBX_dbi	dbi,
		MDBX_stat *	stat,
		size_t	bytes )

Retrieve statistics for a table.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dbi	A table handle returned by mdbx_dbi_open().
[out]	stat	The address of an MDBX_stat structure where the statistics will be copied.
[in]	bytes	The size of MDBX_stat.

Returns: A non-zero error value on failure and 0 on success, some possible errors are:

Return values

MDBX_THREAD_MISMATCH	Given transaction is not owned by current thread.
MDBX_EINVAL	An invalid parameter was specified.

◆ mdbx_default_pagesize()

LIBMDBX_API size_t mdbx_default_pagesize ( void )

Returns the default size of database page for the current system.

Default size of database page depends on the size of the system page and usually exactly match it.

◆ mdbx_enumerate_tables()

LIBMDBX_API int mdbx_enumerate_tables	(	const MDBX_txn *	txn,
		MDBX_table_enum_func	func,
		void *	ctx )

Enumerates user's named tables in a database.

Enumerates user-created named tables by calling a user-specified visitor function for each named table. The enumeration continues until the named tables are exhausted, or until a result other than zero is returned from a user-defined callback function, which will be returned immediately as a result.

See also: MDBX_table_enum_func

Parameters

[in]	txn	A transaction started by mdbx_txn_begin().
[in]	func	A custom callback function with the signature MDBX_table_enum_func, which will be called for each table.
[in]	ctx	A pointer to some context that will be passed to the func() function as it is.

Returns: A non-zero error value on failure and 0 on success.

◆ mdbx_env_get_fd()

LIBMDBX_API int mdbx_env_get_fd	(	const MDBX_env *	env,
		mdbx_filehandle_t *	fd )

Return the file descriptor for the given environment.

Note: All MDBX file descriptors have FD_CLOEXEC and couldn't be used after exec() and or fork().

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[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:

Return values

MDBX_EINVAL An invalid parameter was specified.

◆ mdbx_env_get_flags()

LIBMDBX_API int mdbx_env_get_flags	(	const MDBX_env *	env,
		unsigned *	flags )

Get environment flags.

See also: mdbx_env_set_flags()

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[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:

Return values

MDBX_EINVAL An invalid parameter was specified.

◆ mdbx_env_get_maxdbs()

int mdbx_env_get_maxdbs	(	const MDBX_env *	env,
		MDBX_dbi *	dbs )

inline

Get the maximum number of named tables for the environment.

See also: mdbx_env_set_maxdbs()

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[out]	dbs	Address to store the maximum number of tables.

Returns: A non-zero error value on failure and 0 on success, some possible errors are:

Return values

MDBX_EINVAL An invalid parameter was specified.

◆ mdbx_env_get_maxkeysize()

LIBMDBX_API int mdbx_env_get_maxkeysize ( const MDBX_env * env )

Deprecated: Please use mdbx_env_get_maxkeysize_ex() and/or mdbx_env_get_maxvalsize_ex()

◆ mdbx_env_get_maxkeysize_ex()

LIBMDBX_API int mdbx_env_get_maxkeysize_ex	(	const MDBX_env *	env,
		MDBX_db_flags_t	flags )

Returns the maximum size of keys can put.

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[in]	flags	Table options (MDBX_DUPSORT, MDBX_INTEGERKEY and so on).

See also: db_flags

Returns: The maximum size of a key can write, or -1 if something is wrong.

◆ mdbx_env_get_maxreaders()

int mdbx_env_get_maxreaders	(	const MDBX_env *	env,
		unsigned *	readers )

inline

Get the maximum number of threads/reader slots for the environment.

See also: mdbx_env_set_maxreaders()

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[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:

Return values

MDBX_EINVAL An invalid parameter was specified.

◆ mdbx_env_get_maxvalsize_ex()

LIBMDBX_API int mdbx_env_get_maxvalsize_ex	(	const MDBX_env *	env,
		MDBX_db_flags_t	flags )

Returns the maximum size of data we can put.

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[in]	flags	Table options (MDBX_DUPSORT, MDBX_INTEGERKEY and so on).

See also: db_flags

Returns: The maximum size of a data can write, or -1 if something is wrong.

◆ mdbx_env_get_pairsize4page_max()

LIBMDBX_API int mdbx_env_get_pairsize4page_max	(	const MDBX_env *	env,
		MDBX_db_flags_t	flags )

Returns maximal size of key-value pair to fit in a single page for specified table flags.

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[in]	flags	Table options (MDBX_DUPSORT, MDBX_INTEGERKEY and so on).

See also: db_flags

Returns: The maximum size of a data can write, or -1 if something is wrong.

◆ mdbx_env_get_path()

LIBMDBX_API int mdbx_env_get_path	(	const MDBX_env *	env,
		const char **	dest )

Return the path that was used in mdbx_env_open().

Note: On Windows the mdbx_env_get_pathW() is recommended to use.

Parameters

[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.

Returns: A non-zero error value on failure and 0 on success, some possible errors are:

Return values

MDBX_EINVAL An invalid parameter was specified.

◆ mdbx_env_get_pathW()

LIBMDBX_API int mdbx_env_get_pathW	(	const MDBX_env *	env,
		const wchar_t **	dest )

Return the path that was used in mdbx_env_open().

Note: On Windows the mdbx_env_get_pathW() is recommended to use.

Parameters

[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.

Returns: A non-zero error value on failure and 0 on success, some possible errors are:

Return values

MDBX_EINVAL An invalid parameter was specified.

Note: Available only on Windows.

See also: mdbx_env_get_path()

◆ mdbx_env_get_syncbytes()

int mdbx_env_get_syncbytes	(	const MDBX_env *	env,
		size_t *	threshold )

inline

Get threshold to force flush the data buffers to disk, even any of MDBX_SAFE_NOSYNC flag in the environment.

See also: mdbx_env_set_syncbytes(); MDBX_opt_sync_bytes

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[out]	threshold	Address of an size_t to store the number of bytes of summary changes when a synchronous flush would be made.

Returns: A non-zero error value on failure and 0 on success, some possible errors are:

Return values

MDBX_EINVAL An invalid parameter was specified.

◆ mdbx_env_get_syncperiod()

int mdbx_env_get_syncperiod	(	const MDBX_env *	env,
		unsigned *	period_seconds_16dot16 )

inline

Get relative period since the last unsteady commit to force flush the data buffers to disk, even of MDBX_SAFE_NOSYNC flag in the environment.

See also: mdbx_env_set_syncperiod(); MDBX_opt_sync_period

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[out]	period_seconds_16dot16	Address of an size_t to store the period in 1/65536 of second when a synchronous flush would be made since the last unsteady commit.

Returns: A non-zero error value on failure and 0 on success, some possible errors are:

Return values

MDBX_EINVAL An invalid parameter was specified.

◆ mdbx_env_get_userctx()

LIBMDBX_API void * mdbx_env_get_userctx ( const MDBX_env * env )

Returns an application information (a context pointer) associated with the environment.

See also: mdbx_env_set_userctx()

Parameters

[in] env An environment handle returned by mdbx_env_create()

Returns: The pointer set by mdbx_env_set_userctx() or NULL if something wrong.

◆ mdbx_env_get_valsize4page_max()

LIBMDBX_API int mdbx_env_get_valsize4page_max	(	const MDBX_env *	env,
		MDBX_db_flags_t	flags )

Returns maximal data size in bytes to fit in a leaf-page or single large/overflow-page for specified table flags.

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[in]	flags	Table options (MDBX_DUPSORT, MDBX_INTEGERKEY and so on).

See also: db_flags

Returns: The maximum size of a data can write, or -1 if something is wrong.

◆ mdbx_env_info()

int mdbx_env_info	(	const MDBX_env *	env,
		MDBX_envinfo *	info,
		size_t	bytes )

inline

Return information about the MDBX environment.

Deprecated: Please use mdbx_env_info_ex() instead.

◆ mdbx_env_info_ex()

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.

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. Otherwise, if txn is null, then stat will be populated by a snapshot from the last committed write transaction, and at next time, other information can be returned.

Legacy mdbx_env_info() correspond to calling mdbx_env_info_ex() with the null txn argument.

Parameters

[in]	env	An environment handle returned by mdbx_env_create()
[in]	txn	A transaction handle returned by mdbx_txn_begin()
[out]	info	The address of an MDBX_envinfo structure where the information will be provided.
[in]	bytes	The actual size of MDBX_envinfo, this value is used to provide ABI compatibility.

Returns: A non-zero error value on failure and 0 on success.

◆ mdbx_env_stat()

int mdbx_env_stat	(	const MDBX_env *	env,
		MDBX_stat *	stat,
		size_t	bytes )

inline

Return statistics about the MDBX environment.

Deprecated: Please use mdbx_env_stat_ex() instead.

◆ mdbx_env_stat_ex()

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.

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. Otherwise, if txn is null, then stat will be populated by a snapshot from the last committed write transaction, and at next time, other information can be returned.

Legacy mdbx_env_stat() correspond to calling mdbx_env_stat_ex() with the null txn argument.

Parameters

[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.
[in]	bytes	The size of MDBX_stat.

Returns: A non-zero error value on failure and 0 on success.

◆ mdbx_gc_info()

LIBMDBX_API int mdbx_gc_info	(	MDBX_txn *	txn,
		MDBX_gc_info_t *	info,
		size_t	bytes,
		MDBX_gc_iter_func	iter_func,
		void *	iter_ctx )

Provides information of Garbage Collection and page usage.

Scans the whole GC to summarise information of GC state and page page usage for given transaction. During this optionaly iterages GC entries by calling a user-specified visitor function for each span of pages inside GC, excepting a pages formes the B-tree structure of GC itself. Such iteration continues until the GC items are exhausted, or until a result other than zero is returned from a user-defined callback function, which will be returned immediately as a result.

Note: This API has not been frozen yet, and there may be improvements and changes in subsequent versions.

See also: MDBX_gc_info_t; MDBX_gc_iter_func

Parameters

[in]	txn	A transaction started by mdbx_txn_begin().
[out]	info	The address of a MDBX_gc_info_t structure where the information will be provided.
[in]	bytes	The actual size of MDBX_gc_info_t, this value is used to provide ABI compatibility.
[in]	iter_func	A custom callback function with the signature MDBX_gc_iter_func, which will be called for each span.
[in]	iter_ctx	A pointer to some context that will be passed to the iter_func() function as it is.

Returns: A non-zero error value on failure and 0 on success, some possible errors are:

Return values

MDBX_EINVAL	An invalid parameter was specified.
MDBX_NOTFOUND	The GC is empty for now.

◆ mdbx_get_sysraminfo()

LIBMDBX_API int mdbx_get_sysraminfo	(	intptr_t *	page_size,
		intptr_t *	total_pages,
		intptr_t *	avail_pages )

Returns basic information about system RAM. This function provides a portable way to get information about available RAM and can be useful in that it returns the same information that libmdbx uses internally to adjust various options and control readahead.

Parameters

[out]	page_size	Optional address where the system page size will be stored.
[out]	total_pages	Optional address where the number of total RAM pages will be stored.
[out]	avail_pages	Optional address where the number of available/free RAM pages will be stored.

Returns: A non-zero error value on failure and 0 on success.

◆ mdbx_is_dirty()

LIBMDBX_API int mdbx_is_dirty	(	const MDBX_txn *	txn,
		const void *	ptr )

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.

"Dirty" pages are those that have already been changed during a write transaction. Accordingly, any further changes may result in such pages being overwritten. Therefore, all functions libmdbx performing changes inside the database as arguments should NOT get pointers to data in those pages. In turn, "not dirty" pages before modification will be copied.

In other words, data from dirty pages must either be copied before being passed as arguments for further processing or rejected at the argument 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 only way to ensure that the actual page header is physically located in the same memory page, including for multi-pages with long data.; In rare cases the function may return a false positive answer (MDBX_RESULT_TRUE when data is NOT on a dirty page), but never a false negative if the arguments are correct.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	ptr	The address of data to check.

Returns: A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, otherwise the error code.

Return values

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.

◆ mdbx_limits_dbsize_max()

LIBMDBX_API intptr_t mdbx_limits_dbsize_max ( intptr_t pagesize )

Returns maximal database size in bytes for given page size, or -1 if pagesize is invalid.

◆ mdbx_limits_dbsize_min()

LIBMDBX_API intptr_t mdbx_limits_dbsize_min ( intptr_t pagesize )

Returns minimal database size in bytes for given page size, or -1 if pagesize is invalid.

◆ mdbx_limits_keysize_max()

LIBMDBX_API intptr_t mdbx_limits_keysize_max	(	intptr_t	pagesize,
		MDBX_db_flags_t	flags )

Returns maximal key size in bytes for given page size and table flags, or -1 if pagesize is invalid.

See also: db_flags

◆ mdbx_limits_keysize_min()

LIBMDBX_API intptr_t mdbx_limits_keysize_min ( MDBX_db_flags_t flags )

Returns minimal key size in bytes for given table flags.

See also: db_flags

◆ mdbx_limits_pairsize4page_max()

LIBMDBX_API intptr_t mdbx_limits_pairsize4page_max	(	intptr_t	pagesize,
		MDBX_db_flags_t	flags )

Returns maximal size of key-value pair to fit in a single page with the given size and table flags, or -1 if pagesize is invalid.

See also: db_flags

◆ mdbx_limits_pgsize_max()

intptr_t mdbx_limits_pgsize_max ( void )

inline

Returns the maximal database page size in bytes.

◆ mdbx_limits_pgsize_min()

intptr_t mdbx_limits_pgsize_min ( void )

inline

Returns the minimal database page size in bytes.

◆ mdbx_limits_txnsize_max()

LIBMDBX_API intptr_t mdbx_limits_txnsize_max ( intptr_t pagesize )

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.

◆ mdbx_limits_valsize4page_max()

LIBMDBX_API intptr_t mdbx_limits_valsize4page_max	(	intptr_t	pagesize,
		MDBX_db_flags_t	flags )

Returns maximal data size in bytes to fit in a leaf-page or single large/overflow-page with the given page size and table flags, or -1 if pagesize is invalid.

See also: db_flags

◆ mdbx_limits_valsize_max()

LIBMDBX_API intptr_t mdbx_limits_valsize_max	(	intptr_t	pagesize,
		MDBX_db_flags_t	flags )

Returns maximal data size in bytes for given page size and table flags, or -1 if pagesize is invalid.

See also: db_flags

◆ mdbx_limits_valsize_min()

LIBMDBX_API intptr_t mdbx_limits_valsize_min ( MDBX_db_flags_t flags )

Returns minimal data size in bytes for given table flags.

See also: db_flags

◆ mdbx_reader_list()

LIBMDBX_API int mdbx_reader_list	(	const MDBX_env *	env,
		MDBX_reader_list_func	func,
		void *	ctx )

Enumerate the entries in the reader lock table.

Parameters

[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.

Returns: A non-zero error value on failure and 0 on success, or MDBX_RESULT_TRUE if the reader lock table is empty.

◆ mdbx_txn_id()

LIBMDBX_API uint64_t mdbx_txn_id ( const MDBX_txn * txn )

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.

Parameters

[in] txn A transaction handle returned by mdbx_txn_begin().

Returns: A transaction ID, valid if input is an active transaction, otherwise 0.

◆ mdbx_txn_info()

LIBMDBX_API int mdbx_txn_info	(	const MDBX_txn *	txn,
		MDBX_txn_info *	info,
		bool	scan_rlt )

Return information about the MDBX transaction.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin()
[out]	info	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.

Returns: A non-zero error value on failure and 0 on success.

◆ mdbx_txn_straggler()

LIBMDBX_API int mdbx_txn_straggler	(	const MDBX_txn *	txn,
		int *	percent )

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.

Deprecated: Please use mdbx_txn_info() instead.

Parameters

[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 negative value on failure.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Class Documentation

◆ MDBX_stat

◆ MDBX_envinfo

Public Attributes

Member Data Documentation

◆ mi_autosync_period_seconds16dot16

◆ mi_autosync_threshold

◆ [struct]

◆ mi_dxb_fallocated

◆ mi_dxb_fsize

◆ mi_dxb_pagesize

◆ [struct]

◆ [struct]

◆ mi_last_pgno

◆ mi_latter_reader_txnid

◆ mi_mapsize

◆ mi_maxreaders

◆ mi_meta_sign

◆ mi_meta_txnid

◆ mi_mode

◆ mi_numreaders

◆ [struct]

◆ mi_recent_txnid

◆ mi_self_latter_reader_txnid

◆ mi_since_reader_check_seconds16dot16

◆ mi_since_sync_seconds16dot16

◆ mi_sys_ioblk

◆ mi_sys_pagesize

◆ mi_sys_upcblk

◆ mi_unsync_volume

◆ MDBX_txn_info

◆ MDBX_commit_latency

Public Attributes

Member Data Documentation

◆ audit

◆ ending

◆ gc_cputime

◆ [struct]

◆ gc_wallclock

◆ preparation

◆ sync

◆ whole

◆ write

◆ MDBX_gc_info_t

Public Attributes

Member Data Documentation

◆ [struct]

◆ max_reader_lag

◆ max_retained_pages

◆ pages_allocated

◆ pages_backed

◆ pages_gc

◆ pages_total

◆ MDBX_envinfo.mi_geo

◆ MDBX_envinfo.mi_bootid

Public Attributes

Member Data Documentation

◆ current

◆ meta

◆ MDBX_envinfo.mi_bootid.current

◆ MDBX_envinfo.mi_bootid.meta

◆ MDBX_envinfo.mi_pgop_stat

◆ MDBX_envinfo.mi_dxbid

◆ MDBX_commit_latency.gc_prof

Public Attributes

Member Data Documentation

◆ coalescences

◆ flushes

◆ kicks

◆ max_reader_lag

◆ max_retained_pages

◆ pnl_merge_self

◆ pnl_merge_work

◆ self_counter

◆ self_majflt