RU

Class mdbx::env

ClassList > mdbx > env

Unmanaged database environment. More...

• #include <mdbx.h++>

Inherited by the following classes: mdbx::env_managed

Classes

Type	Name
struct	geometry Database geometry for size management.
struct	limits A namespace-like holder of static functions returning the various libmdbx limits, the C++ counterpart of the mdbx_limits_*() C API.
struct	operate_options Operate options.
struct	operate_parameters Operate parameters.
struct	reader_info Reader information.
struct	reclaiming_options Garbage reclaiming options.
struct	sysraminfo Information about the system RAM, see mdbx_get_sysraminfo() .

Public Types

Type	Name
enum int	defrag_control Control values returned by the defragmentation progress visitor.
typedef ::MDBX_defrag_result_t	defrag_result The result of database defragmentation, see MDBX_defrag_result_t .
enum unsigned	durability Durability level.
enum	extra_runtime_option MDBX environment extra runtime options.
typedef ::MDBX_envinfo	info Information about the environment.
enum unsigned	mode Operation mode.
enum	remove_mode Deletion modes for remove() .
typedef ::MDBX_stat	stat Statistics for a database in the MDBX environment.

Public Static Attributes

Type	Name
durability	half_synchronous_weak_last = durability::half\_synchronous\_weak\_last
durability	lazy_weak_tail = /* multi line expression */
mode	nested_transactions = /* multi line expression */
mode	readonly = mode::readonly
durability	robust_synchronous = /* multi line expression */
durability	whole_fragile = /* multi line expression */
mode	write_file_io = /* multi line expression */
mode	write_mapped_io = /* multi line expression */

Public Functions

Type	Name
env &	copy (const ::mdbx::filesystem::path & destination, bool compactify, bool force_dynamic_size=false) Make a copy (backup) of an existing environment to the specified path.
env &	copy (const ::std::wstring & destination, bool compactify, bool force_dynamic_size=false) Make a copy (backup) of an existing environment to the specified path.
env &	copy (const wchar_t * destination, bool compactify, bool force_dynamic_size=false) Make a copy (backup) of an existing environment to the specified path.
env &	copy (const ::std::string & destination, bool compactify, bool force_dynamic_size=false) Make a copy (backup) of an existing environment to the specified path.
env &	copy (const char * destination, bool compactify, bool force_dynamic_size=false) Make a copy (backup) of an existing environment to the specified path.
env &	copy (filehandle fd, bool compactify, bool force_dynamic_size=false) Copy an environment to the specified file descriptor.
size_t	dbsize_max () const Returns the maximal database size in bytes for the environment.
size_t	dbsize_min () const Returns the minimal database size in bytes for the environment.
constexpr	env () noexcept Constructs an empty (null) environment.
	env (const env &) noexcept Copy constructor.
	env (env_managed &&) = delete
size_t	get_pagesize () const Returns pagesize of this MDBX environment.
const path_char *	get_path () const Return the path that was used for opening the environment.
const MDBX_env *	handle () noexcept const Returns the underlying C handle (read-only).
MDBX_env *	handle () noexcept Returns the underlying C handle.
bool	is_cooperative () const Checks whether the environment is cooperative, i.e. not exclusive.
bool	is_empty () const Checks whether the database is empty.
bool	is_exclusive () const Checks whether the environment is exclusive.
bool	is_nested_transactions_available () const Checks whether nested transactions are available.
bool	is_pristine () const Returns true for a freshly created database, butfalse if at least one transaction was committed.
bool	is_readonly () const Checks whether the environment is read-only.
bool	is_readwrite () const Checks whether the environment is read-write.
bool	is_writemap () const Checks whether the environment uses memory-mapped I/O for writes.
size_t	key_max (key_mode mode) const Returns the maximal key size in bytes for specified keys mode.
size_t	key_min (key_mode mode) noexcept const Returns the minimal key size in bytes for specified keys mode.
constexpr	operator MDBX_env * () noexcept Returns the underlying C handle.
constexpr	operator const MDBX_env * () noexcept const Returns the underlying C handle (read-only).
env &	operator= (const env &) noexcept Copy assignment operator.
env &	operator= (env_managed &&) = delete
bool	poll_sync_to_disk () Performs non-blocking polling of sync-to-disk thresholds.
env &	set_sync_period (const duration & period) Sets relative period since the last unsteady commit to force flush the data buffers to disk, for non-sync durability modes.
duration	sync_period () const Gets relative period since the last unsteady commit that used to force flush the data buffers to disk, for non-sync durability modes.
size_t	transaction_size_max () const Returns the maximal write transaction size (i.e. limit for summary volume of dirty pages) in bytes.
size_t	value_max (value_mode mode) const Returns the maximal value size in bytes for specified values mode.
size_t	value_min (value_mode mode) noexcept const Returns the minimal value size in bytes for specified values mode.

