X "Invalidation protocol" -> "Isolation protocol"

wcfs/internal/wcfs_watchlink.cpp

@@ -361,7 +361,7 @@ error _WatchLink::recvReq(context::Context ctx, PinReq *prx) {
     return E(_parsePinReq(prx, &pkt));
 }
 
-// _parsePinReq parses message into PinReq according to wcfs invalidation protocol.
+// _parsePinReq parses message into PinReq according to wcfs isolation protocol.
 static error _parsePinReq(PinReq *pin, const rxPkt *pkt) {
     //printf("parse pinreq: stream=%lu msg='%s'\n", pkt->stream, &pkt->data[0]);
     pin->stream = pkt->stream;

wcfs/internal/wcfs_watchlink.h

@@ -65,7 +65,7 @@ static_assert(sizeof(rxPkt) == 256, "rxPkt miscompiled");   // NOTE 128 is too l
 //
 // It is created by WCFS::_openwatch().
 //
-// .sendReq()/.recvReq() provides raw IO in terms of wcfs invalidation protocol messages.
+// .sendReq()/.recvReq() provides raw IO in terms of wcfs isolation protocol messages.
 // .close() closes the link.
 //
 // It is safe to use WatchLink from multiple threads simultaneously.
@@ -75,7 +75,7 @@ class _WatchLink : public object {
     os::File        _f;      // head/watch file handle
     string          _rxbuf;  // buffer for read data from _f
 
-    // inv.protocol message IO
+    // iso.protocol message IO
     chan<rxPkt>     _acceptq;   // server originated messages go here
     sync::Mutex     _rxmu;
     bool            _rxdown;

wcfs/todo.dot

@@ -4,7 +4,7 @@ digraph {
 		ordering=in;
 
 		wcfs		[label="wcfs"]
-		invProto	[label="open/invalidation\nprotocol", style=filled fillcolor=grey95]
+		invProto	[label="open/isolation\nprotocol", style=filled fillcolor=grey95]
 		client		[label="client", style=filled fillcolor=grey97]
 
 		wcfs	-> invProto;

wcfs/todo.svg

@@ -18,15 +18,15 @@
 <!-- invProto -->
 <g id="node2" class="node">
 <title>invProto</title>
-<ellipse fill="#f2f2f2" stroke="#000000" cx="1070.2046" cy="-389.3036" rx="78.4777" ry="26.7407"/>
-<text text-anchor="middle" x="1070.2046" y="-393.1036" font-family="Times,serif" font-size="14.00" fill="#000000">open/invalidation</text>
+<ellipse fill="#f2f2f2" stroke="#000000" cx="1070.2046" cy="-389.3036" rx="65.5227" ry="26.7407"/>
+<text text-anchor="middle" x="1070.2046" y="-393.1036" font-family="Times,serif" font-size="14.00" fill="#000000">open/isolation</text>
 <text text-anchor="middle" x="1070.2046" y="-378.1036" font-family="Times,serif" font-size="14.00" fill="#000000">protocol</text>
 </g>
 <!-- wcfs&#45;&gt;invProto -->
 <g id="edge1" class="edge">
 <title>wcfs&#45;&gt;invProto</title>
-<path fill="none" stroke="#000000" d="M902.6265,-389.3036C928.9401,-389.3036 955.2537,-389.3036 981.5674,-389.3036"/>
-<polygon fill="#000000" stroke="#000000" points="981.6524,-392.8037 991.6523,-389.3036 981.6523,-385.8037 981.6524,-392.8037"/>
+<path fill="none" stroke="#000000" d="M902.6265,-389.3036C933.1106,-389.3036 963.5948,-389.3036 994.079,-389.3036"/>
+<polygon fill="#000000" stroke="#000000" points="994.4171,-392.8037 1004.4171,-389.3036 994.417,-385.8037 994.4171,-392.8037"/>
 </g>
 <!-- liveCacheControl -->
 <g id="node4" class="node">
@@ -101,8 +101,8 @@
 <!-- invProto&#45;&gt;client -->
 <g id="edge2" class="edge">
 <title>invProto&#45;&gt;client</title>
-<path fill="none" stroke="#000000" d="M1159.0843,-389.3036C1179.5479,-389.3036 1200.0114,-389.3036 1220.475,-389.3036"/>
-<polygon fill="#000000" stroke="#000000" points="1159.0386,-385.8037 1149.0386,-389.3036 1159.0385,-392.8037 1159.0386,-385.8037"/>
+<path fill="none" stroke="#000000" d="M1146.4748,-389.3036C1171.0624,-389.3036 1195.6499,-389.3036 1220.2374,-389.3036"/>
+<polygon fill="#000000" stroke="#000000" points="1146.312,-385.8037 1136.312,-389.3036 1146.312,-392.8037 1146.312,-385.8037"/>
 </g>
 <!-- client&#45;&gt;wcfsRead -->
 <g id="edge25" class="edge">

wcfs/wcfs.go

@@ -31,12 +31,14 @@
 // head/bigfile/<bigfileX> which represents always latest bigfile data.
 // Clients that want to get isolation guarantee should subscribe for
 // invalidations and re-mmap invalidated regions to file with pinned bigfile revision for
-// the duration of their transaction. See "Invalidation protocol" for details.
+// the duration of their transaction. See "Isolation protocol" for details.
 //
 // In the usual situation when bigfiles are big, and there are O(1)/δt updates,
 // there should be no need for any cache besides shared kernel cache of latest
 // bigfile data.
 //
+// XXX reference to wcfs client library.
+//
 //
 // Filesystem organization
 //
@@ -68,7 +70,7 @@
 // /at describes precisely ZODB state for which bigfile data is currently
 // exposed. Whenever bigfile data is changed in upstream ZODB, information
 // about the changes is first propagated to /watch, and only after that
-// /bigfile/<bigfileX> is updated. See "Invalidation protocol" for details.
+// /bigfile/<bigfileX> is updated. See "Isolation protocol" for details.
 //
 // @<revX>/ has the following structure:
 //
@@ -85,9 +87,9 @@
 // wcfs filesystem. Similarly @<revX>/ become visible only after access.
 //
 //
-// Invalidation protocol	XXX -> "Isolation protocol"
+// Isolation protocol
 //
-// In order to support isolation, wcfs implements invalidation protocol that
+// In order to support isolation, wcfs implements isolation protocol that
 // must be cooperatively followed by both wcfs and client.
 //
 // First, client mmaps latest bigfile, but does not access it
@@ -125,9 +127,7 @@
 // head/watch links to clients, that had requested it (separately to each
 // client), about the changes:
 //
-//	S: <2·k> pin <bigfileX> #<blk> @<rev_max>
-//	XXX @head means unpin.
-//	XXX -> use `unpin <bigfileX> #<blk>`
+//	S: <2·k> pin <bigfileX> #<blk> @<rev_max>	; @head means unpin
 //
 // and waits until all clients confirm that changed file block can be updated
 // in global OS cache.
@@ -137,7 +137,9 @@
 //	# mmapped at address corresponding to #blk
 //	mmap(@<rev_max>/bigfile/<bigfileX>, #blk, MAP_FIXED)
 //
-// XXX unpin -> mmap(head/bigfile/<bigfileX>, #blk, MAP_FIXED)
+// or, if given @head as @<rev_max>, to bigfile@head
+//
+//	mmap(head/bigfile/<bigfileX>, #blk, MAP_FIXED)
 //
 // and must send ack back to the server when it is done:
 //
@@ -185,7 +187,7 @@
 //
 // The problem could be avoided, if wcfs would reside inside OS kernel and this
 // way could be able to manipulate clients address space directly (then
-// invalidation protocol won't be needed). It is also possible to imagine
+// isolation protocol won't be needed). It is also possible to imagine
 // mechanism, where wcfs would synchronously change clients' address space via
 // injecting trusted code and running it on client side via ptrace to adjust
 // file mappings.
@@ -379,7 +381,7 @@ package main
 //
 //	  watch.pin(file, #blk, @rev)
 //
-//	sends pin message according to "Invalidation protocol", and is assumed
+//	sends pin message according to "Isolation protocol", and is assumed
 //	to cause
 //
 //	  remmap(file, #blk, @rev/bigfile/file)
@@ -669,7 +671,7 @@ type Watch struct {
 	// atMu, similarly to zheadMu, protects watch.at and pins associated with Watch.
 	// atMu.R guarantees that watch.at is not changing, but multiple
 	//        simultaneous pins could be running (used e.g. by readPinWatchers).
-	// atMu.W guaraneees that only one user has watch.at write access and
+	// atMu.W guarantees that only one user has watch.at write access and
 	//        that no pins are running (used by setupWatch).
 	atMu sync.RWMutex
 	at   zodb.Tid               // requested to be watched @at
@@ -1324,7 +1326,7 @@ retry:
 	log.Errorf("BUG: bigfile %s: blk %d: -> pagecache: %s  (ignoring, but reading from bigfile will be very slow)", oid, blk, st)
 }
 
-// -------- invalidation protocol notification/serving --------
+// -------- isolation protocol notification/serving --------
 //
 // (see "7.2) for all registered client@at watchers ...")
 
@@ -1554,7 +1556,7 @@ func (wlink *WatchLink) setupWatch(ctx context.Context, foid zodb.Oid, at zodb.T
 		bfdir.fileMu.Unlock()
 		if f == nil {
 			wlink.byfileMu.Unlock()
-			// by "invalidation protocol" watch is setup after data file was opened
+			// by "isolation protocol" watch is setup after data file was opened
 			return fmt.Errorf("file not yet known to wcfs or is not a ZBigFile")
 		}
 
@@ -1671,7 +1673,7 @@ func (wlink *WatchLink) setupWatch(ctx context.Context, foid zodb.Oid, at zodb.T
 
 	// downgrade atMu.W -> atMu.R to let other clients to access the file.
 	// XXX there is no primitive to do Wlock->Rlock atomically, but we are
-	// ok with that since we prepared eveyrhing to handle simultaneous pins
+	// ok with that since we prepared everything to handle simultaneous pins
 	// from other reads.
 	w.atMu.Unlock()
 	w.atMu.RLock()
@@ -1832,7 +1834,7 @@ func (wlink *WatchLink) _serve() (err error) {
 
 		// client-initiated request
 
-		// bye		TODO document in "Invalidation protocol"
+		// bye		TODO document in "Isolation protocol"
 		if msg == "bye" {
 			return nil // deferred sk.Close will wake-up rx on client side
 		}

wcfs/wcfs_test.py

@@ -1030,7 +1030,7 @@ def _blkRevAt(t, zf, blk, at): # -> rev
 
 
 # _pinnedAt returns which blocks needs to be pinned for zf@at compared to zf@head
-# according to wcfs invalidation protocol.
+# according to wcfs isolation protocol.
 #
 # Criteria for when blk must be pinned as of @at view:
 #
@@ -1073,7 +1073,7 @@ def iter_revv(t, start=z64, level=0):
 # -------------------------------------
 # ---- actual tests to access data ----
 
-# exercise wcfs functionality without wcfs invalidation protocol.
+# exercise wcfs functionality without wcfs isolation protocol.
 # plain data access + wcfs handling of ZODB invalidations.
 @func
 def test_wcfs_basic():