From 72491b3e40db75e7edf5831e8914a1ca5c8e9937 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 17 Sep 2017 21:34:34 +0300 Subject: [PATCH] docs/btree: Describe page caching policy of the underlying implementation. --- docs/library/btree.rst | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/library/btree.rst b/docs/library/btree.rst index 9322d32e6a..8fac67e8d4 100644 --- a/docs/library/btree.rst +++ b/docs/library/btree.rst @@ -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.