.

bigfile/file_zodb.py

@@ -26,9 +26,9 @@ This way only regular ZODB objects - not blobs - are used, and whenever file
 data is changed, δ(ZODB) is proportional to δ(data).
 
 Being BigFile ZBigFile can be memory-mapped. Created mappings provide lazy
-on-access block loading and dirtying. This way ZBigFile larger than RAM can be
-accessed transparently as if it was a regular array in RAM. Changes made to
-ZBigFile data will be either saved or discarded depending on current
+on-read block loading and on-write dirtying. This way ZBigFile larger than RAM
+can be accessed transparently as if it was a regular array in RAM. Changes made
+to ZBigFile data will be either saved or discarded depending on current
 transaction completion - commit or abort. The amount of ZBigFile changes in one
 transaction is limited by available RAM.
 
@@ -41,7 +41,12 @@ ZBigFile does not weaken ZODB ACID properties, in particular:
 API for clients
 ---------------
 
-    .fileh_open()   -> open new BigFileH-like object which can be mmaped
+API for clients is ZBigFile class and its .fileh_open() method:
+
+    .fileh_open()   -> opens new BigFileH-like object which can be mmaped
+
+The primary user of ZBigFile is ZBigArray (see bigarray/__init__.py and
+bigarray/array_zodb.py), but ZBigFile itself can be used directly too.
 
 
 Operating mode
@@ -51,9 +56,9 @@ Two operating modes are provided: "local-cache" and "shared-cache".
 
 Local-cache is the mode wendelin.core was originally implemented with in 2014.
 In this mode ZBigFile data is loaded from ZODB directly via current ZODB connection.
-It was relatively straight-forward to implement, but cached file data becomes
+It was relatively straight-forward to implement, but cached file data become
 duplicated in between ZODB connections of current process and in between
-several ZODB processes.
+several client processes that use ZODB.
 
 In shared-cache mode file's data is accessed through special filesystem for
 which data cache is centrally maintained by OS kernel. This mode was added in
@@ -64,16 +69,24 @@ see wcfs/wcfs.go which describes the filesystem and shared-cache mode in detail.
 The mode of operation can be selected via environment variable::
 
   $WENDELIN_CORE_VIRTMEM
-      rw:uvmm         local-cache   (i.e. !wcfs)    (default)
-      r:wcfs+w:uvmm   shared-cache  (i.e.  wcfs)
+      rw:uvmm           local-cache     (i.e. !wcfs)    (default)
+      r:wcfs+w:uvmm     shared-cache    (i.e.  wcfs)
 
 
 Data format
 -----------
 
-$WENDELIN_CORE_ZBLK_FMT
-    ZBlk0
-    ZBlk1
+Due to weakness of current ZODB storage servers, wendelin.core cannot provide
+at the same time both fast reads and small database size growth on small data
+changes. "Small" here means something like 1-10000 bytes as larger changes
+become comparable to 2M block size and are handled efficiently out of the box.
+Until the problem is fixed on ZODB server side, users have to explicitly
+indicate via environment variable that their workload is "small changes" if
+they prefer to prioritize database size over access speed::
+
+  $WENDELIN_CORE_ZBLK_FMT
+      ZBlk0             fast reads      (default)
+      ZBlk1             small changes
 
 
 To represent BigFile as ZODB objects, each file block is represented separately