Typedefs
typedef int	MDBX_hsr_func(const MDBX_env env, const MDBX_txn txn, mdbx_pid_t pid, mdbx_tid_t tid, uint64_t laggard, unsigned gap, size_t space, int retry) noexcept
	A Handle-Slow-Readers callback function to resolve database full/overflow issue due to a reader(s) which prevents the old data from being recycled.

Enumerations
enum	MDBX_error_t { MDBX_SUCCESS = 0 , MDBX_RESULT_FALSE = MDBX_SUCCESS , MDBX_RESULT_TRUE = -1 , MDBX_KEYEXIST = -30799 , MDBX_FIRST_LMDB_ERRCODE = MDBX_KEYEXIST , MDBX_NOTFOUND = -30798 , MDBX_PAGE_NOTFOUND = -30797 , MDBX_CORRUPTED = -30796 , MDBX_PANIC = -30795 , MDBX_VERSION_MISMATCH = -30794 , MDBX_INVALID = -30793 , MDBX_MAP_FULL = -30792 , MDBX_DBS_FULL = -30791 , MDBX_READERS_FULL = -30790 , MDBX_TXN_FULL = -30788 , MDBX_CURSOR_FULL = -30787 , MDBX_PAGE_FULL = -30786 , MDBX_UNABLE_EXTEND_MAPSIZE = -30785 , MDBX_INCOMPATIBLE = -30784 , MDBX_BAD_RSLOT = -30783 , MDBX_BAD_TXN = -30782 , MDBX_BAD_VALSIZE = -30781 , MDBX_BAD_DBI = -30780 , MDBX_PROBLEM = -30779 , MDBX_LAST_LMDB_ERRCODE = MDBX_PROBLEM , MDBX_BUSY = -30778 , MDBX_FIRST_ADDED_ERRCODE = MDBX_BUSY , MDBX_EMULTIVAL = -30421 , MDBX_EBADSIGN = -30420 , MDBX_WANNA_RECOVERY = -30419 , MDBX_EKEYMISMATCH = -30418 , MDBX_TOO_LARGE = -30417 , MDBX_THREAD_MISMATCH = -30416 , MDBX_TXN_OVERLAPPING = -30415 , MDBX_BACKLOG_DEPLETED = -30414 , MDBX_DUPLICATED_CLK = -30413 , MDBX_DANGLING_DBI = -30412 , MDBX_OUSTED = -30411 , MDBX_MVCC_RETARDED = -30410 , MDBX_LAST_ADDED_ERRCODE = MDBX_MVCC_RETARDED , MDBX_ENODATA = 9919 , MDBX_EINVAL = EINVAL , MDBX_EACCESS = EACCES , MDBX_ENOMEM = ENOMEM , MDBX_EROFS = EROFS , MDBX_ENOSYS = ENOSYS , MDBX_EIO = EIO , MDBX_EPERM = EPERM , MDBX_EINTR = EINTR , MDBX_ENOFILE = ENOENT , MDBX_EREMOTE = ENOTBLK , MDBX_EDEADLK = EDEADLK }
	Errors and return codes. More...

Functions
LIBMDBX_API const char *	mdbx_strerror (int errnum)
	Return a string describing a given error code.

LIBMDBX_API const char *	mdbx_strerror_r (int errnum, char *buf, size_t buflen)
	Return a string describing a given error code.

LIBMDBX_API const char *	mdbx_strerror_ANSI2OEM (int errnum)

LIBMDBX_API const char *	mdbx_strerror_r_ANSI2OEM (int errnum, char *buf, size_t buflen)

LIBMDBX_API int	mdbx_env_set_hsr (MDBX_env env, MDBX_hsr_func hsr_callback)
	Sets a Handle-Slow-Readers callback to resolve database full/overflow issue due to a reader(s) which prevents the old data from being recycled.

Detailed Description

Typedef Documentation

◆ MDBX_hsr_func

typedef int MDBX_hsr_func(const MDBX_env *env, const MDBX_txn *txn, mdbx_pid_t pid, mdbx_tid_t tid, uint64_t laggard, unsigned gap, size_t space, int retry) noexcept

noexcept

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

Read transactions prevent reuse of pages freed by newer write transactions, thus the database can grow quickly. This callback will be called when there is not enough space in the database (i.e. before increasing the database size or before MDBX_MAP_FULL error) and thus can be used to resolve issues with a "long-lived" read transactions.

See also: mdbx_env_set_hsr(); mdbx_env_get_hsr(); mdbx_txn_park(); Long-lived read transactions

Using this callback you can choose how to resolve the situation:

abort the write transaction with an error;
wait for the read transaction(s) to complete;
notify a thread performing a long-lived read transaction and wait for an effect;
kill the thread or whole process that performs the long-lived read transaction;

