mdbx: add notes about range query estimation into READMEs.

Change-Id: Ia9e0b7e393082115839483ea7a3b37fb37ba0308

README-RU.md

@@ -171,31 +171,18 @@ Amplification Factor) и RAF (Read Amplification Factor) также Olog(N).
 Доработки и усовершенствования относительно LMDB
 ================================================
 
-1. Утилита `mdbx_chk` для проверки целостности структуры БД.
+1. Автоматическое динамическое управление размером БД согласно
-
-2. Автоматическое динамическое управление размером БД согласно
 параметрам задаваемым функцией `mdbx_env_set_geometry()`, включая шаг
 приращения и порог уменьшения размера БД, а также выбор размера
 страницы. Соответственно, это позволяет снизить фрагментированность
 файла БД на диске и освободить место, в том числе в **Windows**.
 
-3. Автоматическая без-затратная компактификация БД путем возврата
+2. Автоматическая без-затратная компактификация БД путем возврата
 освобождающихся страниц в область нераспределенного резерва в конце
 файла данных. При этом уменьшается количество страниц находящихся в
 памяти и участвующих в в обмене с диском.
 
-4. Поддержка ключей и значений нулевой длины, включая сортированные
+3. Режим `LIFO RECLAIM`.
-дубликаты.
-
-5. Возможность связать с каждой завершаемой транзакцией до 3
-дополнительных маркеров посредством `mdbx_canary_put()`, и прочитать их
-в транзакции чтения посредством `mdbx_canary_get()`.
-
-6. Возможность посредством `mdbx_replace()` обновить или удалить запись
-с получением предыдущего значения данных, а также адресно изменить
-конкретное multi-значение.
-
-7. Режим `LIFO RECLAIM`.
 
     Для повторного использования выбираются не самые старые, а
     самые новые страницы из доступных. За счет этого цикл
@@ -209,9 +196,27 @@ Amplification Factor) и RAF (Read Amplification Factor) также Olog(N).
     многократное увеличение производительности по записи
     (обновлению данных).
 
-8. Генерация последовательностей посредством `mdbx_dbi_sequence()`.
+4. Быстрая оценка количества элементов попадающих в запрашиваемый
+диапазон значений ключа посредством функций `mdbx_estimate_range()`,
+`mdbx_estimate_move()` и `mdbx_estimate_distance()` для выбора
+оптимального плана выполнения запроса.
 
-9. Обработчик `OOM-KICK`.
+5. Утилита `mdbx_chk` для проверки целостности структуры БД.
+
+6. Поддержка ключей и значений нулевой длины, включая сортированные
+дубликаты.
+
+7. Возможность связать с каждой завершаемой транзакцией до 3
+дополнительных маркеров посредством `mdbx_canary_put()`, и прочитать их
+в транзакции чтения посредством `mdbx_canary_get()`.
+
+8. Возможность посредством `mdbx_replace()` обновить или удалить запись
+с получением предыдущего значения данных, а также адресно изменить
+конкретное multi-значение.
+
+9. Генерация последовательностей посредством `mdbx_dbi_sequence()`.
+
+10. Обработчик `OOM-KICK`.
 
     Посредством `mdbx_env_set_oomfunc()` может быть установлен
     внешний обработчик (callback), который будет вызван при
@@ -232,83 +237,83 @@ Amplification Factor) и RAF (Read Amplification Factor) также Olog(N).
     * прервать текущую операцию изменения данных с возвратом кода
       ошибки.
 
-10. Возможность открыть БД в эксклюзивном режиме посредством флага
+11. Возможность открыть БД в эксклюзивном режиме посредством флага
-`MDBX_EXCLUSIVE`.
+    `MDBX_EXCLUSIVE`, в том числе на сетевом носителе.
 
-11. Возможность получить отставание текущей транзакции чтения от
+12. Возможность получить отставание текущей транзакции чтения от
 последней версии данных в БД посредством `mdbx_txn_straggler()`.
 
-12. Возможность явно запросить обновление существующей записи, без
+13. Возможность явно запросить обновление существующей записи, без
 создания новой посредством флажка `MDBX_CURRENT` для `mdbx_put()`.
 
-13. Исправленный вариант `mdbx_cursor_count()`, возвращающий корректное
+14. Исправленный вариант `mdbx_cursor_count()`, возвращающий корректное
 количество дубликатов для всех типов таблиц и любого положения курсора.
 
-14. Возможность получить посредством `mdbx_env_info()` дополнительную
+15. Возможность получить посредством `mdbx_env_info()` дополнительную
 информацию, включая номер самой старой версии БД (снимка данных),
 который используется одним из читателей.
 
