docs/btree: Describe page caching policy of the underlying implementation.

This commit is contained in:
Paul Sokolovsky 2017-09-17 21:34:34 +03:00
parent 75163325ae
commit 72491b3e40
1 changed files with 11 additions and 7 deletions

View File

@ -76,20 +76,24 @@ Example::
Functions
---------
.. function:: open(stream, \*, flags=0, cachesize=0, pagesize=0, minkeypage=0)
.. function:: open(stream, \*, flags=0, pagesize=0, cachesize=0, minkeypage=0)
Open a database from a random-access `stream` (like an open file). All
other parameters are optional and keyword-only, and allow to tweak advanced
parameters of the database operation (most users will not need them):
* *flags* - Currently unused.
* *cachesize* - Suggested maximum memory cache size in bytes. For a
board with enough memory using larger values may improve performance.
The value is only a recommendation, the module may use more memory if
values set too low.
* *pagesize* - Page size used for the nodes in BTree. Acceptable range
is 512-65536. If 0, underlying I/O block size will be used (the best
compromise between memory usage and performance).
is 512-65536. If 0, a port-specific default will be used, optimized for
port's memory usage and/or performance.
* *cachesize* - Suggested memory cache size in bytes. For a
board with enough memory using larger values may improve performance.
Cache policy is as follows: entire cache is not allocated at once;
instead, accessing a new page in database will allocate a memory buffer
for it, until value specified by *cachesize* is reached. Then, these
buffers will be managed using LRU (least recently used) policy. More
buffers may still be allocated if needed (e.g., if a database contains
big keys and/or values). Allocated cache buffers aren't reclaimed.
* *minkeypage* - Minimum number of keys to store per page. Default value
of 0 equivalent to 2.