Depending on the arguments and needs, your implementation may wait, terminate a process or thread that is performing a long read, or perform some other action. In doing so it is important that the returned code always corresponds to the performed action.

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[in]	txn	The current write transaction which internally at the MDBX_MAP_FULL condition.
[in]	pid	A pid of the reader process.
[in]	tid	A thread_id of the reader thread.
[in]	laggard	An oldest read transaction number on which stalled.
[in]	gap	A lag from the last committed txn.
[in]	space	A space that actually become available for reuse after this reader finished. The callback function can take this value into account to evaluate the impact that a long-running transaction has.
[in]	retry	A retry number starting from 0. If callback has returned 0 at least once, then at end of current handling loop the callback function will be called additionally with negative `retry` value to notify about the end of loop. The callback function can use this fact to implement timeout reset logic while waiting for a readers.

Returns: The RETURN CODE determines the further actions libmdbx and must match the action which was executed by the callback:

Return values

-2	or less An error condition and the reader was not killed.
-1	The callback was unable to solve the problem and agreed on MDBX_MAP_FULL error; libmdbx should increase the database size or return MDBX_MAP_FULL error.
0	(zero) The callback solved the problem or just waited for a while, libmdbx should rescan the reader lock table and retry. This also includes a situation when corresponding transaction terminated in normal way by mdbx_txn_abort() or mdbx_txn_reset(), and my be restarted. I.e. reader slot don't needed to be cleaned from transaction.
1	Transaction aborted asynchronous and reader slot should be cleared immediately, i.e. read transaction will not continue but mdbx_txn_abort() nor mdbx_txn_reset() will be called later.
2	or great The reader process was terminated or killed, and libmdbx should entirely reset reader registration.

Enumeration Type Documentation

◆ MDBX_error_t

enum MDBX_error_t

Errors and return codes.

BerkeleyDB uses -30800 to -30999, we'll go under them

See also: mdbx_strerror(); mdbx_strerror_r(); mdbx_liberr2str()

Enumerator
MDBX_SUCCESS	Successful result
MDBX_RESULT_FALSE	Alias for MDBX_SUCCESS
MDBX_RESULT_TRUE	Successful result with special meaning or a flag
MDBX_KEYEXIST	key/data pair already exists
MDBX_FIRST_LMDB_ERRCODE	The first LMDB-compatible defined error code
MDBX_NOTFOUND	key/data pair not found (EOF)
MDBX_PAGE_NOTFOUND	Requested page not found - this usually indicates corruption
MDBX_CORRUPTED	Database is corrupted (page was wrong type and so on)
MDBX_PANIC	Environment had fatal error, i.e. update of meta page failed and so on.
MDBX_VERSION_MISMATCH	DB file version mismatch with libmdbx
MDBX_INVALID	File is not a valid MDBX file
MDBX_MAP_FULL	Environment mapsize reached
MDBX_DBS_FULL	Environment maxdbs reached
MDBX_READERS_FULL	Environment maxreaders reached
MDBX_TXN_FULL	Transaction has too many dirty pages, i.e transaction too big
MDBX_CURSOR_FULL	Cursor stack too deep - this usually indicates corruption, i.e branch-pages loop
MDBX_PAGE_FULL	Page has not enough space - internal error
MDBX_UNABLE_EXTEND_MAPSIZE	Database engine was unable to extend mapping, e.g. since address space is unavailable or busy. This can mean: Database size extended by other process beyond to environment mapsize and engine was unable to extend mapping while starting read transaction. Environment should be reopened to continue. Engine was unable to extend mapping during write transaction or explicit call of mdbx_env_set_geometry().
MDBX_INCOMPATIBLE	Environment or table is not compatible with the requested operation or the specified flags. This can mean: The operation expects an MDBX_DUPSORT / MDBX_DUPFIXED table. Opening a named DB when the unnamed DB has MDBX_DUPSORT / MDBX_INTEGERKEY. Accessing a data record as a named table, or vice versa. The table was dropped and recreated with different flags.
MDBX_BAD_RSLOT	Invalid reuse of reader locktable slot, e.g. read-transaction already run for current thread
MDBX_BAD_TXN	Transaction is not valid for requested operation, e.g. had errored and be must aborted, has a child/nested transaction, or is invalid
MDBX_BAD_VALSIZE	Invalid size or alignment of key or data for target table, either invalid table name
MDBX_BAD_DBI	The specified DBI-handle is invalid or changed by another thread/transaction
MDBX_PROBLEM	Unexpected internal error, transaction should be aborted
MDBX_LAST_LMDB_ERRCODE	The last LMDB-compatible defined error code
MDBX_BUSY	Another write transaction is running or environment is already used while opening with MDBX_EXCLUSIVE flag
MDBX_FIRST_ADDED_ERRCODE	The first of MDBX-added error codes
MDBX_EMULTIVAL	The specified key has more than one associated value
MDBX_EBADSIGN	Bad signature of a runtime object(s), this can mean: memory corruption or double-free; ABI version mismatch (rare case);
MDBX_WANNA_RECOVERY	Database should be recovered, but this could NOT be done for now since it opened in read-only mode
MDBX_EKEYMISMATCH	The given key value is mismatched to the current cursor position
MDBX_TOO_LARGE	Database is too large for current system, e.g. could NOT be mapped into RAM.
MDBX_THREAD_MISMATCH	A thread has attempted to use a not owned object, e.g. a transaction that started by another thread
MDBX_TXN_OVERLAPPING	Overlapping read and write transactions for the current thread
MDBX_BACKLOG_DEPLETED	Внутренняя ошибка возвращаемая в случае нехватки запаса свободных страниц при обновлении GC. Используется как вспомогательное средство для отладки. Note С точки зрения пользователя семантически равнозначна MDBX_PROBLEM.
MDBX_DUPLICATED_CLK	Alternative/Duplicate LCK-file is exists and should be removed manually
MDBX_DANGLING_DBI	Some cursors and/or other resources should be closed before table or corresponding DBI-handle could be (re)used and/or closed.
MDBX_OUSTED	The parked read transaction was outed for the sake of recycling old MVCC snapshots.
MDBX_MVCC_RETARDED	MVCC snapshot used by read transaction is outdated and could not be copied since corresponding meta-pages was overwritten.
MDBX_LAST_ADDED_ERRCODE
MDBX_ENODATA
MDBX_EINVAL
MDBX_EACCESS
MDBX_ENOMEM
MDBX_EROFS
MDBX_ENOSYS
MDBX_EIO
MDBX_EPERM
MDBX_EINTR
MDBX_ENOFILE
MDBX_EREMOTE
MDBX_EDEADLK

