libmdbx  0.11.9.0 (2022-08-02T12:00:30+03:00)
One of the fastest compact embeddable key-value ACID database without WAL.
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) 1
 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

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

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]envAn environment handle returned by mdbx_env_create().
[in]txnThe current write transaction which internally at the MDBX_MAP_FULL condition.
[in]pidA pid of the reader process.
[in]tidA thread_id of the reader thread.
[in]laggardAn oldest read transaction number on which stalled.
[in]gapA lag from the last committed txn.
[in]spaceA 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]retryA 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
-2or less An error condition and the reader was not killed.
-1The 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.
1Transaction 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.
2or great The reader process was terminated or killed, and libmdbx should entirely reset reader registration.

Enumeration Type Documentation

◆ 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:

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]envAn environment handle returned by mdbx_env_create().
[in]hsr_callbackA 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]errnumThe 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]errnumThe error code.
[in,out]bufBuffer to store the error message.
[in]buflenThe 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()