libmdbx (2022-08-02T12:00:30+03:00)
One of the fastest compact embeddable key-value ACID database without WAL.
mdbx::env::operate_options Struct Reference

Operate options. More...

#include <mdbx.h++>

Public Member Functions

 operate_options () noexcept
 operate_options (const operate_options &) noexcept=default
operate_optionsoperator= (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::env::operate_options::operate_options ( )

◆ operate_options() [2/3]

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

◆ operate_options() [3/3]

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

Member Function Documentation

◆ operator=()

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

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.

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.

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.

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

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