X wcfs/client: Package overview (draft)

wcfs/client/_wcfs.pxd

@@ -23,7 +23,7 @@
 
 # Package _wcfs provides Python-wrappers for C++ wcfs client package.
 #
-# It wraps WCFS/Conn/FileH/Mapping and WatchLink to help wcfs_test.py unit-test
+# It wraps WCFS/Conn/FileH/Mapping and WatchLink to help client_test.py unit-test
 # WCFS base-layer mmap functionality. At functional level WCFS client (and especially
 # pinner) is verified when running wendelin.core array tests in wcfs mode.
 

wcfs/client/wcfs.h

@@ -19,7 +19,33 @@
 
 // Package wcfs provides WCFS client integrated with user-space virtual memory manager.
 //
-// XXX view service provided
+// This client package takes care about WCFS isolation protocol details and
+// provides to clients simple interface to isolated file data similar to
+// regular files: given a particular revision of database @at, it provides
+// synthetic read-only bigfile mappings with data corresponding to @at state,
+// but using /head/bigfile/* most of the time to build and maintain the mappings.
+//
+// For its data a mapping to bigfile X mostly reuses kernel cache for
+// /head/bigfile/X with amount of data not associated with kernel cache for
+// /head/bigfile/X being proportional to δ(bigfile/X, at..head). In the usual
+// case where many client workers simultaneously serve requests, their database
+// views are a bit outdated, but close to head, which means that in practice
+// the kernel cache for /head/bigfile/* is being used almost 100% of the time.
+//
+// A mapping for bigfile X @at is built from OS-level memory mapping of on-WCFS
+// files as
+//
+//	                                     ___        /@revA/bigfile/X
+//	   __                                           /@revB/bigfile/X
+//	          _                                     /@revC/bigfile/X
+//	                      +                         ...
+//	───  ───── ──────────────────────────   ─────	/head/bigfile/X
+//
+// where @revR mmaps are being dynamically added/removed by this client package
+// to maintain X@at data view according to WCFS invalidation protocol(*).
+//
+//
+// API overview
 //
 //  - `WCFS` represents filesystem-level connection to wcfs server.
 //  - `Conn` represents logical connection that provides view of data on wcfs
@@ -27,8 +53,21 @@
 //  - `FileH` represent isolated file view under Conn.
 //  - `Mapping` represents one memory mapping of FileH.
 //
-// XXX text
-// XXX provides isolated view.
+//
+// Integration with wendelin.core virtmem layer
+//
+// This client package can be used standalone, but additionally provides
+// integration with wendelin.core userspace virtual memory manager: when a
+// Mapping is created it can be associated as serving base layer for a
+// particular virtmem VMA via FileH.mmap(vma=...). In that case, since virtmem
+// itself adds another layer of dirty pages over read-only base provided by
+// Mapping(+), the Mapping will interact with virtmem layer to coordinate
+// mapping memory updates.
+//
+// --------
+//
+// (*) see wcfs.go documentation for overview and details of WCFS isolation protocol.
+// (+) Mapping is already 2-layer as depicted above.
 
 #ifndef _NXD_WCFS_H_
 #define _NXD_WCFS_H_