Class 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
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 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)
env &	copy (const wchar_t * destination, bool compactify, bool force_dynamic_size=false)
env &	copy (const ::std::string & destination, bool compactify, bool force_dynamic_size=false)
env &	copy (const char * destination, bool compactify, bool force_dynamic_size=false)
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
	env (const env &) noexcept
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
MDBX_env *	handle () noexcept
bool	is_cooperative () const
bool	is_empty () const Checks whether the database is empty.
bool	is_exclusive () const
bool	is_nested_transactions_available () const
bool	is_pristine () const Returns `true` for a freshly created database, but`false` if at least one transaction was committed.
bool	is_readonly () const
bool	is_readwrite () const
bool	is_writemap () const
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
constexpr	operator const MDBX_env * () noexcept const
env &	operator= (const env &) noexcept
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_NODISCARD info	get_preopen_snapinfo (const wchar_t * pathname)
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)
bool	remove (const wchar_t * pathname, const remove_mode mode=just_remove)
bool	remove (const ::std::string & pathname, const remove_mode mode=just_remove)
bool	remove (const char * pathname, const remove_mode mode=just_remove)

Protected Attributes

Type	Name
MDBX_env *	handle_ = `{nullptr}`

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
};

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

function copy [2/6]

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

function copy [3/6]

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

function copy [4/6]

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

function copy [5/6]

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

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
)

function dbsize_max

Returns the maximal database size in bytes for the environment.

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

function dbsize_min

Returns the minimal database size in bytes for the environment.

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

function env [1/2]

constexpr mdbx::env::env () noexcept

function env [2/2]

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

function get_pagesize

Returns pagesize of this MDBX environment.

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

function get_path

Return the path that was used for opening the environment.

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

function handle [1/2]

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

function handle [2/2]

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

function is_cooperative

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

function is_empty

Checks whether the database is empty.

bool mdbx::env::is_empty () const

function is_exclusive

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

function is_nested_transactions_available

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

function is_pristine

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

bool mdbx::env::is_pristine () const

function is_readonly

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

function is_readwrite

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

function is_writemap

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

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

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

function operator MDBX_env *

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

function operator const MDBX_env *

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

function operator=

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

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

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

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

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

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

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

Public Static Functions Documentation

function default_pagesize

Returns default page size for current system/platform.

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

function get_preopen_snapinfo [1/2]

static inline MDBX_NODISCARD  info mdbx::env::get_preopen_snapinfo (
    const ::std::wstring & pathname
)

function get_preopen_snapinfo [2/2]

static inline MDBX_NODISCARD  info mdbx::env::get_preopen_snapinfo (
    const wchar_t * pathname
)

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
)

function remove [2/5]

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

function remove [3/5]

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

function remove [4/5]

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

function remove [5/5]

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

Protected Attributes Documentation

variable handle_

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 docs/mdbx.h++