Operate options. More...

#include <mdbx.h++>

Public Member Functions
MDBX_CXX11_CONSTEXPR	operate_options () noexcept

MDBX_CXX11_CONSTEXPR	operate_options (const operate_options &) noexcept=default

MDBX_CXX14_CONSTEXPR operate_options &	operator= (const operate_options &) noexcept=default

	operate_options (MDBX_env_flags_t) noexcept

Public Attributes
bool	orphan_read_transactions {false}

bool	nested_write_transactions {false}

bool	exclusive {false}

bool	disable_readahead {false}

bool	disable_clear_memory {false}

Detailed Description

Operate options.

Constructor & Destructor Documentation

◆ operate_options() [1/3]

MDBX_CXX11_CONSTEXPR mdbx::env::operate_options::operate_options ( )

inlinenoexcept

◆ operate_options() [2/3]

MDBX_CXX11_CONSTEXPR mdbx::env::operate_options::operate_options ( const operate_options & )

defaultnoexcept

◆ operate_options() [3/3]

mdbx::env::operate_options::operate_options ( MDBX_env_flags_t )

noexcept

Member Function Documentation

◆ operator=()

MDBX_CXX14_CONSTEXPR operate_options& mdbx::env::operate_options::operator= ( const operate_options & )

defaultnoexcept

Member Data Documentation

◆ disable_clear_memory

bool mdbx::env::operate_options::disable_clear_memory {false}

Don't initialize malloc'ed memory before writing to datafile.

Don't initialize malloc'ed memory before writing to unused spaces in the data file. By default, memory for pages written to the data file is obtained using malloc. While these pages may be reused in subsequent transactions, freshly malloc'ed pages will be initialized to zeroes before use. This avoids persisting leftover data from other code (that used the heap and subsequently freed the memory) into the data file.

Note that many other system libraries may allocate and free memory from the heap for arbitrary uses. E.g., stdio may use the heap for file I/O buffers. This initialization step has a modest performance cost so some applications may want to disable it using this flag. This option can be a problem for applications which handle sensitive data like passwords, and it makes memory checkers like Valgrind noisy. This flag is not needed with MDBX_WRITEMAP, which writes directly to the mmap instead of using malloc for pages. The initialization is also skipped if MDBX_RESERVE is used; the caller is expected to overwrite all of the memory that was reserved in that case.

This flag may be changed at any time using mdbx_env_set_flags().

◆ disable_readahead

bool mdbx::env::operate_options::disable_readahead {false}

Don't do readahead.

Turn off readahead. Most operating systems perform readahead on read requests by default. This option turns it off if the OS supports it. Turning it off may help random read performance when the DB is larger than RAM and system RAM is full.

By default libmdbx dynamically enables/disables readahead depending on the actual database size and currently available memory. On the other hand, such automation has some limitation, i.e. could be performed only when DB size changing but can't tracks and reacts changing a free RAM availability, since it changes independently and asynchronously.

Note: The mdbx_is_readahead_reasonable() function allows to quickly find out whether to use readahead or not based on the size of the data and the amount of available memory.

This flag affects only at environment opening and can't be changed after.

◆ exclusive

bool mdbx::env::operate_options::exclusive {false}

Open environment in exclusive/monopolistic mode.

MDBX_EXCLUSIVE flag can be used as a replacement for MDB_NOLOCK, which don't supported by MDBX. In this way, you can get the minimal overhead, but with the correct multi-process and multi-thread locking.

with MDBX_EXCLUSIVE = open environment in exclusive/monopolistic mode or return MDBX_BUSY if environment already used by other process. The main feature of the exclusive mode is the ability to open the environment placed on a network share.
without MDBX_EXCLUSIVE = open environment in cooperative mode, i.e. for multi-process access/interaction/cooperation. The main requirements of the cooperative mode are:
1. data files MUST be placed in the LOCAL file system, but NOT on a network share.
2. environment MUST be opened only by LOCAL processes, but NOT over a network.
3. OS kernel (i.e. file system and memory mapping implementation) and all processes that open the given environment MUST be running in the physically single RAM with cache-coherency. The only exception for cache-consistency requirement is Linux on MIPS architecture, but this case has not been tested for a long time).

This flag affects only at environment opening but can't be changed after.

◆ nested_write_transactions

bool mdbx::env::operate_options::nested_write_transactions {false}

◆ orphan_read_transactions

bool mdbx::env::operate_options::orphan_read_transactions {false}

Tie reader locktable slots to read-only transactions instead of to threads.

Don't use Thread-Local Storage, instead tie reader locktable slots to MDBX_txn objects instead of to threads. So, mdbx_txn_reset() keeps the slot reserved for the MDBX_txn object. A thread may use parallel read-only transactions. And a read-only transaction may span threads if you synchronizes its use.

Applications that multiplex many user threads over individual OS threads need this option. Such an application must also serialize the write transactions in an OS thread, since MDBX's write locking is unaware of the user threads.

Note: Regardless to MDBX_NOTLS flag a write transaction entirely should always be used in one thread from start to finish. MDBX checks this in a reasonable manner and return the MDBX_THREAD_MISMATCH error in rules violation.