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

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.