ISAR/libmdbx
3
0
Fork 0
mirror of https://github.com/isar/libmdbx.git synced 2025-01-30 22:47:16 +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
================================================
1. Утилита `mdbx_chk` для проверки целостности структуры БД.
2. Автоматическое динамическое управление размером БД согласно
1. Автоматическое динамическое управление размером БД согласно
параметрам задаваемым функцией `mdbx_env_set_geometry()`, включая шаг
приращения и порог уменьшения размера БД, а также выбор размера
страницы. Соответственно, это позволяет снизить фрагментированность
файла БД на диске и освободить место, в том числе в **Windows**.
3. Автоматическая без-затратная компактификация БД путем возврата
2. Автоматическая без-затратная компактификация БД путем возврата
освобождающихся страниц в область нераспределенного резерва в конце
файла данных. При этом уменьшается количество страниц находящихся в
памяти и участвующих в в обмене с диском.
4. Поддержка ключей и значений нулевой длины, включая сортированные
дубликаты.
5. Возможность связать с каждой завершаемой транзакцией до 3
дополнительных маркеров посредством `mdbx_canary_put()`, и прочитать их
в транзакции чтения посредством `mdbx_canary_get()`.
6. Возможность посредством `mdbx_replace()` обновить или удалить запись
с получением предыдущего значения данных, а также адресно изменить
конкретное multi-значение.
7. Режим `LIFO RECLAIM`.
3. Режим `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. Возможность открыть БД в эксклюзивном режиме посредством флага
`MDBX_EXCLUSIVE`.
11. Возможность открыть БД в эксклюзивном режиме посредством флага
`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
```

88
README.md
View File

@ -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.
2. Automatic dynamic DB size management according to the parameters
specified by `mdbx_env_set_geometry()` function. Including including
1. Automatic dynamic DB size management according to the parameters
specified by `mdbx_env_set_geometry()` function. 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
of database file with optionally automatic shrinking it. This reduces
2. Automatic returning of freed pages into unallocated space at the end
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
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:
3. `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
```