Group c_statinfo

Classes

Type	Name
struct	MDBX_commit_latency Latency of commit stages in 1/65536 of seconds units.
struct	MDBX_commit_latency.gc_prof Information for GC profiling.
struct	MDBX_commit_latency.gc_prof.pnl_merge_self Metrics of the amount of work and cost of merging lists of pages.
struct	MDBX_commit_latency.gc_prof.pnl_merge_work Metrics of the amount of work and cost of merging lists of pages.
struct	MDBX_envinfo Information about the environment.
struct	MDBX_envinfo.mi_bootid A mostly unique ID that is regenerated on each boot.
struct	MDBX_envinfo.mi_bootid.current
struct	MDBX_envinfo.mi_bootid.meta
struct	MDBX_envinfo.mi_dxbid
struct	MDBX_envinfo.mi_geo
struct	MDBX_envinfo.mi_pgop_stat
struct	MDBX_gc_info_t Information about Garbage Collection and page usage.
struct	MDBX_gc_info_t.gc_reclaimable
struct	MDBX_stat Statistics for a table in the environment.
struct	MDBX_txn_info Information about the transaction.

Public Types

Type	Name
enum	MDBX_dbi_state_t DBI state bits returned by mdbx_dbi_flags_ex() .
typedef int(*	MDBX_gc_iter_func A callback function for iterating GC entries.
typedef int(*	MDBX_reader_list_func A callback function used to enumerate the reader lock table.
typedef int(*	MDBX_table_enum_func A callback function for listing user's named tables.

Public Functions

Type	Name
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.
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_dbi_flags_ex (const MDBX_txn * txn, MDBX_dbi dbi, unsigned * flags, unsigned * state) Retrieve the DB flags and status for a table handle.
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 size_t	mdbx_default_pagesize (void) Returns the default size of database page for the current system.
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_env_get_fd (const MDBX_env * env, mdbx_filehandle_t * fd) Return the file descriptor for the given environment.
LIBMDBX_API int	mdbx_env_get_flags (const MDBX_env * env, unsigned * flags) Get environment flags.
int	mdbx_env_get_maxdbs (const MDBX_env * env, MDBX_dbi * dbs) Get the maximum number of named tables for the environment.
LIBMDBX_API int	mdbx_env_get_maxkeysize (const MDBX_env * env)
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.
int	mdbx_env_get_maxreaders (const MDBX_env * env, unsigned * readers) Get the maximum number of threads/reader slots for the environment.
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_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_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() .
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 void *	mdbx_env_get_userctx (const MDBX_env * env) Returns an application information (a context pointer) associated with the environment.
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.
int	mdbx_env_info (const MDBX_env * env, MDBX_envinfo * info, size_t bytes) Return information 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_stat (const MDBX_env * env, MDBX_stat * stat, size_t bytes) Return statistics about the MDBX environment.
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.
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.
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_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 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_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_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_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.
intptr_t	mdbx_limits_pgsize_max (void) Returns the maximal database page size in bytes.
intptr_t	mdbx_limits_pgsize_min (void) Returns the minimal database page size in bytes.
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.
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_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 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 uint64_t	mdbx_txn_id (const MDBX_txn * txn) Return the transaction's ID.
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 int	mdbx_txn_straggler (const MDBX_txn * txn, int * percent) Returns a lag of the reading for the given transaction.

Public Types Documentation

enum MDBX_dbi_state_t

DBI state bits returned by mdbx_dbi_flags_ex() .

enum MDBX_dbi_state_t {
    MDBX_DBI_DIRTY = 0x01,
    MDBX_DBI_STALE = 0x02,
    MDBX_DBI_FRESH = 0x04,
    MDBX_DBI_CREAT = 0x08
};

See also: mdbx_dbi_flags_ex()

typedef MDBX_gc_iter_func

A callback function for iterating GC entries.

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;

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:

ctx A pointer to the context passed by a similar parameter in mdbx_gc_info().
txn A transaction handle returned by mdbx_txn_begin().
span_txnid A transaction ID and the same as MVCC-snapshot number of which the span is associated in reclaiming order.
span_pgno The starting page number of a span.
span_length The number of pages in a span, it is 1 for a single pages.
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.

typedef MDBX_reader_list_func

A callback function used to enumerate the reader lock table.

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;

Parameters:

ctx An arbitrary context pointer for the callback.
num The serial number during enumeration, starting from 1.
slot The reader lock table slot number.
txnid The ID of the transaction being read, i.e. the MVCC-snapshot number.
lag The lag from a recent MVCC-snapshot, i.e. the number of committed write transactions since the current read transaction started.
pid The reader process ID.
thread The reader thread ID.
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.
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()

typedef MDBX_table_enum_func

A callback function for listing user's named tables.

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;

See also: mdbx_enumerate_tables()

Parameters:

ctx A pointer to the context passed by a similar parameter in mdbx_enumerate_tables().
txn A transaction handle.
name The name of a table.
flags The MDBX_db_flags_t of a table
stat Basic statistics MDBX_stat of a table.
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.

Public Functions Documentation

function mdbx_dbi_dupsort_depthmask

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

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

Parameters:

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

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.

function mdbx_dbi_flags

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

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

See also: MDBX_db_flags_t

function mdbx_dbi_flags_ex

Retrieve the DB flags and status for a table handle.

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

See also: MDBX_db_flags_t

See also: MDBX_dbi_state_t

Parameters:

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

Returns:

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

function mdbx_dbi_stat

Retrieve statistics for a table.

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

Parameters:

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

Returns:

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

Return value:

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

function mdbx_default_pagesize

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

LIBMDBX_API size_t mdbx_default_pagesize (
    void
)

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

function mdbx_enumerate_tables

Enumerates user's named tables in a database.

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

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:

txn A transaction started by mdbx_txn_begin().
func A custom callback function with the signature MDBX_table_enum_func, which will be called for each table.
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.

function mdbx_env_get_fd

Return the file descriptor for the given environment.

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

Note:

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

Parameters:

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

MDBX_EINVAL An invalid parameter was specified.

function mdbx_env_get_flags

Get environment flags.

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

See also: mdbx_env_set_flags()

Parameters:

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

MDBX_EINVAL An invalid parameter was specified.

function mdbx_env_get_maxdbs

Get the maximum number of named tables for the environment.

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

See also: mdbx_env_set_maxdbs()

Parameters:

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

MDBX_EINVAL An invalid parameter was specified.

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

function mdbx_env_get_maxkeysize_ex

Returns the maximum size of keys can put.

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

Parameters:

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

function mdbx_env_get_maxreaders

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

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

See also: mdbx_env_set_maxreaders()

Parameters:

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

MDBX_EINVAL An invalid parameter was specified.

function mdbx_env_get_maxvalsize_ex

Returns the maximum size of data we can put.

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

Parameters:

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

function mdbx_env_get_pairsize4page_max

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

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

Parameters:

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

function mdbx_env_get_path

Return the path that was used in mdbx_env_open() .

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

Note:

On Windows the mdbx_env_get_pathW() is recommended to use.

Parameters:

env An environment handle returned by mdbx_env_create()
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 value:

MDBX_EINVAL An invalid parameter was specified.

function mdbx_env_get_pathW

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
)

Note:

On Windows the mdbx_env_get_pathW() is recommended to use.

Parameters:

env An environment handle returned by mdbx_env_create()
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 value:

MDBX_EINVAL An invalid parameter was specified.

Note:

Available only on Windows.

See also: mdbx_env_get_path()

function mdbx_env_get_syncbytes

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

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

See also: mdbx_env_set_syncbytes()

See also: MDBX_opt_sync_bytes

Parameters:

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

MDBX_EINVAL An invalid parameter was specified.

function mdbx_env_get_syncperiod

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.

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

See also: mdbx_env_set_syncperiod()

See also: MDBX_opt_sync_period

Parameters:

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

MDBX_EINVAL An invalid parameter was specified.

function mdbx_env_get_userctx

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

LIBMDBX_API void * mdbx_env_get_userctx (
    const MDBX_env * env
)

See also: mdbx_env_set_userctx()

Parameters:

env An environment handle returned by mdbx_env_create()

Returns:

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

function mdbx_env_get_valsize4page_max

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

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

Parameters:

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

function mdbx_env_info

Return information about the MDBX environment.

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

Deprecated

Please use mdbx_env_info_ex() instead.

function mdbx_env_info_ex

Return information 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
)

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:

env An environment handle returned by mdbx_env_create()
txn A transaction handle returned by mdbx_txn_begin()
info The address of an MDBX_envinfo structure where the information will be provided.
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.

function mdbx_env_stat

Return statistics about the MDBX environment.

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

Deprecated

Please use mdbx_env_stat_ex() instead.

function mdbx_env_stat_ex

Return statistics about the MDBX environment.

LIBMDBX_API int mdbx_env_stat_ex (
    const MDBX_env * env,
    const MDBX_txn * txn,
    MDBX_stat * stat,
    size_t bytes
)

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:

env An environment handle returned by mdbx_env_create().
txn A transaction handle returned by mdbx_txn_begin().
stat The address of an MDBX_stat structure where the statistics will be copied.
bytes The size of MDBX_stat.

Returns:

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

function mdbx_gc_info

Provides information of Garbage Collection and page usage.

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
)

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

