.

wcfs/internal/xbtree/treediff.go

@@ -34,57 +34,29 @@ package xbtree
 //
 // BTree diff algorithm
 //
-// The central part of BTree-diff algorithm is in diffT and diffB.
+// diffT, diffB and δMerge constitute the diff algorithm implementation.
+// diff(A,B) works on pair of A and B whole key range splitted into regions
+// covered by tree nodes. The splitting represents current state of recursion
+// into corresponding tree. If a node in particular key range is Bucket, that
+// bucket contributes to δ- in case of A, and to δ+ in case of B. If a node in
+// particular key range is Tree, the algorithm may want to expand that tree
+// node into its children and to recourse into children.
 //
+// There are two phases:
 //
-// FIXME the algorithm is different: recursion is implemented by expanding rangeSplit step by step.
+// - Phase 1 expands A top->down driven by δZTC, adds reached buckets to δ-,
+//   and queues key regions of those buckets to be processed on B.
 //
-// δ(BTree) notes
-// ==============
+// - Phase 2 starts processing from queued key regions, expands them on B and
+//   adds reached buckets to δ+. Then it iterates to reach consistency in between
+//   A and B because processing buckets on B side may increase δ key coverage,
+//   and so corresponding key ranges has to be again processed on A. Which in
+//   turn may increase δ key coverage again, and needs to be processed on B side,
+//   etc...
 //
-// input: BTree, (@new, []oid)  ->  find out δ(BTree) i.e. {-k(v), +k'(v'), ...}
+// The final δ is merge of δ- and δ+.
 //
-// - oid ∈ Bucket
-// - oid ∈ BTree
-//
-// Bucket:
-//
-//      old = {k  -> v}
-//      new = {k' -> v'}
-//
-//      Δ = -k(v), +k(v), ...
-//
-// => for all buckets
-//
-//      Δ accumulates to []δk(v)[n+,n-]  n+ ∈ {0,1}, n- ∈ {0,1}, if n+=n- - cancel
-//
-//
-// BTree:
-//
-//      old = {k  -> B}   or {k  -> T}
-//      new = {k' -> B'}  or {k' -> T'}
-//
-//      Δ = -k(B), +k(B), -k(T), +K(T), ...
-//
-// we translate (in top-down order):
-//
-//      k(B) -> {} of k(v)
-//      k(T) -> {} of k(B) -> {} of k(v)
-//
-// which gives
-//
-//      Δ = k(v), +k(v), ...
-//
-// i.e. exactly as for buckets and it accumulates to global Δ.
-//
-// The globally-accumulated Δ is the answer for δ(BTree, (@new, []oid))
-//
-// top-down order is obtained via toposort({oid}) wrt visited PathSet.
-//
-// δ(BTree) in wcfs context:
-//
-// . -k(blk) -> invalidate #blk
-// . +k(blk) -> invalidate #blk (e.g. if blk was previously read as hole)
+// diffT has more detailed explanation of phase 1 and phase 2 logic.
 
 import (
 	"context"