libmdbx  0.11.9.0 (2022-08-02T12:00:30+03:00)
One of the fastest compact embeddable key-value ACID database without WAL.
Statistics & Information

Classes

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_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
 

Typedefs

typedef enum MDBX_dbi_state_t MDBX_dbi_state_t
 
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) 1
 A callback function used to enumerate the reader lock table. More...
 

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. More...
 
MDBX_DEPRECATED int mdbx_env_stat (const MDBX_env *env, MDBX_stat *stat, size_t bytes)
 Return statistics about the MDBX environment. More...
 
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. More...
 
MDBX_DEPRECATED int mdbx_env_info (const MDBX_env *env, MDBX_envinfo *info, size_t bytes)
 Return information about the MDBX environment. More...
 
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. More...
 
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. More...
 
LIBMDBX_API int mdbx_env_get_flags (const MDBX_env *env, unsigned *flags)
 Get environment flags. More...
 
LIBMDBX_API int mdbx_env_get_path (const MDBX_env *env, const char **dest)
 Return the path that was used in mdbx_env_open(). More...
 
LIBMDBX_API int mdbx_env_get_fd (const MDBX_env *env, mdbx_filehandle_t *fd)
 Return the file descriptor for the given environment. More...
 
intptr_t mdbx_limits_pgsize_min (void)
 Returns the minimal database page size in bytes. More...
 
intptr_t mdbx_limits_pgsize_max (void)
 Returns the maximal database page size in bytes. More...
 
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. More...
 
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. More...
 
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 database flags, or -1 if pagesize is invalid. More...
 
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 database flags, or -1 if pagesize is invalid. More...
 
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. More...
 
int mdbx_env_get_maxreaders (const MDBX_env *env, unsigned *readers)
 Get the maximum number of threads/reader slots for the environment. More...
 
int mdbx_env_get_maxdbs (const MDBX_env *env, MDBX_dbi *dbs)
 Get the maximum number of named databases for the environment. More...
 
LIBMDBX_API size_t mdbx_default_pagesize (void)
 Returns the default size of database page for the current system. More...
 
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. More...
 
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. More...
 
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. More...
 
MDBX_DEPRECATED LIBMDBX_API int mdbx_env_get_maxkeysize (const MDBX_env *env)
 
LIBMDBX_API void * mdbx_env_get_userctx (const MDBX_env *env)
 Returns an application information (a context pointer) associated with the environment. More...
 
LIBMDBX_API int mdbx_txn_info (const MDBX_txn *txn, MDBX_txn_info *info, bool scan_rlt)
 Return information about the MDBX transaction. More...
 
LIBMDBX_API uint64_t mdbx_txn_id (const MDBX_txn *txn)
 Return the transaction's ID. More...
 
LIBMDBX_API int mdbx_dbi_stat (MDBX_txn *txn, MDBX_dbi dbi, MDBX_stat *stat, size_t bytes)
 Retrieve statistics for a database. More...
 
LIBMDBX_API int mdbx_dbi_dupsort_depthmask (MDBX_txn *txn, MDBX_dbi dbi, uint32_t *mask)
 Retrieve depth (bitmask) information of nested dupsort (multi-value) B+trees for given database. More...
 
LIBMDBX_API int mdbx_dbi_flags_ex (MDBX_txn *txn, MDBX_dbi dbi, unsigned *flags, unsigned *state)
 Retrieve the DB flags and status for a database handle. More...
 
int mdbx_dbi_flags (MDBX_txn *txn, MDBX_dbi dbi, unsigned *flags)
 The shortcut to calling mdbx_dbi_flags_ex() with state=NULL for discarding it result. More...
 
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. More...
 
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. More...
 
MDBX_DEPRECATED LIBMDBX_API int mdbx_txn_straggler (const MDBX_txn *txn, int *percent)
 Returns a lag of the reading for the given transaction. More...
 

Detailed Description


Class Documentation

◆ 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 the last steady sync in 1/65536 of second

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 Duration of GC/freeDB handling & updation.
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_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 merge

Page merges

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

Typedef Documentation

◆ MDBX_dbi_state_t

◆ 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) 1

A callback function used to enumerate the reader lock table.

Parameters
[in]ctxAn arbitrary context pointer for the callback.
[in]numThe serial number during enumeration, starting from 1.
[in]slotThe reader lock table slot number.
[in]txnidThe ID of the transaction being read, i.e. the MVCC-snapshot number.
[in]lagThe lag from a recent MVCC-snapshot, i.e. the number of committed write transactions since the current read transaction started.
[in]pidThe reader process ID.
[in]threadThe reader thread ID.
[in]bytes_usedThe number of last used page in the MVCC-snapshot which being read, i.e. database file can't shrinked beyond this.
[in]bytes_retainedThe 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()

Enumeration Type Documentation