-15. Функция `mdbx_del()` не игнорирует дополнительный (уточняющий)
+16. Функция `mdbx_del()` не игнорирует дополнительный (уточняющий)
 аргумент `data` для таблиц без дубликатов (без флажка `MDBX_DUPSORT`), а
 при его ненулевом значении всегда использует его для сверки с удаляемой
 записью.
 
-16. Возможность открыть dbi-таблицу, одновременно с установкой
+17. Возможность открыть dbi-таблицу, одновременно с установкой
 компараторов для ключей и данных, посредством `mdbx_dbi_open_ex()`.
 
-17. Возможность посредством `mdbx_is_dirty()` определить находятся ли
+18. Возможность посредством `mdbx_is_dirty()` определить находятся ли
 некоторый ключ или данные в "грязной" странице БД. Таким образом,
 избегая лишнего копирования данных перед выполнением модифицирующих
 операций (значения, размещенные в "грязных" страницах, могут быть
 перезаписаны при изменениях, иначе они будут неизменны).
 
-18. Корректное обновление текущей записи, в том числе сортированного
+19. Корректное обновление текущей записи, в том числе сортированного
 дубликата, при использовании режима `MDBX_CURRENT` в
 `mdbx_cursor_put()`.
 
-19. Возможность узнать есть ли за текущей позицией курсора строка данных
+20. Возможность узнать есть ли за текущей позицией курсора строка данных
 посредством `mdbx_cursor_eof()`.
 
-20. Дополнительный код ошибки `MDBX_EMULTIVAL`, который возвращается из
+21. Дополнительный код ошибки `MDBX_EMULTIVAL`, который возвращается из
 `mdbx_put()` и `mdbx_replace()` при попытке выполнить неоднозначное
 обновление или удаления одного из нескольких значений с одним ключом.
 
-21. Возможность посредством `mdbx_get_ex()` получить значение по
+22. Возможность посредством `mdbx_get_ex()` получить значение по
 заданному ключу, одновременно с количеством дубликатов.
 
-22. Наличие функций `mdbx_cursor_on_first()` и `mdbx_cursor_on_last()`,
+23. Наличие функций `mdbx_cursor_on_first()` и `mdbx_cursor_on_last()`,
 которые позволяют быстро выяснить стоит ли курсор на первой/последней
 позиции.
 
