diff --git a/README-RU.md b/README-RU.md index f5abc31b..97888cbf 100644 --- a/README-RU.md +++ b/README-RU.md @@ -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 ``` diff --git a/README.md b/README.md index a2a6ab7a..78cc9067 100644 --- a/README.md +++ b/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. - -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 ```