Public Static Functions

Type	Name
size_t	default_pagesize () noexcept Returns default page size for current system/platform.
MDBX_NODISCARD info	get_preopen_snapinfo (const ::std::wstring & pathname, MDBX_preopen_flags mode=MDBX_PREOPEN_PROPERLY) Provides information about a database, including meta-page and geometry, without opening it.
MDBX_NODISCARD info	get_preopen_snapinfo (const wchar_t * pathname, MDBX_preopen_flags mode=MDBX_PREOPEN_PROPERLY) Provides information about a database, including meta-page and geometry, without opening it.
bool	remove (const ::mdbx::filesystem::path & pathname, const remove_mode mode=just_remove) Removes the environment's files in a proper and multiprocess-safe way.
bool	remove (const ::std::wstring & pathname, const remove_mode mode=just_remove) Removes the environment's files in a proper and multiprocess-safe way.
bool	remove (const wchar_t * pathname, const remove_mode mode=just_remove) Removes the environment's files in a proper and multiprocess-safe way.
bool	remove (const ::std::string & pathname, const remove_mode mode=just_remove) Removes the environment's files in a proper and multiprocess-safe way.
bool	remove (const char * pathname, const remove_mode mode=just_remove) Removes the environment's files in a proper and multiprocess-safe way.

Protected Attributes

Type	Name
MDBX_env *	handle_ = {nullptr} The underlying C environment handle, null for an empty instance.

Detailed Description

Like other unmanaged classes, env allows copying and assignment for handles as a values, but does not manage nor destroys the represented underlying object from the own class destructor.

An environment supports multiple key-value tables (aka key-value maps, tables or sub-databases), all residing in the same shared-memory mapped file.

Public Types Documentation

enum defrag_control

Control values returned by the defragmentation progress visitor.

enum mdbx::env::defrag_control {
    proceed = 0,
    abort = -1,
    discontinue = 1
};

See also: defrag()

---

typedef defrag_result

The result of database defragmentation, see MDBX_defrag_result_t .

using mdbx::env::defrag_result = ::MDBX_defrag_result_t;

---

enum durability

Durability level.

enum mdbx::env::durability {
    robust_synchronous,
    half_synchronous_weak_last,
    lazy_weak_tail,
    whole_fragile
};

---

enum extra_runtime_option

MDBX environment extra runtime options.

enum mdbx::env::extra_runtime_option {
    max_maps = MDBX_opt_max_db,
    max_readers = MDBX_opt_max_readers,
    sync_bytes = MDBX_opt_sync_bytes,
    sync_period = MDBX_opt_sync_period,
    rp_augment_limit = MDBX_opt_rp_augment_limit,
    loose_limit = MDBX_opt_loose_limit,
    dp_reserve_limit = MDBX_opt_dp_reserve_limit,
    dp_limit = MDBX_opt_txn_dp_limit,
    dp_initial = MDBX_opt_txn_dp_initial,
    spill_max_denominator = MDBX_opt_spill_max_denominator,
    spill_min_denominator = MDBX_opt_spill_min_denominator,
    spill_parent4child_denominator = MDBX_opt_spill_parent4child_denominator,
    merge_threshold_dot16 = MDBX_opt_merge_threshold,
    writethrough_threshold = MDBX_opt_writethrough_threshold,
    prefault_write_enable = MDBX_opt_prefault_write_enable,
    gc_time_limit = MDBX_opt_gc_time_limit,
    prefer_waf_insteadof_balance = MDBX_opt_prefer_waf_insteadof_balance,
    subpage_limit = MDBX_opt_subpage_limit,
    subpage_room_threshold = MDBX_opt_subpage_room_threshold,
    subpage_reserve_prereq = MDBX_opt_subpage_reserve_prereq,
    subpage_reserve_limit = MDBX_opt_subpage_reserve_limit,
    split_reserve = MDBX_opt_split_reserve,
    presync_threshold = MDBX_opt_presync_threshold,
    shrink_retry_period = MDBX_opt_shrink_retry_period
};

See also: mdbx_env_set_option()

See also: mdbx_env_get_option()

---

typedef info

Information about the environment.

using mdbx::env::info = ::MDBX_envinfo;

---

enum mode

Operation mode.

enum mdbx::env::mode {
    readonly,
    write_file_io,
    write_mapped_io,
    nested_transactions = write_file_io
};