◆ 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 

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 ( MDBX_txn txn,
MDBX_dbi  dbi,
uint32_t *  mask 
)

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

Parameters
[in]txnA transaction handle returned by mdbx_txn_begin().
[in]dbiA database handle returned by mdbx_dbi_open().
[out]maskThe 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_MISMATCHGiven transaction is not owned by current thread.
MDBX_EINVALAn invalid parameter was specified.
MDBX_RESULT_TRUEThe dbi isn't a dupsort (multi-value) database.

◆ mdbx_dbi_flags()

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

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

◆ mdbx_dbi_flags_ex()

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

Retrieve the DB flags and status for a database handle.

Parameters
[in]txnA transaction handle returned by mdbx_txn_begin().
[in]dbiA database handle returned by mdbx_dbi_open().
[out]flagsAddress where the flags will be returned.
[out]stateAddress 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 ( MDBX_txn txn,
MDBX_dbi  dbi,
MDBX_stat stat,
size_t  bytes 
)

Retrieve statistics for a database.

Parameters
[in]txnA transaction handle returned by mdbx_txn_begin().
[in]dbiA database handle returned by mdbx_dbi_open().
[out]statThe address of an MDBX_stat structure where the statistics will be copied.
[in]bytesThe size of MDBX_stat.
Returns
A non-zero error value on failure and 0 on success, some possible errors are:
Return values
MDBX_THREAD_MISMATCHGiven transaction is not owned by current thread.
MDBX_EINVALAn 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_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]envAn environment handle returned by mdbx_env_create().
[out]fdAddress 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_EINVALAn 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]envAn environment handle returned by mdbx_env_create().
[out]flagsThe 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_EINVALAn 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 databases for the environment.

See also
mdbx_env_set_maxdbs()
Parameters
[in]envAn environment handle returned by mdbx_env_create().
[out]dbsAddress to store the maximum number of databases.
Returns
A non-zero error value on failure and 0 on success, some possible errors are:
Return values
MDBX_EINVALAn invalid parameter was specified.

◆ mdbx_env_get_maxkeysize()

MDBX_DEPRECATED LIBMDBX_API int mdbx_env_get_maxkeysize ( const MDBX_env env)

◆ 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]envAn environment handle returned by mdbx_env_create().
[in]flagsDatabase 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]envAn environment handle returned by mdbx_env_create().
[out]readersAddress 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_EINVALAn 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]envAn environment handle returned by mdbx_env_create().
[in]flagsDatabase 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().

Parameters
[in]envAn environment handle returned by mdbx_env_create()
[out]destAddress 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_EINVALAn invalid parameter was specified.

◆ 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]envAn environment handle returned by mdbx_env_create().
[out]thresholdAddress 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_EINVALAn 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]envAn environment handle returned by mdbx_env_create().
[out]period_seconds_16dot16Address 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_EINVALAn 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]envAn environment handle returned by mdbx_env_create()
Returns
The pointer set by mdbx_env_set_userctx() or NULL if something wrong.

◆ mdbx_env_info()

MDBX_DEPRECATED 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]envAn environment handle returned by mdbx_env_create()
[in]txnA transaction handle returned by mdbx_txn_begin()
[out]infoThe address of an MDBX_envinfo structure where the information will be copied
[in]bytesThe size of MDBX_envinfo.
Returns
A non-zero error value on failure and 0 on success.

◆ mdbx_env_stat()

MDBX_DEPRECATED 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]envAn environment handle returned by mdbx_env_create()
[in]txnA transaction handle returned by mdbx_txn_begin()
[out]statThe address of an MDBX_stat structure where the statistics will be copied
[in]bytesThe size of MDBX_stat.
Returns
A non-zero error value on failure and 0 on success.

◆ 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_sizeOptional address where the system page size will be stored.
[out]total_pagesOptional address where the number of total RAM pages will be stored.
[out]avail_pagesOptional 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]txnA transaction handle returned by mdbx_txn_begin().
[in]ptrThe address of data to check.
Returns
A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, otherwise the error code:
Return values
MDBX_RESULT_TRUEGiven address is on the dirty page.
MDBX_RESULT_FALSEGiven address is NOT on the dirty page.
Otherwisethe 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 database 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_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 database flags, or -1 if pagesize is invalid.

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]envAn environment handle returned by mdbx_env_create().
[in]funcA MDBX_reader_list_func function.
[in]ctxAn 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]txnA 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]txnA transaction handle returned by mdbx_txn_begin()
[out]infoThe address of an MDBX_txn_info structure where the information will be copied.
[in]scan_rltThe 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()

MDBX_DEPRECATED 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]txnA transaction handle returned by mdbx_txn_begin().
[out]percentPercentage of page allocation in the database.
Returns
Number of transactions committed after the given was started for read, or negative value on failure.