RU

Group c_err

Modules > c_err

Public Types

Type	Name
enum	MDBX_error_t Errors and return codes.
typedef int(*	MDBX_hsr_func 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.

Public Functions

Type	Name
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.
LIBMDBX_API const char *	mdbx_liberr2str (int errnum) Returns a string describing only MDBX error numbers.
LIBMDBX_API const char *	mdbx_strerror (int errnum) Return a string describing a given error code.
LIBMDBX_API const char *	mdbx_strerror_ANSI2OEM (int errnum) Similar to mdbx_strerror() but returns Windows error-messages in the OEM-encoding for console utilities.
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_r_ANSI2OEM (int errnum, char * buf, size_t buflen) Similar to mdbx_strerror_r() but returns Windows error-messages in the OEM-encoding for console utilities.

Public Types Documentation

enum MDBX_error_t

Errors and return codes.

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_LCK = -30413,
    MDBX_DANGLING_DBI = -30412,
    MDBX_OUSTED = -30411,
    MDBX_MVCC_RETARDED = -30410,
    MDBX_LAGGARD_READER = -30409,
    MDBX_LAST_ADDED_ERRCODE = MDBX_LAGGARD_READER,
    MDBX_ENODATA = ENODATA,
    MDBX_EINVAL = EINVAL,
    MDBX_EACCESS = EACCES,
    MDBX_ENOMEM = ENOMEM,
    MDBX_EROFS = EROFS,
    MDBX_ENOSYS = ENOTSUP,
    MDBX_EIO = EIO,
    MDBX_EPERM = EPERM,
    MDBX_EINTR = EINTR,
    MDBX_EEXIST = EEXIST,
    MDBX_ENOFILE = ENOENT,
    MDBX_EREMOTE = EREMOTEIO,
    MDBX_EDEADLK = EDEADLK
};

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

See also: mdbx_strerror()

See also: mdbx_strerror_r()

See also: mdbx_liberr2str()

---

typedef MDBX_hsr_func

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.

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;

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

See also: mdbx_env_get_hsr()

See also: mdbx_txn_park()

See also: 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:

• env An environment handle returned by mdbx_env_create().
• txn The current write transaction which internally at the MDBX_MAP_FULL condition.
• pid A pid of the reader process.
• tid A thread_id of the reader thread.
• laggard An oldest read transaction number on which stalled.
• gap A lag from the last committed txn.
• 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.
• 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 value:

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

---

Public Functions Documentation

function mdbx_env_set_hsr

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.

LIBMDBX_API int mdbx_env_set_hsr (
    MDBX_env * env,
    MDBX_hsr_func hsr_callback
) 

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

See also: mdbx_env_get_hsr()

See also: mdbx_txn_park()

See also: Long-lived read transactions

Parameters:

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

Returns:

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

---

function mdbx_liberr2str

Returns a string describing only MDBX error numbers.

LIBMDBX_API const char * mdbx_liberr2str (
    int errnum
) 

Returns NULL for non-MDBX error codes. This function is thread-safe since it returns pointers to constant non-localized strings.

See also: mdbx_strerror() mdbx_strerror_r()

Parameters:

• errnum The error code.

---

function mdbx_strerror

Return a string describing a given error code.

LIBMDBX_API const char * mdbx_strerror (
    int errnum
) 

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:

• errnum The error code.

Returns:

"error message" The description of the error.

---

function mdbx_strerror_ANSI2OEM

Similar to mdbx_strerror() but returns Windows error-messages in the OEM-encoding for console utilities.

LIBMDBX_API const char * mdbx_strerror_ANSI2OEM (
    int errnum
) 

Bit of Windows' madness.

See also: mdbx_strerror_r_ANSI2OEM()

---

function mdbx_strerror_r

Return a string describing a given error code.

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

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

Parameters:

• errnum The error code.
• buf Buffer to store the error message.
• buflen The size of buffer to store the message.

Returns:

"error message" The description of the error.

---

function mdbx_strerror_r_ANSI2OEM

Similar to mdbx_strerror_r() but returns Windows error-messages in the OEM-encoding for console utilities.

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

Bit of Windows' madness.

See also: mdbx_strerror_ANSI2OEM()

---

---