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_write_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]

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

inlineconstexprnoexcept

operate_options() [2/3]

constexpr 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=()

constexpr 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_write_transactions

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

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

no_sticky_threads

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

Отвязывает транзакции от потоков/threads насколько это возможно.

Опция предназначена для приложений, которые мультиплексируют множество пользовательских легковесных потоков выполнения по отдельным потокам операционной системы, например как это происходит в средах выполнения GoLang и Rust. Таким приложениям также рекомендуется сериализовать транзакции записи в одном потоке операционной системы, поскольку блокировка записи MDBX использует базовые системные примитивы синхронизации и ничего не знает о пользовательских потоках и/или легковесных потоков среды выполнения. Как минимум, обязательно требуется обеспечить завершение каждой пишущей транзакции строго в том же потоке операционной системы где она была запущена.

Note

Начиная с версии v0.13 опция MDBX_NOSTICKYTHREADS полностью заменяет опцию MDBX_NOTLS.

При использовании MDBX_NOSTICKYTHREADS транзакции становятся не ассоциированными с создавшими их потоками выполнения. Поэтому в функциях API не выполняется проверка соответствия транзакции и текущего потока выполнения. Большинство функций работающих с транзакциями и курсорами становится возможным вызывать из любых потоков выполнения. Однако, также становится невозможно обнаружить ошибки одновременного использования транзакций и/или курсоров в разных потоках.

Использование MDBX_NOSTICKYTHREADS также сужает возможности по изменению размера БД, так как теряется возможность отслеживать работающие с БД потоки выполнения и приостанавливать их на время снятия отображения БД в ОЗУ. В частности, по этой причине на Windows уменьшение файла БД не возможно до закрытия БД последним работающим с ней процессом или до последующего открытия БД в режиме чтения-записи.

Warning

Вне зависимости от MDBX_NOSTICKYTHREADS и MDBX_NOTLS не допускается одновременно использование объектов API из разных потоков выполнения! Обеспечение всех мер для исключения одновременного использования объектов API из разных потоков выполнения целиком ложится на вас!

Транзакции записи могут быть завершены только в том же потоке выполнения где они были запущены. Это ограничение следует из требований большинства операционных систем о том, что захваченный примитив синхронизации (мьютекс, семафор, критическая секция) должен освобождаться только захватившим его потоком выполнения.

Создание курсора в контексте транзакции, привязка курсора к транзакции, отвязка курсора от транзакции и закрытие привязанного к транзакции курсора, являются операциями использующими как сам курсор так и соответствующую транзакцию. Аналогично, завершение или прерывание транзакции является операцией использующей как саму транзакцию, так и все привязанные к ней курсоры. Во избежание повреждения внутренних структур данных, непредсказуемого поведения, разрушение БД и потери данных следует не допускать возможности одновременного использования каких-либо курсора или транзакций из разных потоков выполнения.

Читающие транзакции при использовании MDBX_NOSTICKYTHREADS перестают использовать TLS (Thread Local Storage), а слоты блокировок MVCC-снимков в таблице читателей привязываются только к транзакциям. Завершение каких-либо потоков не приводит к снятию блокировок MVCC-снимков до явного завершения транзакций, либо до завершения соответствующего процесса в целом.

Для пишущих транзакций не выполняется проверка соответствия текущего потока выполнения и потока создавшего транзакцию. Однако, фиксация или прерывание пишущих транзакций должны выполняться строго в потоке запустившим транзакцию, так как эти операции связаны с захватом и освобождением примитивов синхронизации (мьютексов, критических секций), для которых большинство операционных систем требует освобождение только потоком захватившим ресурс.

Этот флаг вступает в силу при открытии среды и не может быть изменен после.

---

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

• mdbx.h++