Function Documentation

◆ mdbx_env_set_hsr()

LIBMDBX_API int mdbx_env_set_hsr	(	MDBX_env *	env,
		MDBX_hsr_func *	hsr_callback )

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

The callback will only be triggered when the database is full due to a reader(s) prevents the old data from being recycled.

See also: MDBX_hsr_func; mdbx_env_get_hsr(); mdbx_txn_park(); Long-lived read transactions

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[in]	hsr_callback	A MDBX_hsr_func function or NULL to disable.

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

◆ mdbx_strerror()

LIBMDBX_API const char * mdbx_strerror ( int errnum )

Return a string describing a given error code.

This function is a superset of the ANSI C X3.159-1989 (ANSI C) strerror() function. If the error code is greater than or equal to 0, then the string returned by the system function strerror() is returned. If the error code is less than 0, an error string corresponding to the MDBX library error is returned. See errors for a list of MDBX-specific error codes.

mdbx_strerror() is NOT thread-safe because may share common internal buffer for system messages. The returned string must NOT be modified by the application, but MAY be modified by a subsequent call to mdbx_strerror(), strerror() and other related functions.

See also: mdbx_strerror_r()

Parameters

[in] errnum The error code.

Returns: "error message" The description of the error.

◆ mdbx_strerror_ANSI2OEM()

LIBMDBX_API const char * mdbx_strerror_ANSI2OEM ( int errnum )

Bit of Windows' madness. The similar to mdbx_strerror() but returns Windows error-messages in the OEM-encoding for console utilities.

See also: mdbx_strerror_r_ANSI2OEM()

◆ mdbx_strerror_r()

LIBMDBX_API const char * mdbx_strerror_r	(	int	errnum,
		char *	buf,
		size_t	buflen )

Return a string describing a given error code.

This function is a superset of the ANSI C X3.159-1989 (ANSI C) strerror() function. If the error code is greater than or equal to 0, then the string returned by the system function strerror() is returned. If the error code is less than 0, an error string corresponding to the MDBX library error is returned. See errors for a list of MDBX-specific error codes.

mdbx_strerror_r() is thread-safe since uses user-supplied buffer where appropriate. The returned string must NOT be modified by the application, since it may be pointer to internal constant string. However, there is no restriction if the returned string points to the supplied buffer.

See also: mdbx_strerror()

mdbx_liberr2str() returns string describing only MDBX error numbers but NULL for non-MDBX error codes. This function is thread-safe since return pointer to constant non-localized strings.

Parameters

[in]	errnum	The error code.
[in,out]	buf	Buffer to store the error message.
[in]	buflen	The size of buffer to store the message.

Returns: "error message" The description of the error.

◆ mdbx_strerror_r_ANSI2OEM()

LIBMDBX_API const char * mdbx_strerror_r_ANSI2OEM	(	int	errnum,
		char *	buf,
		size_t	buflen )

Bit of Windows' madness. The similar to mdbx_strerror_r() but returns Windows error-messages in the OEM-encoding for console utilities.

See also: mdbx_strerror_ANSI2OEM()

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ MDBX_hsr_func

Enumeration Type Documentation

◆ MDBX_error_t

Function Documentation

◆ mdbx_env_set_hsr()

◆ mdbx_strerror()

◆ mdbx_strerror_ANSI2OEM()

◆ mdbx_strerror_r()

◆ mdbx_strerror_r_ANSI2OEM()