libmdbx: merge with 0.3.2

1 files changed, 195 insertions, 62 deletions

diff --git a/libs/libmdbx/src/README-RU.md b/libs/libmdbx/src/README-RU.md
index 97888cbf88..e040b5c4bb 100644
--- a/libs/libmdbx/src/README-RU.md
+++ b/libs/libmdbx/src/README-RU.md
@@ -1,56 +1,55 @@
+### The [repository now only mirrored on the Github](https://abf.io/erthink/libmdbx) due to illegal discriminatory restrictions for Russian Crimea and for sovereign crimeans.
+<!-- Required extensions: pymdownx.betterem, pymdownx.tilde, pymdownx.emoji, pymdownx.tasklist, pymdownx.superfences -->
+-----
+
 libmdbx
 ======================================
-**The revised and extended descendant of [Symas LMDB](https://symas.com/lmdb/).**
-
-*The Future will Positive. Всё будет хорошо.*
-[![Build Status](https://travis-ci.org/leo-yuriev/libmdbx.svg?branch=master)](https://travis-ci.org/leo-yuriev/libmdbx)
-[![Build status](https://ci.appveyor.com/api/projects/status/ue94mlopn50dqiqg/branch/master?svg=true)](https://ci.appveyor.com/project/leo-yuriev/libmdbx/branch/master)
-[![Coverity Scan Status](https://scan.coverity.com/projects/12915/badge.svg)](https://scan.coverity.com/projects/reopen-libmdbx)
+Доработанный и расширенный потомок [Lightning Memory-Mapped Database](https://ru.bmstu.wiki/LMDB_(Lightning_Memory-Mapped_Database)) (aka _LMDB_).
+English version is [here](README.md).
 
-English version [by Google](https://translate.googleusercontent.com/translate_c?act=url&ie=UTF8&sl=ru&tl=en&u=https://github.com/leo-yuriev/libmdbx/tree/master)
-and [by Yandex](https://translate.yandex.ru/translate?url=https%3A%2F%2Fgithub.com%2FReOpen%2Flibmdbx%2Ftree%2Fmaster&lang=ru-en).
+_libmdbx_ превосходит LMDB по возможностям и надежности, не уступая в
+производительности. _libmdbx_ работает на Linux, FreeBSD, MacOS X и
+других ОС соответствующих POSIX.1-2008, а также поддерживает Windows в
+качестве дополнительной платформы.
 
-### Project Status
+Отдельно ведётся не-публичная разработка следующей версии, в которой
+будет кардинальное изменение как API, так и формата базы данных. Цель
+этой революции - обеспечение более четкого и надежного API, добавление
+новых функций, а также наделение базы данных новыми свойствами.
 
-**Сейчас MDBX _активно перерабатывается_** предстоит
-большое изменение как API, так и формата базы данных. К сожалению,
-обновление приведет к потере совместимости с предыдущими версиями.
+*Всё будет хорошо. The Future will (be) [Positive](https://www.ptsecurity.ru).*
 
-Цель этой революции - обеспечение более четкого надежного API и
-добавление новых функции, а также наделение базы данных новыми
-свойствами.
-
-В настоящее время MDBX предназначена для Linux, а также поддерживает
-Windows (начиная с Windows Server 2008) в качестве дополнительной
-платформы. Поддержка других ОС может быть обеспечена на коммерческой
-основе. Однако такие усовершенствования (т. е. pull-requests) могут быть
-приняты в мейнстрим только в том случае, если будет доступен
-соответствующий публичный и бесплатный сервис непрерывной интеграции
-(aka Continuous Integration).
+[![Build Status](https://travis-ci.org/leo-yuriev/libmdbx.svg?branch=master)](https://travis-ci.org/leo-yuriev/libmdbx)
+[![Build status](https://ci.appveyor.com/api/projects/status/ue94mlopn50dqiqg/branch/master?svg=true)](https://ci.appveyor.com/project/leo-yuriev/libmdbx/branch/master)
+[![Coverity Scan Status](https://scan.coverity.com/projects/12915/badge.svg)](https://scan.coverity.com/projects/reopen-libmdbx)
 
 ## Содержание
 - [Обзор](#Обзор)
-  - [Сравнение с другими СУБД](#Сравнение-с-другими-СУБД)
-  - [История & Acknowledgments](#История)
-- [Основные свойства](#Основные-свойства)
-- [Доработки и усовершенствования относительно LMDB](#Доработки-и-усовершенствования-относительно-lmdb)
-- [Недостатки и Компромиссы](#Недостатки-и-Компромиссы)
-  - [Проблема долгих чтений](#Проблема-долгих-чтений)
-  - [Сохранность данных в режиме асинхронной фиксации](#Сохранность-данных-в-режиме-асинхронной-фиксации)
+    - [Сравнение с другими базами данных](#Сравнение-с-другими-базами-данных)
+    - [История & Выражение признательности](#История)
+- [Описание](#Описание)
+    - [Ключевые свойства](#Ключевые-свойства)
+    - [Доработки и усовершенствования относительно LMDB](#Доработки-и-усовершенствования-относительно-lmdb)
+    - [Недостатки и Компромиссы](#Недостатки-и-Компромиссы)
+        - [Проблема долгих чтений](#Проблема-долгих-чтений)
+        - [Сохранность данных в режиме асинхронной фиксации](#Сохранность-данных-в-режиме-асинхронной-фиксации)
+- [Использование](#Использование)
+    - [Сборка](#Сборка)
+    - [Привязки к другим языкам](#Привязки-к-другим-языкам)
 - [Сравнение производительности](#Сравнение-производительности)
-  - [Интегральная производительность](#Интегральная-производительность)
-  - [Масштабируемость чтения](#Масштабируемость-чтения)
-  - [Синхронная фиксация](#Синхронная-фиксация)
-  - [Отложенная фиксация](#Отложенная-фиксация)
-  - [Асинхронная фиксация](#Асинхронная-фиксация)
-  - [Потребление ресурсов](#Потребление-ресурсов)
+    - [Интегральная производительность](#Интегральная-производительность)
+    - [Масштабируемость чтения](#Масштабируемость-чтения)
+    - [Синхронная фиксация](#Синхронная-фиксация)
+    - [Отложенная фиксация](#Отложенная-фиксация)
+    - [Асинхронная фиксация](#Асинхронная-фиксация)
+    - [Потребление ресурсов](#Потребление-ресурсов)
 
+-----
 
 ## Обзор
 _libmdbx_ - это встраиваемый key-value движок хранения со специфическим
 набором свойств и возможностей, ориентированный на создание уникальных
-легковесных решений с предельной производительностью под Linux и
-Windows.
+легковесных решений с предельной производительностью.
 
 _libmdbx_ позволяет множеству процессов совместно читать и обновлять
 несколько key-value таблиц с соблюдением
@@ -79,11 +78,12 @@ _libmdbx_ не использует
 сценарии использования.
 
 
-### Сравнение с другими СУБД
-Ввиду того, что в _libmdbx_ сейчас происходит революция, я посчитал
-лучшим решением ограничится здесь ссылкой на [главу Comparison with
-other databases](https://github.com/coreos/bbolt#comparison-with-other-databases)
-в описании _BoltDB_.
+### Сравнение с другими базами данных
+
+На данный момент, пожалуйста, обратитесь к [главе "сравнение BoltDB с
+другими базами
+данных"](https://github.com/coreos/bbolt#comparison-with-other-databases),
+которая также (в основном) применима к MDBX.
 
 
 ### История
@@ -104,16 +104,20 @@ Tables](https://github.com/leo-yuriev/libfpta), aka ["Позитивные
 Technologies](https://www.ptsecurity.ru).
 
 
-#### Acknowledgments
-Howard Chu (Symas Corporation) - the author of LMDB, from which
-originated the MDBX in 2015.
+### Выражение признательности
+
+Говард Чу (Howard Chu) <hyc@openldap.org> является автором движка LMDB, от
+которого в 2015 году произошел MDBX.
+
+Мартин Хеденфальк (Martin Hedenfalk) <martin@bzero.se> является автором кода
+`btree.c`, который использовался для начала разработки LMDB.
 
-Martin Hedenfalk <martin@bzero.se> - the author of `btree.c` code, which
-was used for begin development of LMDB.
+-----
 
+Описание
+========
 
-Основные свойства
-=================
+## Ключевые свойства
 
 _libmdbx_ наследует все ключевые возможности и особенности своего
 прародителя
@@ -168,8 +172,7 @@ Amplification Factor) и RAF (Read Amplification Factor) также Olog(N).
 кэшированием. Всё необходимое штатно выполняет ядро ОС.
 
 
-Доработки и усовершенствования относительно LMDB
-================================================
+## Доработки и усовершенствования относительно LMDB
 
 1. Автоматическое динамическое управление размером БД согласно
 параметрам задаваемым функцией `mdbx_env_set_geometry()`, включая шаг
@@ -328,7 +331,25 @@ Amplification Factor) и RAF (Read Amplification Factor) также Olog(N).
   >  - попытки повторного освобождения памяти;
   >  - повреждение памяти и ошибки сегментации.
 
---------------------------------------------------------------------------------
+32. На **MacOS X** для синхронизации данных с диском _по-умолчанию_
+используется системная функция `fcntl(F_FULLFSYNC)`, так как [только
+этим гарантируется сохранность
+данных](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fsync.2.html)
+при сбое электропитания. К сожалению, в сценариях с высокой
+интенсивностью пишущих транзакций, использование `F_FULLFSYNC` приводит
+к существенной деградации производительности в сравнении с LMDB, где
+используется системная функция `fsync()`. Поэтому _libmdbx_ позволяет
+переопределить это поведение определением опции
+`MDBX_OSX_SPEED_INSTEADOF_DURABILITY=1` при сборке библиотеки.
+
+33. На **Windows** _libmdbx_ использует файловые блокировки
+`LockFileEx()`, так как это позволяет размещать БД на сетевых дисках, а
+также обеспечивает защиту от некомпетентных действий пользователя
+([защиту от
+дурака](https://ru.wikipedia.org/wiki/%D0%97%D0%B0%D1%89%D0%B8%D1%82%D0%B0_%D0%BE%D1%82_%D0%B4%D1%83%D1%80%D0%B0%D0%BA%D0%B0)).
+Поэтому _libmdbx_ может немного отставать в тестах производительность от
+LMDB, где используются именованные мьютексы.
+
 
 ## Недостатки и Компромиссы
 
@@ -386,7 +407,7 @@ Amplification Factor) и RAF (Read Amplification Factor) также Olog(N).
    > Подробности ниже.
 
 
-#### Проблема долгих чтений
+### Проблема долгих чтений
 *Следует отметить*, что проблема "сборки мусора" так или иначе
 существует во всех СУБД (Vacuum в PostgreSQL). Однако в случае _libmdbx_
 и LMDB она проявляется более остро, прежде всего из-за высокой
@@ -452,7 +473,7 @@ Amplification Factor) и RAF (Read Amplification Factor) также Olog(N).
 за счет эффективной работы [BBWC](https://en.wikipedia.org/wiki/BBWC)
 при включении `LIFO RECLAIM` в _libmdbx_.
 
-#### Сохранность данных в режиме асинхронной фиксации
+### Сохранность данных в режиме асинхронной фиксации
 При работе в режиме `WRITEMAP+MAPSYNC` запись измененных страниц
 выполняется ядром ОС, что имеет ряд преимуществ. Так например, при крахе
 приложения, ядро ОС сохранит все изменения.
@@ -515,6 +536,119 @@ Amplification Factor) и RAF (Read Amplification Factor) также Olog(N).
 
 --------------------------------------------------------------------------------
 
+Использование
+=============
+
+## Сборка
+
+Для сборки на всех платформах кроме Windows вам потребуются не-дремучие
+версии: GNU Make, [bash](https://ru.wikipedia.org/wiki/Bash), компиляторы C и C++ совместимые с GCC или CLANG.
+
+Исторически сборка _libmdbx_ основывается на одном
+[Makefile](https://ru.wikipedia.org/wiki/Makefile), что предполагает
+разные рецепты сборки в зависимости от целевой платформы. В следующих
+версиях планируется переход на использование
+[CMake](https://ru.wikipedia.org/wiki/CMake), с отказом от поддержки
+других инструментов.
+
+#### Выгрузка DSO/DLL и деструкторы Thread-Local-Storage объектов
+При сборке _libmdbx_ в виде разделяемой библиотеки, либо использовании
+статической _libmdbx_ в составе другой динамической библиотеке,
+желательно убедиться, что ваша система обеспечивает корректность вызова
+деструкторов Thread-Local-Storage объектов при выгрузке динамических
+библиотек.
+
+Если это не так, то при выгрузке динамической библиотеки с _libmdbx_
+внутри возможна либо утечка ресурсов, либо падения из-за вызова
+деструкторов из уже выгруженного DSO/DLL объекта. Проблема может
+проявляться только в многопоточном приложении, которое производит
+выгрузку разделяемых динамических библиотек с кодом _libmdbx_ внутри,
+после использования _libmdbx_. Заведомо известно, что TLS-деструкторы
+корректно обслуживаются:
+
+- На всех актуальных версиях Windows (Windows 7 и последующих).
+
+- На системах c функцией
+[`__cxa_thread_atexit_impl()`](https://sourceware.org/glibc/wiki/Destructor%20support%20for%20thread_local%20variables)
+в стандартной библиотеке C. В том числе на системах с GNU libc версии
+2.18 и выше.
+
+- На системах с libpthread/ntpl из состава GNU libc с исправлением
+ошибок [#21031](https://sourceware.org/bugzilla/show_bug.cgi?id=21031) и
+[#21032](https://sourceware.org/bugzilla/show_bug.cgi?id=21032), либо
+где нет подобных ошибок в реализации pthreads.
+
+### Linux и другие платформы с GNU Make
+Для сборки библиотеки достаточно выполнить `make all` в директории с
+исходными текстами, а для выполнения базовых тестов `make check`.
+
+Если установленный в система `make` не является GNU Make, то при попытке
+сборки будет масса ошибок от make. В этом случае, возможно, вместо
+`make` вам следует использовать `gmake`, либо даже `gnu-make` и т.п.
+
+### FreeBSD и родственные платформы
+Как правило, на таких системах по-умолчанию используется Berkeley Make.
+А GNU Make вызывается командой `gmake` или может отсутствовать. Кроме
+этого может отсутствовать [`bash`](https://ru.wikipedia.org/wiki/Bash).
+
+Вам необходимо установить требуемые компоненты: GNU Make, bash,
+компиляторы C и C++ совместимые с GCC или CLANG. После этого для сборки
+библиотеки достаточно выполнить `gmake all` (или `make all`) в
+директории с исходными текстами, а для выполнения базовых тестов `gmake
+check` (или `make check`).
+
+### Windows
+Для сборки libmdbx_ для ОС Windows рекомендуется использовать [Microsoft
+Visual Studio](https://ru.wikipedia.org/wiki/Microsoft_Visual_Studio),
+но не такие инструменты как MinGW, MSYS или Cygwin. Для этого в набор
+исходных кодов _libmdbx_ входят соответствующие файлы проектов
+совместимые с Visual Studio 2015, Windows SDK для Windows 8.1 и более
+поздними версиями. Достаточно открыть `mdbx.sln` и выполнить сборку
+библиотеки.
+
+Для сборки с более новыми версиями SDK или Visual Studio должно быть
+достаточно выполнить "Retarget solution". Для сборки под старые версии
+Windows (например Windows XP) или более старыми компиляторами вам
+потребуется самостоятельно преобразовать или воссоздать файлы проектов.
+
+Сборка посредством MinGW, MSYS или Cygwin потенциально возможна. Однако,
+эти сценарии не тестируются и вероятно потребуют от вас доработки
+`Makefile`. Следует отметить, что в _libmdbx_ предприняты усилия для
+устранения runtime зависимостей от CRT и других библиотек Visual Studio.
+Для этого достаточно при сборке определить опцию `MDBX_AVOID_CRT`.
+
+Пример запуска базового сценария тестирования можно найти в
+[CI-сценарии](appveyor.yml) для [AppVeyor](https://www.appveyor.com/).
+Для выполнения [сценария длительного стохастического
+тестирования](test/long_stochastic.sh) потребуется
+[`bash`](https://ru.wikipedia.org/wiki/Bash), а само тестирование
+рекомендуется выполнять с размещением тестовых данных на
+[RAM-диске](https://ru.wikipedia.org/wiki/RAM-%D0%B4%D0%B8%D1%81%D0%BA).
+
+### MacOS X
+Актуальные [нативные сборочные
+инструменты](https://ru.wikipedia.org/wiki/Xcode) для MacOS X включают
+GNU Make, CLANG и устаревшую версию bash. Поэтому для сборки библиотеки
+достаточно выполнить `make all` в директории с исходными текстами, а для
+выполнения базовых тестов `make check`. Если же что-то пойдет не так, то
+рекомендуется установить [Homebrew](https://brew.sh/) и попробовать ещё
+раз.
+
+Для выполнения [сценария длительного стохастического
+тестирования](test/long_stochastic.sh) потребуется установка актуальной
+(не устаревшей) версии [`bash`](https://ru.wikipedia.org/wiki/Bash). Для
+этого рекомендуется установить [Homebrew](https://brew.sh/), а затем
+выполнить `brew install bash`.
+
+## Привязки к другим языкам
+
+  | Runtime  | GitHub | Author |
+  | -------- | ------ | ------ |
+  | Java     | [mdbxjni](https://github.com/castortech/mdbxjni)   | [Castor Technologies](https://castortech.com/) |
+  | .NET     | [mdbx.NET](https://github.com/wangjia184/mdbx.NET) | [Jerry Wang](https://github.com/wangjia184) |
+
+--------------------------------------------------------------------------------
+
 Сравнение производительности
 ============================
 
@@ -526,9 +660,8 @@ SAMSUNG MZNTD512HAGL-000L1 (DXT23L0Q) 512 Гб.
 сценарии тестирования [доступны на
 github](https://github.com/pmwkaa/ioarena/tree/HL%2B%2B2015).
 
---------------------------------------------------------------------------------
 
-### Интегральная производительность
+## Интегральная производительность
 
 Показана соотнесенная сумма ключевых показателей производительности в трёх
 бенчмарках:
@@ -555,7 +688,7 @@ github](https://github.com/pmwkaa/ioarena/tree/HL%2B%2B2015).
 
 --------------------------------------------------------------------------------
 
-### Масштабируемость чтения
+## Масштабируемость чтения
 
 Для каждого движка показана суммарная производительность при
 одновременном выполнении запросов чтения/поиска в 1-2-4-8 потоков на
@@ -565,7 +698,7 @@ github](https://github.com/pmwkaa/ioarena/tree/HL%2B%2B2015).
 
 --------------------------------------------------------------------------------
 
-### Синхронная фиксация
+## Синхронная фиксация
 
  - Линейная шкала слева и темные прямоугольники соответствуют количеству
    транзакций в секунду, усредненному за всё время теста.
@@ -591,7 +724,7 @@ github](https://github.com/pmwkaa/ioarena/tree/HL%2B%2B2015).
 
 --------------------------------------------------------------------------------
 
-### Отложенная фиксация
+## Отложенная фиксация
 
  - Линейная шкала слева и темные прямоугольники соответствуют количеству
    транзакций в секунду, усредненному за всё время теста.
@@ -622,7 +755,7 @@ _libmdbx_ при этом не ведет WAL, а передает весь ко
 
 --------------------------------------------------------------------------------
 
-### Асинхронная фиксация
+## Асинхронная фиксация
 
  - Линейная шкала слева и темные прямоугольники соответствуют количеству
    транзакций в секунду, усредненному за всё время теста.
@@ -652,7 +785,7 @@ _libmdbx_ при этом не ведет WAL, а передает весь ко
 
 --------------------------------------------------------------------------------
 
-### Потребление ресурсов
+## Потребление ресурсов
 
 Показана соотнесенная сумма использованных ресурсов в ходе бенчмарка в
 режиме отложенной фиксации: