.

wcfs/wcfs_test.py

@@ -162,19 +162,18 @@ class DFile:
 
 # tDB provides database/wcfs testing environment.
 #
-# BigFiles opened under tDB are represented as tFile - see .open for details.
-# Watches opened under tDB are represented as tWatchLink - see .openwatch for details.
+# Database root and wcfs connection are represented by .root and .wc correspondingly
 #
-# XXX .root + .wc
+# The primary way to access wcfs is by opening BigFiles and Watches.
+# A BigFile opened under tDB is represented as tFile - see .open for details.
+# A Watche  opened under tDB is represented as tWatchLink - see .openwatch for details.
 #
-# XXX .change + .commit
-# XXX .dFtail + .head
-#     + .iter_revv
+# The database can be mutated (via !wcfs path) with .change + .commit .
+# Current database head is represented by .head .
+# The history of the changes is kept in .dFtail .
+# There are various helpers to query history (.iter_revv, _blkData, _pinAt, ...)
 #
-# XXX .open         -> .topen
-# XXX .openwatch    -> .topenwatch ?
-#
-# XXX .close
+# tDB must be explicitly closed once no longer used.
 #
 # XXX .path/.read/.stat/._open
 #
@@ -334,53 +333,6 @@ class tDB:
         return open(path, mode, 0)  # unbuffered
 
 
-    # iter_revv iterates through all possible at_i -> at_j -> at_k ... sequences.
-    # at_i < at_j       NOTE all sequences go till head.
-    def iter_revv(t, start=z64, level=0):
-        dFtail = [_ for _ in t.dFtail if _.rev > start]
-        #print(' '*level, 'iter_revv', t.hat(start), [t.hat(_.rev) for _ in dFtail])
-        if len(dFtail) == 0:
-            yield []
-            return
-
-        for dF in dFtail:
-            #print(' '*level, 'QQQ', t.hat(dF.rev))
-            for tail in t.iter_revv(start=dF.rev, level=level+1):
-                #print(' '*level, 'zzz', tail)
-                yield ([dF.rev] + tail)
-
-    # _blkData returns expected zf[blk] data and revision as of @at database state.
-    #
-    # If the block is hole - (b'', at0) is returned.  XXX -> @z64?
-    # XXX ret for when the file did not existed at all? blk was after file size?
-    def _blkData(t, zf, blk, at): # -> (data, rev)
-        if at is None:
-            at = t.head
-
-        # XXX dup wrt _pinAt
-
-        # all changes to zf
-        vdf = [_.byfile[zf] for _ in t.dFtail if zf in _.byfile]
-
-        # changes to zf[blk] <= at
-        blkhistoryat = [_ for _ in vdf if blk in _.ddata and _.rev <= at]
-        if len(blkhistoryat) == 0:
-            # blk did not existed @at       # XXX verify whether file was existing at all
-            data = b''
-            rev  = t.dFtail[0].rev  # was hole - at0    XXX -> pin to z64
-        else:
-            _ = blkhistoryat[-1]
-            data = _.ddata[blk]
-            rev  = _.rev
-            assert rev <= at
-
-        return data, rev
-
-    # _blkRev returns expected zf[blk] revision as of @at database state.
-    def _blkRev(t, zf, blk, at): # -> rev
-        _, rev = t._blkData(zf, blk, at)
-        return rev
-
     # XXX vvv -> not what we need, think again
     # _blkHeadAccessed returns whether block state corresponding to zf[blk] at
     # current head was accessed.
@@ -897,7 +849,57 @@ class tSrvReq:
     def at(req):      return req._parse()[2]
 
 
-# ---- watch setup/adjust ----
+# ---- query dFtail/accessed ----
+
+# iter_revv iterates through all possible at_i -> at_j -> at_k ... sequences.
+# at_i < at_j       NOTE all sequences go till head.
+@func(tDB)
+def iter_revv(t, start=z64, level=0):
+    dFtail = [_ for _ in t.dFtail if _.rev > start]
+    #print(' '*level, 'iter_revv', t.hat(start), [t.hat(_.rev) for _ in dFtail])
+    if len(dFtail) == 0:
+        yield []
+        return
+
+    for dF in dFtail:
+        #print(' '*level, 'QQQ', t.hat(dF.rev))
+        for tail in t.iter_revv(start=dF.rev, level=level+1):
+            #print(' '*level, 'zzz', tail)
+            yield ([dF.rev] + tail)
+
+# _blkData returns expected zf[blk] data and revision as of @at database state.
+#
+# If the block is hole - (b'', at0) is returned.  XXX -> @z64?
+# XXX ret for when the file did not existed at all? blk was after file size?
+@func(tDB)
+def _blkData(t, zf, blk, at): # -> (data, rev)
+    if at is None:
+        at = t.head
+
+    # XXX dup wrt _pinAt
+
+    # all changes to zf
+    vdf = [_.byfile[zf] for _ in t.dFtail if zf in _.byfile]
+
+    # changes to zf[blk] <= at
+    blkhistoryat = [_ for _ in vdf if blk in _.ddata and _.rev <= at]
+    if len(blkhistoryat) == 0:
+        # blk did not existed @at       # XXX verify whether file was existing at all
+        data = b''
+        rev  = t.dFtail[0].rev  # was hole - at0    XXX -> pin to z64
+    else:
+        _ = blkhistoryat[-1]
+        data = _.ddata[blk]
+        rev  = _.rev
+        assert rev <= at
+
+    return data, rev
+
+# _blkRev returns expected zf[blk] revision as of @at database state.
+@func(tDB)
+def _blkRev(t, zf, blk, at): # -> rev
+    _, rev = t._blkData(zf, blk, at)
+    return rev
 
 # _pinAt returns which blocks needs to be pinned for zf@at compared to zf@head
 # according to wcfs invalidation protocol.
@@ -932,6 +934,8 @@ def _pinAt(t, zf, at):  # -> pin = {} blk -> rev
 
     return pin
 
+# ---- watch setup/adjust ----
+
 # watch sets up or adjusts a watch for file@at.
 #
 # During setup it verifies that wcfs sends correct initial pins.