From eb4eda636803954e79d63b6bc46095ccfb5dd5ee Mon Sep 17 00:00:00 2001 From: Leo Yuriev Date: Wed, 8 Feb 2017 17:52:05 +0300 Subject: [PATCH] mdbx: append README. --- README.md | 133 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 84 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index d11e1ad7..2cbe08cb 100644 --- a/README.md +++ b/README.md @@ -3,38 +3,36 @@ libmdbx Extended LMDB, aka "Расширенная LMDB". *The Future will Positive. Всё будет хорошо.* - [![Build Status](https://travis-ci.org/ReOpen/libmdbx.svg?branch=devel)](https://travis-ci.org/ReOpen/libmdbx) - -English version by Google [is here](https://translate.googleusercontent.com/translate_c?act=url&depth=1&hl=ru&ie=UTF8&prev=_t&rurl=translate.google.com&sl=ru&tl=en&u=https://github.com/ReOpen/libmdbx/tree/devel). +English version by Google [is here](https://translate.googleusercontent.com/translate_c?act=url&ie=UTF8&sl=ru&tl=en&u=https://github.com/ReOpen/libmdbx/tree/devel). ## Кратко -_libmdbx_ - это встраиваемый key-value движок хранения со -специфическим набором возможностей, которые при правильном -применении позволяют создавать уникальные решения с чемпионской -производительностью, идеально сочетаясь с технологией -[MRAM](https://en.wikipedia.org/wiki/Magnetoresistive_random-access_memory). -_libmdbx_ обновляет совместно используемый набор данных, никак -не мешая при этом параллельным операциям чтения, не применяя -атомарных операций к самим данным, и обеспечивая -согласованность при аварийной остановке в любой момент. Поэтому -_libmdbx_ позволяя строить системы с линейным масштабированием -производительности чтения/поиска по ядрам CPU и амортизационной -стоимостью любых операций Olog(N). +_libmdbx_ - это встраиваемый key-value движок хранения со специфическим +набором возможностей, которые при правильном применении позволяют +создавать уникальные решения с чемпионской производительностью, идеально +сочетаясь с технологией [MRAM](https://en.wikipedia.org/wiki/Magnetoresistive_random-access_memory). + +_libmdbx_ обновляет совместно используемый набор данных, никак не мешая +при этом параллельным операциям чтения, не применяя атомарных операций к +самим данным, и обеспечивая согласованность при аварийной остановке в +любой момент. Поэтому _libmdbx_ позволяя строить системы с линейным +масштабированием производительности чтения/поиска по ядрам CPU и +амортизационной стоимостью любых операций Olog(N). ### История + _libmdbx_ является потомком "Lightning Memory-Mapped Database", известной под аббревиатурой [LMDB](https://en.wikipedia.org/wiki/Lightning_Memory-Mapped_Database). Изначально доработка производилась в составе проекта -[ReOpenLDAP](https://github.com/ReOpen/ReOpenLDAP). Примерно за -год работы внесенные изменения приобрели самостоятельную -ценность. Осенью 2015 доработанный движок был выделен в -отдельный проект, который был [представлен на конференции -Highload++ 2015](http://www.highload.ru/2015/abstracts/1831.html). +[ReOpenLDAP](https://github.com/ReOpen/ReOpenLDAP). Примерно за год +работы внесенные изменения приобрели самостоятельную ценность. Осенью +2015 доработанный движок был выделен в отдельный проект, который был +[представлен на конференции Highload++ +2015](http://www.highload.ru/2015/abstracts/1831.html). Характеристики и ключевые особенности @@ -284,48 +282,85 @@ RECLAIM` в _libmdbx_. формированием сильных точек фиксации. 4. Возможность автоматического формирования контрольных точек -(сброса данных на диск) при накоплении заданного объёма -изменений, устанавливаемого функцией -`mdbx_env_set_syncbytes()`. +(сброса данных на диск) при накоплении заданного объёма изменений, +устанавливаемого функцией `mdbx_env_set_syncbytes()`. 5. Возможность получить отставание текущей транзакции чтения от -последней версии данных в БД посредством -`mdbx_txn_straggler()`. +последней версии данных в БД посредством `mdbx_txn_straggler()`. -6. Утилита mdbx_chk для проверки БД и функция -`mdbx_env_pgwalk()` для обхода всех страниц БД. +6. Утилита mdbx_chk для проверки БД и функция `mdbx_env_pgwalk()` для +обхода всех страниц БД. -7. Управление отладкой и получение отладочных сообщений -посредством `mdbx_setup_debug()`. +7. Управление отладкой и получение отладочных сообщений посредством +`mdbx_setup_debug()`. 8. Возможность связать с каждой завершаемой транзакцией до 3 -дополнительных маркеров посредством `mdbx_canary_put()`, и -прочитать их в транзакции чтения посредством -`mdbx_canary_get()`. +дополнительных маркеров посредством `mdbx_canary_put()`, и прочитать их +в транзакции чтения посредством `mdbx_canary_get()`. -9. Возможность узнать есть ли за текущей позицией курсора -строка данных посредством `mdbx_cursor_eof()`. +9. Возможность узнать есть ли за текущей позицией курсора строка данных +посредством `mdbx_cursor_eof()`. -10. Возможность явно запросить обновление существующей записи, -без создания новой посредством флажка `MDB_CURRENT` для -`mdb_put()`. +10. Возможность явно запросить обновление существующей записи, без +создания новой посредством флажка `MDB_CURRENT` для `mdbx_put()`. -11. Возможность обновить или удалить запись с получением -предыдущего значения данных посредством `mdbx_replace()`. +11. Возможность обновить или удалить запись с получением предыдущего +значения данных посредством `mdbx_replace()`. -12. Поддержка ключей нулевого размера. +12. Поддержка ключей и значений нулевой длины. Включая сортированные +дубликаты, в том числе вне зависимости от порядка их добавления или +обновления. -13. Исправленный вариант `mdb_cursor_count()`, возвращающий -корректное количество дубликатов для всех типов таблиц и любого -положения курсора. +13. Исправленный вариант `mdbx_cursor_count()`, возвращающий корректное +количество дубликатов для всех типов таблиц и любого положения курсора. 14. Возможность открыть БД в эксклюзивном режиме посредством `mdbx_env_open_ex()`, например в целях её проверки. -15. Возможность закрыть БД в "грязном" состоянии (без сброса -данных и формирования сильной точки фиксации) посредством -`mdbx_env_close_ex()`. +15. Возможность закрыть БД в "грязном" состоянии (без сброса данных и +формирования сильной точки фиксации) посредством `mdbx_env_close_ex()`. -16. Возможность получить посредством `mdbx_env_info()` -дополнительную информацию, включая номер самой старой версии БД -(снимка данных), который используется одним из читателей. +16. Возможность получить посредством `mdbx_env_info()` дополнительную +информацию, включая номер самой старой версии БД (снимка данных), +который используется одним из читателей. + +17. Функция `mdbx_del()` не игнорирует дополнительный (уточняющий) +аргумент `data` для таблиц без дубликатов (без флажка `MDB_DUPSORT`), а +при его ненулевом значении всегда использует его для сверки с удаляемой +записью. + +18. Возможность открыть dbi-таблицу, одновременно с установкой +компараторов для ключей и данных, посредством `mdbx_dbi_open_ex()`. + +19. Возможность посредством `mdbx_is_dirty()` определить находятся ли +некоторый ключ или данные в "грязной" странице БД. Таким образом избегаю +лишнего копирования данных перед выполнением модифицирующих операций +(значения в размещенные "грязных" страницах могут быть перезаписаны при +изменениях, иначе они будут неизменны). + +20. Корректное обновление текущей записи, в том числе сортированного +дубликата, при использовании режима `MDB_CURRENT` в `mdbx_cursor_put()`. + +21. Все курсоры, как в транзакциях только для чтения, так и в пишущих, +могут быть переиспользованы посредством `mdbx_cursor_renew()` и ДОЛЖНЫ +ОСВОБОЖДАТЬСЯ ЯВНО. + > + > ## _ВАЖНО_, Обратите внимание! + > + > Это единственное изменение в API, которое значимо меняет + > семантику управления курсорами и может приводить к утечкам + > памяти. Следует отметить, что это изменение вынужденно. + > Так устраняется неоднозначность с массой тяжких последствий: + > + > - обращение к уже освобожденной памяти; + > - попытки повторного освобождения памяти; + > - memory corruption and segfaults. + +22. Дополнительный код ошибки `MDBX_EMULTIVAL`, который возвращается из +`mdbx_put()` и `mdbx_replace()` при попытке выполнять неоднозначное +обновление или удаления одного из нескольких значений с одним ключом, +т.е. когда невозможно однозначно идентифицировать одно целевое значение +из нескольких. + +23. Возможность посредством `mdbx_get_ex()` получить значение по +заданному ключу, одновременно с количеством дубликатов.