libmdbx  0.11.9.0 (2022-08-02T12:00:30+03:00)
One of the fastest compact embeddable key-value ACID database without WAL.
Extra operations

Modules

 B-tree Traversal
 

Typedefs

typedef enum MDBX_copy_flags_t MDBX_copy_flags_t
 
typedef enum MDBX_env_delete_mode_t MDBX_env_delete_mode_t
 

Enumerations

enum  MDBX_copy_flags_t { MDBX_CP_DEFAULTS = 0 , MDBX_CP_COMPACT = 1u , MDBX_CP_FORCE_DYNAMIC_SIZE = 2u }
 Environment copy flags. More...
 
enum  MDBX_env_delete_mode_t { MDBX_ENV_JUST_DELETE = 0 , MDBX_ENV_ENSURE_UNUSED = 1 , MDBX_ENV_WAIT_FOR_UNUSED = 2 }
 Deletion modes for mdbx_env_delete(). More...
 

Functions

LIBMDBX_API int mdbx_env_delete (const char *pathname, MDBX_env_delete_mode_t mode)
 Delete the environment's files in a proper and multiprocess-safe way. More...
 
LIBMDBX_API int mdbx_env_copy (MDBX_env *env, const char *dest, MDBX_copy_flags_t flags)
 Copy an MDBX environment to the specified path, with options. More...
 
LIBMDBX_API int mdbx_env_copy2fd (MDBX_env *env, mdbx_filehandle_t fd, MDBX_copy_flags_t flags)
 Copy an environment to the specified file descriptor, with options. More...
 
LIBMDBX_API int mdbx_env_sync_ex (MDBX_env *env, bool force, bool nonblock)
 Flush the environment data buffers to disk. More...
 
int mdbx_env_sync (MDBX_env *env)
 The shortcut to calling mdbx_env_sync_ex() with the force=true and nonblock=false arguments. More...
 
int mdbx_env_sync_poll (MDBX_env *env)
 The shortcut to calling mdbx_env_sync_ex() with the force=false and nonblock=true arguments. More...
 
LIBMDBX_API int mdbx_is_readahead_reasonable (size_t volume, intptr_t redundancy)
 Find out whether to use readahead or not, based on the given database size and the amount of available memory. More...
 
LIBMDBX_API MDBX_cmp_funcmdbx_get_keycmp (MDBX_db_flags_t flags)
 Returns default internal key's comparator for given database flags. More...
 
LIBMDBX_API MDBX_cmp_funcmdbx_get_datacmp (MDBX_db_flags_t flags)
 Returns default internal data's comparator for given database flags. More...
 
LIBMDBX_API int mdbx_reader_check (MDBX_env *env, int *dead)
 Check for stale entries in the reader lock table. More...
 
LIBMDBX_API int mdbx_thread_register (const MDBX_env *env)
 Registers the current thread as a reader for the environment. More...
 
LIBMDBX_API int mdbx_thread_unregister (const MDBX_env *env)
 Unregisters the current thread as a reader for the environment. More...
 

Detailed Description

Typedef Documentation

◆ MDBX_copy_flags_t

◆ MDBX_env_delete_mode_t

Enumeration Type Documentation

◆ MDBX_copy_flags_t

Environment copy flags.

See also
mdbx_env_copy()
mdbx_env_copy2fd()
Enumerator
MDBX_CP_DEFAULTS 
MDBX_CP_COMPACT 

Copy with compactification: Omit free space from copy and renumber all pages sequentially

MDBX_CP_FORCE_DYNAMIC_SIZE 

Force to make resizeable copy, i.e. dynamic size instead of fixed

◆ MDBX_env_delete_mode_t

Deletion modes for mdbx_env_delete().

See also
mdbx_env_delete()
Enumerator
MDBX_ENV_JUST_DELETE 

Just delete the environment's files and directory if any.

