mdbx::env::operate_options Struct Reference

Operate options. More...

#include <mdbx.h++>

Public Member Functions
constexpr	operate_options () noexcept
constexpr	operate_options (const operate_options &) noexcept=default
constexpr operate_options &	operator= (const operate_options &) noexcept=default
	operate_options (MDBX_env_flags_t) noexcept

Public Attributes
bool	no_sticky_threads {false}
bool	nested_transactions {false}
	Разрешает вложенные транзакции ценой отключения MDBX_WRITEMAP и увеличением накладных расходов.
bool	exclusive {false}
bool	disable_readahead {false}
bool	disable_clear_memory {false}
bool	enable_validation {false}

Detailed Description

Operate options.

Constructor & Destructor Documentation

operate_options() [1/3]

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

inlineconstexprnoexcept

operate_options() [2/3]

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

constexprdefaultnoexcept

operate_options() [3/3]

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

noexcept

Member Function Documentation

operator=()

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

constexprdefaultnoexcept

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.

enable_validation

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

Extra validation of DB structure and pages content.

The MDBX_VALIDATION enabled the simple safe/careful mode for working with damaged or untrusted DB. However, a notable performance degradation should be expected.

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_transactions

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

Разрешает вложенные транзакции ценой отключения MDBX_WRITEMAP и увеличением накладных расходов.

no_sticky_threads

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

Unlinks transactions from threads as much as possible.

This option is intended for applications that multiplex multiple user-defined lightweight execution threads across separate operating system threads, such as in the GoLang and Rust runtimes. It is also recommended for such applications to serialize write transactions in a single operating system thread, since MDBX write locking uses basic synchronization system primitives and knows nothing about user threads and/or lightweight runtime threads. Anyway, at a minimum, it is absolutely necessary to ensure that each writing transaction is finished strictly in the same thread of the operating system where it was started.

Note

Starting from version 0.13, the MDBX_NOSTICKYTHREADS option completely replaces the MDBX_NOTLS option.

When using MDBX_NOSTICKYTHREADS, transactions become unrelated to system threads that created ones. Therefore, the API functions do not check the correspondence between the transaction and the current execution thread. Most functions that work with transactions and cursors can be called from any execution thread. However, it also becomes impossible to detect mistakes when transactions and/or cursors are used simultaneously in different threads.

Using MDBX_NOSTICKYTHREADS also narrows down the possibilities for resizing the database, as it loses the ability to track execution threads working with the database and suspend ones while the database is unmapped in RAM. Thus unmapping and remapping of a database file becomes impossible while at least one transaction in still present. In particular, for this reason, on Windows, reducing the database file is not possible until the database is closed by the last process working with it or until the database is subsequently opened in read-write mode.

Warning

Regardless of MDBX_NOSTICKYTHREADS and MDBX_NOTLS, it is not allowed to use API objects from different execution threads at the same time! It is entirely your responsibility to ensure that API objects are not used simultaneously from different execution threads!

Write transactions can only be finished in the same system execution thread where ones were started. This restriction follows from the requirements of most operating systems that the acquired synchronization primitive (mutex, semaphore, critical section) should be released only by the same system execution thread which acquires it.

Creating a cursor in the context of a transaction, binding a cursor to a transaction, unlinking a cursor from a transaction, and closing a cursor bound to a transaction are operations that use both a cursor itself and a corresponding transaction. Similarly, completing or aborting a transaction is an operation that uses both a transaction itself and all a cursors associated with it. In order to avoid damage to internal data structures, unpredictable behavior, database destruction and data loss, it is necessary to avoid the possibility of simultaneous use of any cursor or transactions from different execution threads.

When using MDBX_NOSTICKYTHREADS, reading transactions do not use TLS (Thread Local Storage), and the MVCC-snapshot lock slots in a readers table are becomes linked only to transactions. The completion of any threads does not lead to the release of MVCC snapshot locks until the transactions are explicitly completed, or until the corresponding process as a whole is completed. For writing transactions, there is no checking of the correspondence between the current execution thread and the thread that created the transaction. However, the commit or interruption of writing transactions must be performed strictly in the thread that started the transaction, since these operations are associated with the acquire and release of synchronization primitives (mutexes, semaphores, critical sections), for which most operating systems require the release only by the thread that acquired the resource.

This flag takes effect when the environment is opened and cannot be changed after.

---

The documentation for this struct was generated from the following file:

• mdbx.h++