ISAR/libmdbx
3
0
Fork 0
mirror of https://github.com/isar/libmdbx.git synced 2025-02-07 12:39:36 +08:00
Code Issues Packages Projects Releases Wiki Activity

mdbx: add notes about range query estimation into READMEs.

Browse Source 
Change-Id: Ia9e0b7e393082115839483ea7a3b37fb37ba0308
This commit is contained in:
Leonid Yuriev 2019-03-06 00:40:53 +03:00
parent ee899a21ed
commit 7f8cd66e11
2 changed files with 93 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
README-RU.md
View File

@ -171,31 +171,18 @@ Amplification Factor) и RAF (Read Amplification Factor) также Olog(N).
Доработки и усовершенствования относительно LMDB Доработки и усовершенствования относительно LMDB
================================================ ================================================
1. Утилита `mdbx_chk` для проверки целостности структуры БД. 1. Автоматическое динамическое управление размером БД согласно
2. Автоматическое динамическое управление размером БД согласно
параметрам задаваемым функцией `mdbx_env_set_geometry()`, включая шаг параметрам задаваемым функцией `mdbx_env_set_geometry()`, включая шаг
приращения и порог уменьшения размера БД, а также выбор размера приращения и порог уменьшения размера БД, а также выбор размера
страницы. Соответственно, это позволяет снизить фрагментированность страницы. Соответственно, это позволяет снизить фрагментированность
файла БД на диске и освободить место, в том числе в **Windows**. файла БД на диске и освободить место, в том числе в **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()` может быть установлен Посредством `mdbx_env_set_oomfunc()` может быть установлен
внешний обработчик (callback), который будет вызван при внешний обработчик (callback), который будет вызван при
@ -232,83 +237,83 @@ Amplification Factor) и RAF (Read Amplification Factor) также Olog(N).
* прервать текущую операцию изменения данных с возвратом кода * прервать текущую операцию изменения данных с возвратом кода
ошибки. ошибки.
10. Возможность открыть БД в эксклюзивном режиме посредством флага 11. Возможность открыть БД в эксклюзивном режиме посредством флага
`MDBX_EXCLUSIVE`. `MDBX_EXCLUSIVE`, в том числе на сетевом носителе.
11. Возможность получить отставание текущей транзакции чтения от 12. Возможность получить отставание текущей транзакции чтения от
последней версии данных в БД посредством `mdbx_txn_straggler()`. последней версии данных в БД посредством `mdbx_txn_straggler()`.
12. Возможность явно запросить обновление существующей записи, без 13. Возможность явно запросить обновление существующей записи, без
создания новой посредством флажка `MDBX_CURRENT` для `mdbx_put()`. создания новой посредством флажка `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`), а аргумент `data` для таблиц без дубликатов (без флажка `MDBX_DUPSORT`), а
при его ненулевом значении всегда использует его для сверки с удаляемой при его ненулевом значении всегда использует его для сверки с удаляемой
записью. записью.
16. Возможность открыть dbi-таблицу, одновременно с установкой 17. Возможность открыть dbi-таблицу, одновременно с установкой
компараторов для ключей и данных, посредством `mdbx_dbi_open_ex()`. компараторов для ключей и данных, посредством `mdbx_dbi_open_ex()`.
17. Возможность посредством `mdbx_is_dirty()` определить находятся ли 18. Возможность посредством `mdbx_is_dirty()` определить находятся ли
некоторый ключ или данные в "грязной" странице БД. Таким образом, некоторый ключ или данные в "грязной" странице БД. Таким образом,
избегая лишнего копирования данных перед выполнением модифицирующих избегая лишнего копирования данных перед выполнением модифицирующих
операций (значения, размещенные в "грязных" страницах, могут быть операций (значения, размещенные в "грязных" страницах, могут быть
перезаписаны при изменениях, иначе они будут неизменны). перезаписаны при изменениях, иначе они будут неизменны).
18. Корректное обновление текущей записи, в том числе сортированного 19. Корректное обновление текущей записи, в том числе сортированного
дубликата, при использовании режима `MDBX_CURRENT` в дубликата, при использовании режима `MDBX_CURRENT` в
`mdbx_cursor_put()`. `mdbx_cursor_put()`.
19. Возможность узнать есть ли за текущей позицией курсора строка данных 20. Возможность узнать есть ли за текущей позицией курсора строка данных
посредством `mdbx_cursor_eof()`. посредством `mdbx_cursor_eof()`.
20. Дополнительный код ошибки `MDBX_EMULTIVAL`, который возвращается из 21. Дополнительный код ошибки `MDBX_EMULTIVAL`, который возвращается из
`mdbx_put()` и `mdbx_replace()` при попытке выполнить неоднозначное `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()`. устанавливаемого функцией `mdbx_env_set_syncbytes()`.
24. Управление отладкой и получение отладочных сообщений посредством 25. Управление отладкой и получение отладочных сообщений посредством
`mdbx_setup_debug()`. `mdbx_setup_debug()`.
25. Функция `mdbx_env_pgwalk()` для обхода всех страниц БД. 26. Функция `mdbx_env_pgwalk()` для обхода всех страниц БД.
26. Три мета-страницы вместо двух, что позволяет гарантированно 27. Три мета-страницы вместо двух, что позволяет гарантированно
консистентно обновлять слабые контрольные точки фиксации без риска консистентно обновлять слабые контрольные точки фиксации без риска
повредить крайнюю сильную точку фиксации. повредить крайнюю сильную точку фиксации.
27. Гарантия сохранности БД в режиме `WRITEMAP+MAPSYNC`. 28. Гарантия сохранности БД в режиме `WRITEMAP+MAPSYNC`.
> В текущей версии _libmdbx_ вам предоставляется выбор между безопасным > В текущей версии _libmdbx_ вам предоставляется выбор между безопасным
> режимом (по умолчанию) асинхронной фиксации, и режимом `UTTERLY_NOSYNC` > режимом (по умолчанию) асинхронной фиксации, и режимом `UTTERLY_NOSYNC`
> когда при системной аварии есть шанс полного разрушения БД как в LMDB. > когда при системной аварии есть шанс полного разрушения БД как в LMDB.
> Для подробностей смотрите раздел > Для подробностей смотрите раздел
> [Сохранность данных в режиме асинхронной фиксации](#Сохранность-данных-в-режиме-асинхронной-фиксации). > [Сохранность данных в режиме асинхронной фиксации](#Сохранность-данных-в-режиме-асинхронной-фиксации).
28. Возможность закрыть БД в "грязном" состоянии (без сброса данных и 29. Возможность закрыть БД в "грязном" состоянии (без сброса данных и
формирования сильной точки фиксации) посредством `mdbx_env_close_ex()`. формирования сильной точки фиксации) посредством `mdbx_env_close_ex()`.
29. При завершении читающих транзакций, открытые в них DBI-хендлы не 30. При завершении читающих транзакций, открытые в них DBI-хендлы не
закрываются и не теряются при завершении таких транзакций посредством закрываются и не теряются при завершении таких транзакций посредством
`mdbx_txn_abort()` или `mdbx_txn_reset()`. Что позволяет избавится от ряда `mdbx_txn_abort()` или `mdbx_txn_reset()`. Что позволяет избавится от ряда
сложно обнаруживаемых ошибок. сложно обнаруживаемых ошибок.
30. Все курсоры, как в транзакциях только для чтения, так и в пишущих, 31. Все курсоры, как в транзакциях только для чтения, так и в пишущих,
могут быть переиспользованы посредством `mdbx_cursor_renew()` и ДОЛЖНЫ могут быть переиспользованы посредством `mdbx_cursor_renew()` и ДОЛЖНЫ
ОСВОБОЖДАТЬСЯ ЯВНО. ОСВОБОЖДАТЬСЯ ЯВНО.
> >
@ -682,11 +687,11 @@ $ objdump -f -h -j .text libmdbx.so
libmdbx.so: file format elf64-x86-64 libmdbx.so: file format elf64-x86-64
architecture: i386:x86-64, flags 0x00000150: architecture: i386:x86-64, flags 0x00000150:
HAS_SYMS, DYNAMIC, D_PAGED HAS_SYMS, DYNAMIC, D_PAGED
start address 0x000030e0 start address 0x0000000000003870
Sections: Sections:
Idx Name Size VMA LMA File off Algn 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 CONTENTS, ALLOC, LOAD, READONLY, CODE
``` ```

88
README.md
View File

@ -170,30 +170,18 @@ regular maintenance. Backups can be made on the fly on working DB
Improvements over LMDB 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 growth step and truncation threshold, as well as the choice of page
size. 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 amount of pages resides in RAM and circulated in disk I/O. In fact
_libmdbx_ constantly performs DB compactification, without spending _libmdbx_ constantly performs DB compactification, without spending
additional resources for that. 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 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 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) [BBWC](https://en.wikipedia.org/wiki/Disk_buffer#Write_acceleration)
this may greatly improve write performance. 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 `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 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. * 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()`. 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 creating new record. Implemented as `MDBX_CURRENT` flag for
`mdbx_put()`. `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. 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. 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` for tables without duplicates (without flag `MDBX_DUPSORT`), if `data`
is not null then always uses it to verify record, which is being is not null then always uses it to verify record, which is being
deleted. 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()`. 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. 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. `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()`. `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. `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 which allows to know if cursor is currently on first or last position
respectively. 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 persistent storage) when changes reach set threshold (threshold can be
set by `mdbx_env_set_syncbytes()`). 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()`. `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 consistently update weak sync-points without risking to corrupt last
steady sync-point. 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) > Current _libmdbx_ gives a choice of safe async-write mode (default)
> and `UTTERLY_NOSYNC` mode which may result in full > and `UTTERLY_NOSYNC` mode which may result in full
> DB corruption during system crash as with LMDB. For details see > DB corruption during system crash as with LMDB. For details see
> [Data safety in async-write mode](#data-safety-in-async-write-mode). > [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()`. 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 `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 closed or deleted. This allows to avoid several types of hard-to-debug
errors. 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. `mdbx_cursor_renew()` and MUST be freed explicitly.
> ## Caution, please pay attention! > ## Caution, please pay attention!
> >
@ -594,11 +598,11 @@ $ objdump -f -h -j .text libmdbx.so
libmdbx.so: file format elf64-x86-64 libmdbx.so: file format elf64-x86-64
architecture: i386:x86-64, flags 0x00000150: architecture: i386:x86-64, flags 0x00000150:
HAS_SYMS, DYNAMIC, D_PAGED HAS_SYMS, DYNAMIC, D_PAGED
start address 0x000030e0 start address 0x0000000000003870
Sections: Sections:
Idx Name Size VMA LMA File off Algn 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 CONTENTS, ALLOC, LOAD, READONLY, CODE
``` ```