See also: MDBX_gc_iter_func

Parameters:

txn A transaction started by mdbx_txn_begin().
info The address of a MDBX_gc_info_t structure where the information will be provided.
bytes The actual size of MDBX_gc_info_t, this value is used to provide ABI compatibility.
iter_func A custom callback function with the signature MDBX_gc_iter_func, which will be called for each span.
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 value:

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

function mdbx_get_sysraminfo

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_get_sysraminfo (
    intptr_t * page_size,
    intptr_t * total_pages,
    intptr_t * avail_pages
)

Parameters:

page_size Optional address where the system page size will be stored.
total_pages Optional address where the number of total RAM pages will be stored.
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.

function mdbx_is_dirty

Determines whether the given address is on a dirty database page of the transaction or not.

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

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.

Note:

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:

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

Returns:

A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, otherwise the error code.

Return value:

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.

function mdbx_limits_dbsize_max

Returns maximal 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
)

function mdbx_limits_dbsize_min

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

LIBMDBX_API intptr_t mdbx_limits_dbsize_min (
    intptr_t pagesize
)

function mdbx_limits_keysize_max

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_max (
    intptr_t pagesize,
    MDBX_db_flags_t flags
)

See also: db_flags

function mdbx_limits_keysize_min

Returns minimal key size in bytes for given table flags.

LIBMDBX_API intptr_t mdbx_limits_keysize_min (
    MDBX_db_flags_t flags
)

See also: db_flags

function mdbx_limits_pairsize4page_max

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_pairsize4page_max (
    intptr_t pagesize,
    MDBX_db_flags_t flags
)

See also: db_flags

function mdbx_limits_pgsize_max

Returns the maximal database page size in bytes.

inline intptr_t mdbx_limits_pgsize_max (
    void
)

function mdbx_limits_pgsize_min

Returns the minimal database page size in bytes.

inline intptr_t mdbx_limits_pgsize_min (
    void
)

function mdbx_limits_txnsize_max

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.

LIBMDBX_API intptr_t mdbx_limits_txnsize_max (
    intptr_t pagesize
)

function mdbx_limits_valsize4page_max

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_valsize4page_max (
    intptr_t pagesize,
    MDBX_db_flags_t flags
)

See also: db_flags

function mdbx_limits_valsize_max

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_max (
    intptr_t pagesize,
    MDBX_db_flags_t flags
)

See also: db_flags

function mdbx_limits_valsize_min

Returns minimal data size in bytes for given table flags.

LIBMDBX_API intptr_t mdbx_limits_valsize_min (
    MDBX_db_flags_t flags
)

See also: db_flags

function mdbx_reader_list

Enumerate the entries in the reader lock table.

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

Parameters:

env An environment handle returned by mdbx_env_create().
func A MDBX_reader_list_func function.
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.

function mdbx_txn_id

Return the transaction's ID.

LIBMDBX_API uint64_t mdbx_txn_id (
    const MDBX_txn * txn
)

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:

txn A transaction handle returned by mdbx_txn_begin().

Returns:

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

function mdbx_txn_info

Return information about the MDBX transaction.

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

Parameters:

txn A transaction handle returned by mdbx_txn_begin()
info The address of an MDBX_txn_info structure where the information will be copied.
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.

function mdbx_txn_straggler

Returns a lag of the reading for the given transaction.

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

Returns an information for estimate how much given read-only transaction is lagging relative to the actual head.

Deprecated

Please use mdbx_txn_info() instead.

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
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.