.

wcfs/internal/xbtree/δbtail.go

@@ -53,12 +53,12 @@ package xbtree
 // traversal also belongs to the set.
 //
 // A new Track request potentially grows tracked keys coverage. Due to this,
-// ΔBtail needs to recompute potentially whole vδT of the affected tree. This
-// recomputation is managed by "rebuild..." family of functions and uses the
-// same treediff algorithm, that Update is using, but modulo PPTreeSubSet
-// corresponding to δ key coverage. Update also potentially needs to rebuild
-// whole vδT history, not only append new δT, because a change to tracked tree
-// nodes can result in growth of tracked key coverage.
+// on a query, ΔBtail needs to recompute potentially whole vδT of the affected
+// tree. This recomputation is managed by "vδTSnapForTracked*" and "_rebuild"
+// functions and uses the same treediff algorithm, that Update is using, but
+// modulo PPTreeSubSet corresponding to δ key coverage. Update also potentially
+// needs to rebuild whole vδT history, not only append new δT, because a
+// change to tracked tree nodes can result in growth of tracked key coverage.
 //
 // Queries are relatively straightforward code that work on vδT snapshot. The
 // main complexity, besides BTree-diff algorithm, lies in recomputing vδT when
@@ -68,6 +68,16 @@ package xbtree
 //
 // Concurrency
 //
+// In order to allow multiple Track and queries requests to be served in
+// parallel ΔBtail employs special organization of vδT rebuild process:
+//
+// 1. vδT is managed under read-copy-update (RCU) discipline: before making
+//    any vδT change the mutator atomically clones whole vδT and applies the
+//    change to the clone. This way a query, once it retrieves vδT snapshot,
+//    does not need to further synchronize with vδT mutators.
+//
+// 2.
+//
 // trackSet, ktrackNew, krebuildJobs + explain rebuild algo (query lock, check ktrackNew, krebuildJob, go/merge/...)
 //
 // XXX queries work on vδT snapshot. When updated, vδT is modified via RCU ...