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

mdbx-docs: undo > changes as a compromise for Doxygen and Markdown rendering on GitFlic.

Browse Source
This commit is contained in:
Леонид Юрьев (Leonid Yuriev) 2022-05-03 12:19:08 +03:00
parent 6e4094c714
commit 1ab76184ed
1 changed files with 36 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
README.md
View File

@ -220,52 +220,45 @@ the user's point of view.
## Added Features ## Added Features
1. Keys could be more than 2 times longer than _LMDB_. 1. Keys could be more than 2 times longer than _LMDB_.
> For DB with default page size _libmdbx_ support keys up to 2022 bytes
> For DB with default page size _libmdbx_ support keys up to 2022 bytes > and up to 32742 bytes for 64K page size. _LMDB_ allows key size up to
> and up to 32742 bytes for 64K page size. _LMDB_ allows key size up to > 511 bytes and may silently loses data with large values.
> 511 bytes and may silently loses data with large values.
2. Up to 30% faster than _LMDB_ in [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) benchmarks. 2. Up to 30% faster than _LMDB_ in [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) benchmarks.
> Benchmarks of the in-[tmpfs](https://en.wikipedia.org/wiki/Tmpfs) scenarios,
> Benchmarks of the in-[tmpfs](https://en.wikipedia.org/wiki/Tmpfs) scenarios, > that tests the speed of the engine itself, showned that _libmdbx_ 10-20% faster than _LMDB_,
> that tests the speed of the engine itself, showned that _libmdbx_ 10-20% faster than _LMDB_, > and up to 30% faster when _libmdbx_ compiled with specific build options
> and up to 30% faster when _libmdbx_ compiled with specific build options > which downgrades several runtime checks to be match with LMDB behaviour.
> which downgrades several runtime checks to be match with LMDB behaviour. >
> > These and other results could be easily reproduced with [ioArena](https://github.com/pmwkaa/ioarena) just by `make bench-quartet` command,
> These and other results could be easily reproduced with [ioArena](https://github.com/pmwkaa/ioarena) just by `make bench-quartet` command, > including comparisons with [RockDB](https://en.wikipedia.org/wiki/RocksDB)
> including comparisons with [RockDB](https://en.wikipedia.org/wiki/RocksDB) > and [WiredTiger](https://en.wikipedia.org/wiki/WiredTiger).
> and [WiredTiger](https://en.wikipedia.org/wiki/WiredTiger).
3. Automatic on-the-fly database size adjustment, both increment and reduction. 3. Automatic on-the-fly database size adjustment, both increment and reduction.
> _libmdbx_ manages the database size according to parameters specified
> _libmdbx_ manages the database size according to parameters specified > by `mdbx_env_set_geometry()` function,
> by `mdbx_env_set_geometry()` function, > ones include the growth step and the truncation threshold.
> ones include the growth step and the truncation threshold. >
> > Unfortunately, on-the-fly database size adjustment doesn't work under [Wine](https://en.wikipedia.org/wiki/Wine_(software))
> Unfortunately, on-the-fly database size adjustment doesn't work under [Wine](https://en.wikipedia.org/wiki/Wine_(software)) > due to its internal limitations and unimplemented functions, i.e. the `MDBX_UNABLE_EXTEND_MAPSIZE` error will be returned.
> due to its internal limitations and unimplemented functions, i.e. the `MDBX_UNABLE_EXTEND_MAPSIZE` error will be returned.
4. Automatic continuous zero-overhead database compactification. 4. Automatic continuous zero-overhead database compactification.
> During each commit _libmdbx_ merges a freeing pages which adjacent with the unallocated area
> During each commit _libmdbx_ merges a freeing pages which adjacent with the unallocated area > at the end of file, and then truncates unused space when a lot enough of.
> at the end of file, and then truncates unused space when a lot enough of.
5. The same database format for 32- and 64-bit builds. 5. The same database format for 32- and 64-bit builds.
> _libmdbx_ database format depends only on the [endianness](https://en.wikipedia.org/wiki/Endianness) but not on the [bitness](https://en.wiktionary.org/wiki/bitness).
> _libmdbx_ database format depends only on the [endianness](https://en.wikipedia.org/wiki/Endianness) but not on the [bitness](https://en.wiktionary.org/wiki/bitness).
6. LIFO policy for Garbage Collection recycling. This can significantly increase write performance due write-back disk cache up to several times in a best case scenario. 6. LIFO policy for Garbage Collection recycling. This can significantly increase write performance due write-back disk cache up to several times in a best case scenario.
> LIFO means that for reuse will be taken the latest becomes unused pages.
> LIFO means that for reuse will be taken the latest becomes unused pages. > Therefore the loop of database pages circulation becomes as short as possible.
> Therefore the loop of database pages circulation becomes as short as possible. > In other words, the set of pages, that are (over)written in memory and on disk during a series of write transactions, will be as small as possible.
> In other words, the set of pages, that are (over)written in memory and on disk during a series of write transactions, will be as small as possible. > Thus creates ideal conditions for the battery-backed or flash-backed disk cache efficiency.
> Thus creates ideal conditions for the battery-backed or flash-backed disk cache efficiency.
7. Fast estimation of range query result volume, i.e. how many items can 7. Fast estimation of range query result volume, i.e. how many items can
be found between a `KEY1` and a `KEY2`. This is a prerequisite for build be found between a `KEY1` and a `KEY2`. This is a prerequisite for build
and/or optimize query execution plans. and/or optimize query execution plans.
> _libmdbx_ performs a rough estimate based on common B-tree pages of the paths from root to corresponding keys.
> _libmdbx_ performs a rough estimate based on common B-tree pages of the paths from root to corresponding keys.
8. `mdbx_chk` utility for database integrity check. 8. `mdbx_chk` utility for database integrity check.
Since version 0.9.1, the utility supports checking the database using any of the three meta pages and the ability to switch to it. Since version 0.9.1, the utility supports checking the database using any of the three meta pages and the ability to switch to it.
@ -278,14 +271,12 @@ Since version 0.9.1, the utility supports checking the database using any of the
or not, that allows to avoid copy-out before updates. or not, that allows to avoid copy-out before updates.
12. Extended information of whole-database, sub-databases, transactions, readers enumeration. 12. Extended information of whole-database, sub-databases, transactions, readers enumeration.
> _libmdbx_ provides a lot of information, including dirty and leftover pages
> _libmdbx_ provides a lot of information, including dirty and leftover pages > for a write transaction, reading lag and holdover space for read transactions.
> for a write transaction, reading lag and holdover space for read transactions.
13. Extended update and delete operations. 13. Extended update and delete operations.
> _libmdbx_ allows one _at once_ with getting previous value
> _libmdbx_ allows one _at once_ with getting previous value > and addressing the particular item from multi-value with the same key.
> and addressing the particular item from multi-value with the same key.
14. Useful runtime options for tuning engine to application's requirements and use cases specific. 14. Useful runtime options for tuning engine to application's requirements and use cases specific.
@ -315,10 +306,9 @@ pre-opening is not needed.
4. Returning `MDBX_EMULTIVAL` error in case of ambiguous update or delete. 4. Returning `MDBX_EMULTIVAL` error in case of ambiguous update or delete.
5. Guarantee of database integrity even in asynchronous unordered write-to-disk mode. 5. Guarantee of database integrity even in asynchronous unordered write-to-disk mode.
> _libmdbx_ propose additional trade-off by `MDBX_SAFE_NOSYNC` with append-like manner for updates,
> _libmdbx_ propose additional trade-off by `MDBX_SAFE_NOSYNC` with append-like manner for updates, > that avoids database corruption after a system crash contrary to LMDB.
> that avoids database corruption after a system crash contrary to LMDB. > Nevertheless, the `MDBX_UTTERLY_NOSYNC` mode is available to match LMDB's behaviour for `MDB_NOSYNC`.
> Nevertheless, the `MDBX_UTTERLY_NOSYNC` mode is available to match LMDB's behaviour for `MDB_NOSYNC`.
6. On **MacOS & iOS** the `fcntl(F_FULLFSYNC)` syscall is used _by 6. On **MacOS & iOS** the `fcntl(F_FULLFSYNC)` syscall is used _by
default_ to synchronize data with the disk, as this is [the only way to default_ to synchronize data with the disk, as this is [the only way to
@ -387,14 +377,12 @@ since release the version 1.0.
_libmdbx_ provides two official ways for integration in source code form: _libmdbx_ provides two official ways for integration in source code form:
1. Using the amalgamated source code. 1. Using the amalgamated source code.
> The amalgamated source code includes all files required to build and
> The amalgamated source code includes all files required to build and > use _libmdbx_, but not for testing _libmdbx_ itself.
> use _libmdbx_, but not for testing _libmdbx_ itself.
2. Adding the complete original source code as a `git submodule`. 2. Adding the complete original source code as a `git submodule`.
> This allows you to build as _libmdbx_ and testing tool.
> This allows you to build as _libmdbx_ and testing tool. > On the other hand, this way requires you to pull git tags, and use C++11 compiler for test tool.
> On the other hand, this way requires you to pull git tags, and use C++11 compiler for test tool.
_**Please, avoid using any other techniques.**_ Otherwise, at least _**Please, avoid using any other techniques.**_ Otherwise, at least
don't ask for support and don't name such chimeras `libmdbx`. don't ask for support and don't name such chimeras `libmdbx`.