---

enum remove_mode

Deletion modes for remove() .

enum mdbx::env::remove_mode {
    just_remove = MDBX_ENV_JUST_DELETE,
    ensure_unused = MDBX_ENV_ENSURE_UNUSED,
    wait_for_unused = MDBX_ENV_WAIT_FOR_UNUSED
};

---

typedef stat

Statistics for a database in the MDBX environment.

using mdbx::env::stat = ::MDBX_stat;

---

Public Static Attributes Documentation

variable half_synchronous_weak_last

durability mdbx::env::half_synchronous_weak_last;

Deprecated

use mdbx::env::durability::half_synchronous_weak_last instead

---

variable lazy_weak_tail

durability mdbx::env::lazy_weak_tail;

Deprecated

use mdbx::env::durability::lazy_weak_tail instead

---

variable nested_transactions

mode mdbx::env::nested_transactions;

Deprecated

use mdbx::env::mode::nested_transactions instead

---

variable readonly

mode mdbx::env::readonly;

Deprecated

use mdbx::env::mode::readonly instead

---

variable robust_synchronous

durability mdbx::env::robust_synchronous;

Deprecated

use mdbx::env::durability::robust_synchronous instead

---

variable whole_fragile

durability mdbx::env::whole_fragile;

Deprecated

use mdbx::env::durability::whole_fragile instead

---

variable write_file_io

mode mdbx::env::write_file_io;

Deprecated

use mdbx::env::mode::write_file_io instead

---

variable write_mapped_io

mode mdbx::env::write_mapped_io;

Deprecated

use mdbx::env::mode::write_mapped_io instead

---

Public Functions Documentation

function copy [1/6]

Make a copy (backup) of an existing environment to the specified path.

env & mdbx::env::copy (
    const ::mdbx::filesystem::path & destination,
    bool compactify,
    bool force_dynamic_size=false
) 

Parameters:

• destination The path to the copy to be made.
• compactify Omit free space from the copy and renumber all pages sequentially.
• force_dynamic_size Force the dynamic size (grow/shrink) of the copy.

Returns:

A reference to this environment instance.

Exception:

• mdbx::error on failure.

---

function copy [2/6]

Make a copy (backup) of an existing environment to the specified path.

env & mdbx::env::copy (
    const ::std::wstring & destination,
    bool compactify,
    bool force_dynamic_size=false
) 

Parameters:

• destination The path to the copy to be made.
• compactify Omit free space from the copy and renumber all pages sequentially.
• force_dynamic_size Force the dynamic size (grow/shrink) of the copy.

Returns:

A reference to this environment instance.

---

function copy [3/6]

Make a copy (backup) of an existing environment to the specified path.

env & mdbx::env::copy (
    const wchar_t * destination,
    bool compactify,
    bool force_dynamic_size=false
) 

Parameters:

• destination The path to the copy to be made.
• compactify Omit free space from the copy and renumber all pages sequentially.
• force_dynamic_size Force the dynamic size (grow/shrink) of the copy.

Returns:

A reference to this environment instance.

---

function copy [4/6]

Make a copy (backup) of an existing environment to the specified path.

env & mdbx::env::copy (
    const ::std::string & destination,
    bool compactify,
    bool force_dynamic_size=false
) 

Parameters:

• destination The path to the copy to be made.
• compactify Omit free space from the copy and renumber all pages sequentially.
• force_dynamic_size Force the dynamic size (grow/shrink) of the copy.

Returns:

A reference to this environment instance.

---

function copy [5/6]

Make a copy (backup) of an existing environment to the specified path.

env & mdbx::env::copy (
    const char * destination,
    bool compactify,
    bool force_dynamic_size=false
) 

Parameters:

• destination The path to the copy to be made.
• compactify Omit free space from the copy and renumber all pages sequentially.
• force_dynamic_size Force the dynamic size (grow/shrink) of the copy.

Returns:

A reference to this environment instance.

---

function copy [6/6]

Copy an environment to the specified file descriptor.

env & mdbx::env::copy (
    filehandle fd,
    bool compactify,
    bool force_dynamic_size=false
) 

Parameters:

• fd The file descriptor.
• compactify The compactify argument.
• force_dynamic_size The force_dynamic_size argument.

Returns:

The environment instance.

---

function dbsize_max

Returns the maximal database size in bytes for the environment.

inline size_t mdbx::env::dbsize_max () const

Returns:

The maximal database size in bytes.

---

function dbsize_min

Returns the minimal database size in bytes for the environment.

inline size_t mdbx::env::dbsize_min () const