-23. Возможность автоматического формирования контрольных точек (сброса
+24. Возможность автоматического формирования контрольных точек (сброса
 данных на диск) при накоплении заданного объёма изменений,
 устанавливаемого функцией `mdbx_env_set_syncbytes()`.
 
-24. Управление отладкой и получение отладочных сообщений посредством
+25. Управление отладкой и получение отладочных сообщений посредством
 `mdbx_setup_debug()`.
 
-25. Функция `mdbx_env_pgwalk()` для обхода всех страниц БД.
+26. Функция `mdbx_env_pgwalk()` для обхода всех страниц БД.
 
-26. Три мета-страницы вместо двух, что позволяет гарантированно
+27. Три мета-страницы вместо двух, что позволяет гарантированно
 консистентно обновлять слабые контрольные точки фиксации без риска
 повредить крайнюю сильную точку фиксации.
 
-27. Гарантия сохранности БД в режиме `WRITEMAP+MAPSYNC`.
+28. Гарантия сохранности БД в режиме `WRITEMAP+MAPSYNC`.
   > В текущей версии _libmdbx_ вам предоставляется выбор между безопасным
   > режимом (по умолчанию) асинхронной фиксации, и режимом `UTTERLY_NOSYNC`
   > когда при системной аварии есть шанс полного разрушения БД как в LMDB.
   > Для подробностей смотрите раздел
   > [Сохранность данных в режиме асинхронной фиксации](#Сохранность-данных-в-режиме-асинхронной-фиксации).
 
-28. Возможность закрыть БД в "грязном" состоянии (без сброса данных и
+29. Возможность закрыть БД в "грязном" состоянии (без сброса данных и
 формирования сильной точки фиксации) посредством `mdbx_env_close_ex()`.
 
-29. При завершении читающих транзакций, открытые в них DBI-хендлы не
+30. При завершении читающих транзакций, открытые в них DBI-хендлы не
 закрываются и не теряются при завершении таких транзакций посредством
 `mdbx_txn_abort()` или `mdbx_txn_reset()`. Что позволяет избавится от ряда
 сложно обнаруживаемых ошибок.
 
-30. Все курсоры, как в транзакциях только для чтения, так и в пишущих,
+31. Все курсоры, как в транзакциях только для чтения, так и в пишущих,
 могут быть переиспользованы посредством `mdbx_cursor_renew()` и ДОЛЖНЫ
 ОСВОБОЖДАТЬСЯ ЯВНО.
   >
@@ -682,11 +687,11 @@ $ objdump -f -h -j .text libmdbx.so
 libmdbx.so:     file format elf64-x86-64
 architecture: i386:x86-64, flags 0x00000150:
 HAS_SYMS, DYNAMIC, D_PAGED
-start address 0x000030e0
+start address 0x0000000000003870
 
 Sections:
 Idx Name          Size      VMA               LMA               File off  Algn
- 11 .text         00014d84  00000000000030e0  00000000000030e0  000030e0  2**4
+ 11 .text         000173d4  0000000000003870  0000000000003870  00003870  2**4
                   CONTENTS, ALLOC, LOAD, READONLY, CODE
 
 ```

README.md

@@ -170,30 +170,18 @@ regular maintenance. Backups can be made on the fly on working DB
 Improvements over LMDB
 ======================
 
-1. `mdbx_chk` tool for DB integrity check.
+1. Automatic dynamic DB size management according to the parameters
-
+specified by `mdbx_env_set_geometry()` function. Including
-2. Automatic dynamic DB size management according to the parameters
-specified by `mdbx_env_set_geometry()` function. Including including
 growth step and truncation threshold, as well as the choice of page
 size.
 
-3. Automatic returning of freed pages into unallocated space at the end
+2. Automatic returning of freed pages into unallocated space at the end
-of database file with optionally automatic shrinking it. This reduces
+of database file, with optionally automatic shrinking it. This reduces
 amount of pages resides in RAM and circulated in disk I/O. In fact
 _libmdbx_ constantly performs DB compactification, without spending
 additional resources for that.
 
-4. Support for keys and values of zero length, including sorted
+3. `LIFO RECLAIM` mode:
-duplicates.
-
-5. Ability to assign up to 3 markers to commiting transaction with
-`mdbx_canary_put()` and then get them in read transaction by
-`mdbx_canary_get()`.
-
-6. Ability to update or delete record and get previous value via
-`mdbx_replace()` Also can update specific multi-value.
-
-7. `LIFO RECLAIM` mode:
 
     The newest pages are picked for reuse instead of the oldest. This allows
     to minimize reclaim loop and make it execution time independent of total
@@ -204,9 +192,25 @@ duplicates.
     [BBWC](https://en.wikipedia.org/wiki/Disk_buffer#Write_acceleration)
     this may greatly improve write performance.
 
-8. Sequence generation via `mdbx_dbi_sequence()`.
+4. Fast estimation of range query result size via functions `mdbx_estimate_range()`,
+`mdbx_estimate_move()` and `mdbx_estimate_distance()`. E.g. for selection the
+optimal query execution plan.
 
-9. `OOM-KICK` callback.
+5. `mdbx_chk` tool for DB integrity check.
+
+6. Support for keys and values of zero length, including sorted
+duplicates.
+
+7. Ability to assign up to 3 markers to commiting transaction with
+`mdbx_canary_put()` and then get them in read transaction by
+`mdbx_canary_get()`.
+
+8. Ability to update or delete record and get previous value via
+`mdbx_replace()`. Also can update specific multi-value.
+
+9. Sequence generation via `mdbx_dbi_sequence()`.
+
+10. `OOM-KICK` callback.
 
     `mdbx_env_set_oomfunc()` allows to set a callback, which will be called
     in the event of DB space exhausting during long-time read transaction in
@@ -224,75 +228,75 @@ duplicates.
 
     * abort current write transaction with returning error code.
 
-10. Ability to open DB in exclusive mode with `MDBX_EXCLUSIVE` flag.
+11. Ability to open DB in exclusive mode with `MDBX_EXCLUSIVE` flag.
 
-11. Ability to get how far current read-only snapshot is from latest
+12. Ability to get how far current read-only snapshot is from latest
 version of the DB by `mdbx_txn_straggler()`.
 
-12. Ability to explicitly request update of present record without
+13. Ability to explicitly request update of present record without
 creating new record. Implemented as `MDBX_CURRENT` flag for
 `mdbx_put()`.
 
-13. Fixed `mdbx_cursor_count()`, which returns correct count of
+14. Fixed `mdbx_cursor_count()`, which returns correct count of
 duplicated for all table types and any cursor position.
 
-14. `mdbx_env_info()` to getting additional info, including number of
+15. `mdbx_env_info()` to getting additional info, including number of
 the oldest snapshot of DB, which is used by one of the readers.
 
-15. `mdbx_del()` doesn't ignore additional argument (specifier) `data`
+16. `mdbx_del()` doesn't ignore additional argument (specifier) `data`
 for tables without duplicates (without flag `MDBX_DUPSORT`), if `data`
 is not null then always uses it to verify record, which is being
 deleted.
 
-16. Ability to open dbi-table with simultaneous setup of comparators for
+17. Ability to open dbi-table with simultaneous setup of comparators for
 keys and values, via `mdbx_dbi_open_ex()`.
 
-17. `mdbx_is_dirty()`to find out if key or value is on dirty page, that
+18. `mdbx_is_dirty()`to find out if key or value is on dirty page, that
 useful to avoid copy-out before updates.
 
-18. Correct update of current record in `MDBX_CURRENT` mode of
+19. Correct update of current record in `MDBX_CURRENT` mode of
 `mdbx_cursor_put()`, including sorted duplicated.
 
-19. Check if there is a row with data after current cursor position via
+20. Check if there is a row with data after current cursor position via
 `mdbx_cursor_eof()`.
 
-20. Additional error code `MDBX_EMULTIVAL`, which is returned by
+21. Additional error code `MDBX_EMULTIVAL`, which is returned by
 `mdbx_put()` and `mdbx_replace()` in case is ambiguous update or delete.
 
-21. Ability to get value by key and duplicates count by `mdbx_get_ex()`.
+22. Ability to get value by key and duplicates count by `mdbx_get_ex()`.
 
-22. Functions `mdbx_cursor_on_first()` and `mdbx_cursor_on_last()`,
+23. Functions `mdbx_cursor_on_first()` and `mdbx_cursor_on_last()`,
 which allows to know if cursor is currently on first or last position
 respectively.
 
-23. Automatic creation of synchronization points (flush changes to
+24. Automatic creation of synchronization points (flush changes to
 persistent storage) when changes reach set threshold (threshold can be
 set by `mdbx_env_set_syncbytes()`).
 
-24. Control over debugging and receiving of debugging messages via
+25. Control over debugging and receiving of debugging messages via
 `mdbx_setup_debug()`.
 
-25. Function `mdbx_env_pgwalk()` for page-walking all pages in DB.
+26. Function `mdbx_env_pgwalk()` for page-walking all pages in DB.
 
-26. Three meta-pages instead of two, this allows to guarantee
+27. Three meta-pages instead of two, this allows to guarantee
 consistently update weak sync-points without risking to corrupt last
 steady sync-point.
 
-27. Guarantee of DB integrity in `WRITEMAP+MAPSYNC` mode:
+28. Guarantee of DB integrity in `WRITEMAP+MAPSYNC` mode:
   > Current _libmdbx_ gives a choice of safe async-write mode (default)
   > and `UTTERLY_NOSYNC` mode which may result in full
   > DB corruption during system crash as with LMDB. For details see
   > [Data safety in async-write mode](#data-safety-in-async-write-mode).
 
-28. Ability to close DB in "dirty" state (without data flush and
+29. Ability to close DB in "dirty" state (without data flush and
 creation of steady synchronization point) via `mdbx_env_close_ex()`.
 
-29. If read transaction is aborted via `mdbx_txn_abort()` or
+30. If read transaction is aborted via `mdbx_txn_abort()` or
 `mdbx_txn_reset()` then DBI-handles, which were opened in it, aren't
 closed or deleted. This allows to avoid several types of hard-to-debug
 errors.
 
-30. All cursors in all read and write transactions can be reused by
+31. All cursors in all read and write transactions can be reused by
 `mdbx_cursor_renew()` and MUST be freed explicitly.
   > ## Caution, please pay attention!
   >
@@ -594,11 +598,11 @@ $ objdump -f -h -j .text libmdbx.so
 libmdbx.so:     file format elf64-x86-64
 architecture: i386:x86-64, flags 0x00000150:
 HAS_SYMS, DYNAMIC, D_PAGED
-start address 0x000030e0
+start address 0x0000000000003870
 
 Sections:
 Idx Name          Size      VMA               LMA               File off  Algn
- 11 .text         00014d84  00000000000030e0  00000000000030e0  000030e0  2**4
+ 11 .text         000173d4  0000000000003870  0000000000003870  00003870  2**4
                   CONTENTS, ALLOC, LOAD, READONLY, CODE
 
 ```