.

wcfs/notes.txt

@@ -6,6 +6,24 @@ This file contains notes additional to usage documentation and internal
 organization overview in wcfs.go .
 
 
+Invalidations to wcfs clients are delayed until they read
+=========================================================
+
+Initially it was planned that wcfs would send invalidation messages to its
+clients right after receiving invalidation message from ZODB at transaction
+boundary time. That simplifies logic but requires that for a particular file,
+wcfs has to send to clients whole range of where the file was changed.
+
+Emitting whole δR right at transaction-boundary time requires to keep whole
+ZBigFile.blktab index in RAM. Even though from space point of view it is
+somewhat acceptable (~ 0.01% of whole-file data size, i.e. ~ 128MB of index for
+~ 1TB of data), it is not good from time overhead point of view - initial open
+of a file this way would be potentially very slow.
+
+-> we took the approach where we invalidate a block lazily only when it is
+actually accesses.
+
+
 Changing mmapping while under pagefault is possible
 ===================================================
 

wcfs/wcfs.go

@@ -224,7 +224,7 @@ package main
 // Wcfs organization
 //
 // Wcfs is a ZODB client that translates ZODB objects into OS files as would
-// non-wcfs wendelin.core do for a ZBigFile. Contrary to non-wcfs wendelin.core
+// non-wcfs wendelin.core do for a ZBigFile. Contrary to non-wcfs wendelin.core,
 // it keeps bigfile data in shared cache efficiently. It is organized as follows:
 //
 // 1) 1 ZODB connection for "latest data" for whole filesystem (zhead).
@@ -262,7 +262,7 @@ package main
 //
 //	that describes which file(s) parts needs to be invalidated.
 //
-//   4.4) for all file/blk to invalidate we do:
+//    4.4) for all file/blk to invalidate we do:
 //
 //	- try to retrieve file/head/data[blk] from OS file cache;
 //	- if retrieved successfully -> store retrieved data back into OS file
@@ -277,6 +277,8 @@ package main
 //	won't be served from OS file cache and instead will trigger a FUSE read
 //	request to wcfs.
 //
+//    4.5) no invalidation messages are sent to wcfs clients at this point(*).
+//
 // 5) after OS file cache was invalidated, we resync zhead to new database
 //    view corresponding to tid.
 //
@@ -327,7 +329,7 @@ package main
 //
 //	remmapping is done synchronously via ptrace.
 //	XXX via running wcfs-trusted code wcfs injects into clients.
-//	FIXME ptrace won't work when client thread is blocked under pagefault or syscall(+).
+//	FIXME ptrace won't work when client thread is blocked under pagefault or syscall(~).
 //
 //	in order to support remmapping for each file/head/data
 //
@@ -339,23 +341,17 @@ package main
 //
 //   Thus a client that wants latest data on pagefault will get latest data,
 //   and a client that wants @rev data will get @rev data, even if it was this
-//   "old" client that triggered the pagefault(*).
+//   "old" client that triggered the pagefault(+).
 //
-// (*) see "Changing mmapping while under pagefault is possible" in notes.txt
-// (+) see "Client cannot be ptraced while under pagefault" in notes.txt
+// (*) see "Invalidations to wcfs clients are delayed until they read" in notes.txt
+// (+) see "Changing mmapping while under pagefault is possible" in notes.txt
+// (~) see "Client cannot be ptraced while under pagefault" in notes.txt
 //
 //
 // XXX mmap(@at) open
 //
-// XXX zconn(s) for historical state
-// XXX serving read from @<rev>/data
+// XXX 8) serving read from @<rev>/data + zconn(s) for historical state
 //
-// XXX(integrate place=?) emitting whole δR right at transaction-boundary time
-// requires to keep whole blktab index in tree. Even though from space point of
-// view it is somewhat acceptable (~ 0.01% of whole-file data size, i.e. ~
-// 128MB of index for ~ 1TB of data), it is not good from time overhead point
-// of view - initial open of a file this way would be potentially very slow.
-// -> we took the approach where we invalidate lazily only actual block access.
 //
 // XXX(integrate place=?) ZData - no need to keep track -> ZBlk1 is always
 // marked as changed on blk data change.

wcfs/δtail.go.in

@@ -42,8 +42,7 @@ import (
 //	- forget information in the tail past specified revision, and
 //	- query the tail about what is last revision that changed an id.
 //
-// It is generally not safe to use ΔTail from multiple goroutines simultaneously.
-// It is safe to perform multiple simultaneous read-kind operations.
+// ΔTail is safe to access for multiple-readers / single writer.
 //
 // (*) examples of id:
 //