Returns:

The minimal database size in bytes.

---

function env [1/3]

Constructs an empty (null) environment.

constexpr mdbx::env::env () noexcept

---

function env [2/3]

Copy constructor.

mdbx::env::env (
    const env &
) noexcept

---

function env [3/3]

mdbx::env::env (
    env_managed &&
) = delete

---

function get_pagesize

Returns pagesize of this MDBX environment.

inline size_t mdbx::env::get_pagesize () const

Returns:

The database page size in bytes.

---

function get_path

Return the path that was used for opening the environment.

const path_char * mdbx::env::get_path () const

Returns:

The path used for opening, or nullptr for an empty instance.

---

function handle [1/2]

Returns the underlying C handle (read-only).

inline const MDBX_env * mdbx::env::handle () noexcept const

Returns:

The constant pointer to the MDBX_env object.

---

function handle [2/2]

Returns the underlying C handle.

inline MDBX_env * mdbx::env::handle () noexcept

Returns:

The mutable pointer to the MDBX_env object.

---

function is_cooperative

Checks whether the environment is cooperative, i.e. not exclusive.

inline bool mdbx::env::is_cooperative () const

Returns:

true if the environment can be used concurrently by processes.

---

function is_empty

Checks whether the database is empty.

bool mdbx::env::is_empty () const

Returns:

true if the database is empty.

---

function is_exclusive

Checks whether the environment is exclusive.

inline bool mdbx::env::is_exclusive () const

Returns:

true if the environment was opened in the exclusive mode.

---

function is_nested_transactions_available

Checks whether nested transactions are available.

inline bool mdbx::env::is_nested_transactions_available () const

Returns:

true if nested transactions can be used.

---

function is_pristine

Returns true for a freshly created database, butfalse if at least one transaction was committed.

bool mdbx::env::is_pristine () const

Returns:

true if the database is pristine.

---

function is_readonly

Checks whether the environment is read-only.

inline bool mdbx::env::is_readonly () const

Returns:

true if the environment is read-only.

---

function is_readwrite

Checks whether the environment is read-write.

inline bool mdbx::env::is_readwrite () const

Returns:

true if the environment is read-write.

---

function is_writemap

Checks whether the environment uses memory-mapped I/O for writes.

inline bool mdbx::env::is_writemap () const

Returns:

true if MDBX_WRITEMAP was used.

---

function key_max

Returns the maximal key size in bytes for specified keys mode.

inline size_t mdbx::env::key_max (
    key_mode mode
) const

Parameters:

• mode The operation mode.

Returns:

The maximal key size in bytes for specified keys mode.

---

function key_min

Returns the minimal key size in bytes for specified keys mode.

inline size_t mdbx::env::key_min (
    key_mode mode
) noexcept const

Parameters:

• mode The operation mode.

Returns:

The minimal key size in bytes for specified keys mode.

---

function operator MDBX_env *

Returns the underlying C handle.

inline constexpr mdbx::env::operator MDBX_env * () noexcept

Returns:

The mutable pointer to the MDBX_env object.

---

function operator const MDBX_env *

Returns the underlying C handle (read-only).

inline constexpr mdbx::env::operator const MDBX_env * () noexcept const

Returns:

The constant pointer to the MDBX_env object.

---

function operator=

Copy assignment operator.

env & mdbx::env::operator= (
    const env &
) noexcept

Returns:

A reference to this instance.

---

function operator=

env & mdbx::env::operator= (
    env_managed &&
) = delete

---

function poll_sync_to_disk

Performs non-blocking polling of sync-to-disk thresholds.

inline bool mdbx::env::poll_sync_to_disk () 

Returns:

True if sync done or no data to sync; false if the environment is busy by another thread.

---

function set_sync_period

Sets relative period since the last unsteady commit to force flush the data buffers to disk, for non-sync durability modes.

inline env & mdbx::env::set_sync_period (
    const duration & period
) 

The relative period value affects all processes which operates with given environment until the last process close environment or a new value will be settled. Data is always written to disk when txn_managed::commit() is called, but the operating system may keep it buffered. MDBX always flushes the OS buffers upon commit as well, unless the environment was opened with env::durability::whole_fragile, env::durability::lazy_weak_tail or in part env::durability::half_synchronous_weak_last. The settled period is not checked asynchronously, but only by the txn_managed::commit() and env::sync_to_disk() functions. Therefore, in cases where transactions are committed infrequently and/or irregularly, polling by env::poll_sync_to_disk() may be a reasonable solution to timeout enforcement.

The default is 0, which means that no timeout is checked and no additional flush will be made.

