.

wcfs/internal/zdata/δftail.go

@@ -19,8 +19,46 @@
 
 package zdata
 
-// XXX note about ΔFtail organization: queries results are built on the fly to
-// avoid complexity of recomputing vδF on tracking set change.
+// ΔFtail provides ZBigFile-level history tail.
+//
+// It translates ZODB object-level changes to information about which blocks of
+// which ZBigFile were modified, and provides service to query that information.
+// See ΔFtail class documentation for details.
+//
+//
+// ΔFtail organization
+//
+// ΔFtail leverages
+//
+//	- ΔBtail to track changes to ZBigFile.blktab BTree, and
+//	- ΔZtail to track changes to ZBlk objects and to ZBigFile object itself.
+//
+// then every query merges ΔBtail and ΔZtail data on the fly to provide
+// ZBigFile-level result.
+//
+// Merging on the fly, contrary to computing and maintaining vδF data, is done
+// to avoid complexity of recomputing vδF when tracking set changes. Most of
+// ΔFtail complexity is, thus, located in ΔBtail, which implements BTree diff
+// and handles complexity of recomputing vδB when set of tracked blocks
+// changes.
+//
+// Changes to ZBigFile object indicate epochs. Epochs could be
+//
+//	- file creation or deletion,
+//	- change of ZBigFile.blksize,
+//	- change of ZBigFile.blktab to point to another BTree.
+//
+// Epochs represent major changes to file history where file is assumed to
+// change so dramatically, that practically it can be considered to be a
+// "whole" change. In particular, WCFS, upon seeing a ZBigFile epoch,
+// invalidates all data in corresponding OS-level cache for the file.
+//
+// The only historical data, that ΔFtail maintains by itself, is history of
+// epochs. That history does not need to be recomputed when more blocks become
+// tracked and is thus easy to maintain. It also can be maintained only in
+// ΔFtail because ΔBtail and ΔZtail does not "know" anything about ZBigFile.
+//
+// XXX concurrency
 
 import (
 	"context"
@@ -78,7 +116,7 @@ type setOid = set.Oid
 //		.rev↑
 //		{}blk | EPOCH
 //
-// XXX concurrent use
+// XXX concurrent use.
 //
 // See also zodb.ΔTail and xbtree.ΔBtail
 type ΔFtail struct {