Note
On POSIX systems, processes already working with the database will continue to work without interference until it close the environment.
On Windows, the behavior of MDB_ENV_JUST_DELETE is different because the system does not support deleting files that are currently memory mapped.
MDBX_ENV_ENSURE_UNUSED 

Make sure that the environment is not being used by other processes, or return an error otherwise.

MDBX_ENV_WAIT_FOR_UNUSED 

Wait until other processes closes the environment before deletion.

Function Documentation

◆ mdbx_env_copy()

LIBMDBX_API int mdbx_env_copy ( MDBX_env env,
const char *  dest,
MDBX_copy_flags_t  flags 
)

Copy an MDBX environment to the specified path, with options.

This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

Note
This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Restrictions & Caveats section.
Parameters
[in]envAn environment handle returned by mdbx_env_create(). It must have already been opened successfully.
[in]destThe pathname of a file in which the copy will reside. This file must not be already exist, but parent directory must be writable.
[in]flagsSpecifies options for this operation. This parameter must be bitwise OR'ing together any of the constants described here:
  • MDBX_CP_DEFAULTS Perform copy as-is without compaction, etc.
  • MDBX_CP_COMPACT Perform compaction while copying: omit free pages and sequentially renumber all pages in output. This option consumes little bit more CPU for processing, but may running quickly than the default, on account skipping free pages.
  • MDBX_CP_FORCE_DYNAMIC_SIZE Force to make resizeable copy, i.e. dynamic size instead of fixed.
Returns
A non-zero error value on failure and 0 on success.

◆ mdbx_env_copy2fd()

LIBMDBX_API int mdbx_env_copy2fd ( MDBX_env env,
mdbx_filehandle_t  fd,
MDBX_copy_flags_t  flags 
)

Copy an environment to the specified file descriptor, with options.

This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

See also
mdbx_env_copy()
Note
This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Restrictions & Caveats section.
Fails if the environment has suffered a page leak and the destination file descriptor is associated with a pipe, socket, or FIFO.
Parameters
[in]envAn environment handle returned by mdbx_env_create(). It must have already been opened successfully.
[in]fdThe file descriptor to write the copy to. It must have already been opened for Write access.
[in]flagsSpecial options for this operation.
See also
mdbx_env_copy()
Returns
A non-zero error value on failure and 0 on success.

◆ mdbx_env_delete()

LIBMDBX_API int mdbx_env_delete ( const char *  pathname,
MDBX_env_delete_mode_t  mode 
)

Delete the environment's files in a proper and multiprocess-safe way.

Parameters
[in]pathnameThe pathname for the database or the directory in which the database files reside.
[in]modeSpecifies deletion mode for the environment. This parameter must be set to one of the constants described above in the MDBX_env_delete_mode_t section.
Note
The MDBX_ENV_JUST_DELETE don't supported on Windows since system unable to delete a memory-mapped files.
Returns
A non-zero error value on failure and 0 on success, some possible errors are:
Return values
MDBX_RESULT_TRUENo corresponding files or directories were found, so no deletion was performed.

◆ mdbx_env_sync()

int mdbx_env_sync ( MDBX_env env)
inline

The shortcut to calling mdbx_env_sync_ex() with the force=true and nonblock=false arguments.

◆ mdbx_env_sync_ex()

LIBMDBX_API int mdbx_env_sync_ex ( MDBX_env env,
bool  force,
bool  nonblock 
)

Flush the environment data buffers to disk.

Unless the environment was opened with no-sync flags (MDBX_NOMETASYNC, MDBX_SAFE_NOSYNC and MDBX_UTTERLY_NOSYNC), then data is always written an flushed to disk when mdbx_txn_commit() is called. Otherwise mdbx_env_sync() may be called to manually write and flush unsynced data to disk.

Besides, mdbx_env_sync_ex() with argument force=false may be used to provide polling mode for lazy/asynchronous sync in conjunction with mdbx_env_set_syncbytes() and/or mdbx_env_set_syncperiod().

Note
This call is not valid if the environment was opened with MDBX_RDONLY.
Parameters
[in]envAn environment handle returned by mdbx_env_create()
[in]forceIf non-zero, force a flush. Otherwise, If force is zero, then will run in polling mode, i.e. it will check the thresholds that were set mdbx_env_set_syncbytes() and/or mdbx_env_set_syncperiod() and perform flush if at least one of the thresholds is reached.
[in]nonblockDon't wait if write transaction is running by other thread.
Returns
A non-zero error value on failure and MDBX_RESULT_TRUE or 0 on success. The MDBX_RESULT_TRUE means no data pending for flush to disk, and 0 otherwise. Some possible errors are:
Return values
MDBX_EACCESthe environment is read-only.
MDBX_BUSYthe environment is used by other thread and nonblock=true.
MDBX_EINVALan invalid parameter was specified.
MDBX_EIOan error occurred during synchronization.

◆ mdbx_env_sync_poll()

int mdbx_env_sync_poll ( MDBX_env env)
inline

The shortcut to calling mdbx_env_sync_ex() with the force=false and nonblock=true arguments.

◆ mdbx_get_datacmp()

LIBMDBX_API MDBX_cmp_func* mdbx_get_datacmp ( MDBX_db_flags_t  flags)

Returns default internal data's comparator for given database flags.

◆ mdbx_get_keycmp()

LIBMDBX_API MDBX_cmp_func* mdbx_get_keycmp ( MDBX_db_flags_t  flags)

Returns default internal key's comparator for given database flags.

◆ mdbx_is_readahead_reasonable()

LIBMDBX_API int mdbx_is_readahead_reasonable ( size_t  volume,
intptr_t  redundancy 
)

Find out whether to use readahead or not, based on the given database size and the amount of available memory.

Parameters
[in]volumeThe expected database size in bytes.
[in]redundancyAdditional reserve or overload in case of negative value.
Returns
A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, otherwise the error code:
Return values
MDBX_RESULT_TRUEReadahead is reasonable.
MDBX_RESULT_FALSEReadahead is NOT reasonable, i.e. MDBX_NORDAHEAD is useful to open environment by mdbx_env_open().
Otherwisethe error code.

◆ mdbx_reader_check()

LIBMDBX_API int mdbx_reader_check ( MDBX_env env,
int *  dead 
)

Check for stale entries in the reader lock table.

Parameters
[in]envAn environment handle returned by mdbx_env_create().
[out]deadNumber of stale slots that were cleared.
Returns
A non-zero error value on failure and 0 on success, or MDBX_RESULT_TRUE if a dead reader(s) found or mutex was recovered.

◆ mdbx_thread_register()

LIBMDBX_API int mdbx_thread_register ( const MDBX_env env)

Registers the current thread as a reader for the environment.

To perform read operations without blocking, a reader slot must be assigned for each thread. However, this assignment requires a short-term lock acquisition which is performed automatically. This function allows you to assign the reader slot in advance and thus avoid capturing the blocker when the read transaction starts firstly from current thread.

See also
mdbx_thread_unregister()
Note
Threads are registered automatically the first time a read transaction starts. Therefore, there is no need to use this function, except in special cases.
Parameters
[in]envAn environment handle returned by mdbx_env_create().
Returns
A non-zero error value on failure and 0 on success, or MDBX_RESULT_TRUE if thread is already registered.

◆ mdbx_thread_unregister()

LIBMDBX_API int mdbx_thread_unregister ( const MDBX_env env)

Unregisters the current thread as a reader for the environment.

To perform read operations without blocking, a reader slot must be assigned for each thread. However, the assigned reader slot will remain occupied until the thread ends or the environment closes. This function allows you to explicitly release the assigned reader slot.

See also
mdbx_thread_register()
Parameters
[in]envAn environment handle returned by mdbx_env_create().
Returns
A non-zero error value on failure and 0 on success, or MDBX_RESULT_TRUE if thread is not registered or already unregistered.