Error handling

Typedefs
typedef enum MDBX_error_t	MDBX_error_t
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) MDBX_CXX17_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. More...

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_LAST_ADDED_ERRCODE = MDBX_TXN_OVERLAPPING, 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 }
	Errors and return codes. More...

Functions
const LIBMDBX_API char *	mdbx_strerror (int errnum)
	Return a string describing a given error code. More...
const LIBMDBX_API char *	mdbx_strerror_r (int errnum, char *buf, size_t buflen)
	Return a string describing a given error code. More...
const LIBMDBX_API char *	mdbx_strerror_ANSI2OEM (int errnum)
const LIBMDBX_API 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. More...

Detailed Description

Typedef Documentation

MDBX_error_t

typedef enum MDBX_error_t MDBX_error_t

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

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 value to notify about the end of loop. The callback function can use this value to implement timeout logic while waiting for 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() or 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 database is not compatible with the requested operation or the specified flags. This can mean: The operation expects an MDBX_DUPSORT / MDBX_DUPFIXED database. Opening a named DB when the unnamed DB has MDBX_DUPSORT / MDBX_INTEGERKEY. Accessing a data record as a database, or vice versa. The database 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, or is invalid
MDBX_BAD_VALSIZE	Invalid size or alignment of key or data for target database, either invalid subDB 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_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

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

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

const LIBMDBX_API 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()

const LIBMDBX_API 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()

const LIBMDBX_API 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()

const LIBMDBX_API 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()