See also: extra_runtime_option::sync_period

Parameters:

• period The period in seconds.

Returns:

The environment instance.

---

function sync_period

Gets relative period since the last unsteady commit that used to force flush the data buffers to disk, for non-sync durability modes.

inline duration mdbx::env::sync_period () const

See set_sync_period() for the description of the period.

Returns:

The period as a duration value.

See also: set_sync_period(const duration&)

See also: extra_runtime_option::sync_period

---

function transaction_size_max

Returns the maximal write transaction size (i.e. limit for summary volume of dirty pages) in bytes.

inline size_t mdbx::env::transaction_size_max () const

Returns:

The maximal write transaction size in bytes.

---

function value_max

Returns the maximal value size in bytes for specified values mode.

inline size_t mdbx::env::value_max (
    value_mode mode
) const

Parameters:

• mode The operation mode.

Returns:

The maximal value size in bytes for specified values mode.

---

function value_min

Returns the minimal value size in bytes for specified values mode.

inline size_t mdbx::env::value_min (
    value_mode mode
) noexcept const

Parameters:

• mode The operation mode.

Returns:

The minimal value size in bytes for specified values mode.

---

Public Static Functions Documentation

function default_pagesize

Returns default page size for current system/platform.

static inline size_t mdbx::env::default_pagesize () noexcept

Returns:

The default page size in bytes.

---

function get_preopen_snapinfo [1/2]

Provides information about a database, including meta-page and geometry, without opening it.

static inline MDBX_NODISCARD  info mdbx::env::get_preopen_snapinfo (
    const ::std::wstring & pathname,
    MDBX_preopen_flags mode=MDBX_PREOPEN_PROPERLY
) 

Parameters:

• pathname The path to the directory or database file.
• mode The mode of processing weak checkpoints, see MDBX_preopen_flags. Defaults to MDBX_PREOPEN_PROPERLY (same as the legacy get_preopen_snapinfo()).

Returns:

The info of the database. Errors are thrown as mdbx::error.

See also: mdbx_preopen_snapinfo_ex()

---

function get_preopen_snapinfo [2/2]

Provides information about a database, including meta-page and geometry, without opening it.

static inline MDBX_NODISCARD  info mdbx::env::get_preopen_snapinfo (
    const wchar_t * pathname,
    MDBX_preopen_flags mode=MDBX_PREOPEN_PROPERLY
) 

Parameters:

• pathname The path to the directory or database file.
• mode The mode of processing weak checkpoints, see MDBX_preopen_flags. Defaults to MDBX_PREOPEN_PROPERLY (same as the legacy get_preopen_snapinfo()).

Returns:

The info of the database. Errors are thrown as mdbx::error.

See also: mdbx_preopen_snapinfo_ex()

---

function remove [1/5]

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

static bool mdbx::env::remove (
    const ::mdbx::filesystem::path & pathname,
    const remove_mode mode=just_remove
) 

Parameters:

• pathname The path to the database.
• mode The operation mode.

Returns:

true on success, false otherwise.

---

function remove [2/5]

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

static bool mdbx::env::remove (
    const ::std::wstring & pathname,
    const remove_mode mode=just_remove
) 

Parameters:

• pathname The path to the environment.
• mode The removal mode, see remove_mode.

Returns:

true on success, false otherwise.

---

function remove [3/5]

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

static bool mdbx::env::remove (
    const wchar_t * pathname,
    const remove_mode mode=just_remove
) 

Parameters:

• pathname The path to the environment.
• mode The removal mode, see remove_mode.

Returns:

true on success, false otherwise.

---

function remove [4/5]

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

static bool mdbx::env::remove (
    const ::std::string & pathname,
    const remove_mode mode=just_remove
) 

Parameters:

• pathname The path to the environment.
• mode The removal mode, see remove_mode.

Returns:

true on success, false otherwise.

---

function remove [5/5]

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

static bool mdbx::env::remove (
    const char * pathname,
    const remove_mode mode=just_remove
) 

Parameters:

• pathname The path to the environment.
• mode The removal mode, see remove_mode.

Returns:

true on success, false otherwise.

---

Protected Attributes Documentation

variable handle_

The underlying C environment handle, null for an empty instance.

MDBX_env* mdbx::env::handle_;

---

Friends Documentation

friend operator!=

inline bool mdbx::env::operator!= (
    const env & a,
    const env & b
) noexcept

---

friend operator==

inline bool mdbx::env::operator== (
    const env & a,
    const env & b
) noexcept

---

---

The documentation for this class was generated from the following file mdbx.h++