.

wcfs/__init__.py

@@ -53,16 +53,15 @@ from six import reraise
 
 # WCFS represents filesystem-level connection to wcfs server.
 #
-# It has to be created with join.
-# Only 1 connection is maintained for one file server.
+# Use join to create it.
 #
 # The primary way to access wcfs is to open logical connection viewing on-wcfs
 # data as of particular database state, and use that logical connection to
-# create base-layer mappings. See .open and Conn for details.
+# create base-layer mappings. See .connect and Conn for details.
 #
 # Raw files on wcfs can be accessed with ._path/._read/._stat/._open .
 #
-# XXX WCFS parallels ZODB.DB .
+# WCFS logically mirrors ZODB.DB .
 class WCFS(object):
     # .mountpoint   path to wcfs mountpoint
     # ._fwcfs       /.wcfs/zurl opened to keep the server from going away (at least cleanly)
@@ -79,8 +78,9 @@ class WCFS(object):
 # maintain isolated database view while at the same time sharing most of data
 # cache in OS pagecache of /head/bigfile/*.
 #
-# XXX wc conn <-> zconn
-# XXX Conn parallels ZODB.Connection .
+# Use .mmap to create new Mappings.
+#
+# Conn logically mirrors ZODB.Connection .
 class Conn(object):
     # ._wc          WCFS
     # .at           Tid
@@ -146,7 +146,7 @@ def _pinner(wconn, ctx):
                     continue
 
                 # FIXME check if virtmem did not mapped RW page into this block already
-                mmap.mmapblk(req.blk, req.at)
+                mmap._mmapblk(req.blk, req.at)
 
             # update f.pinned
             if req.at is None:
@@ -155,12 +155,12 @@ def _pinner(wconn, ctx):
                 f.pinned[req.blk] = req.at
 
 
-# pin remmaps mapping memory for [blk] to be viewing database as of @at state.
+# _mmapblk remmaps mapping memory for file[blk] to be viewing database as of @at state.
 #
 # at=None means unpin to head/ .
 # NOTE this does not check wrt virtmem already mapped blk as RW     XXX ok?
 @func(_Mapping)
-def pin(mmap, blk, at):
+def _mmapblk(mmap, blk, at):
     assert mmap.blk_start <= blk < mmap.blk_stop
     f = mmap.file
     if at is None:
@@ -188,10 +188,10 @@ def mmap(wconn, foid, offset, size): # -> Mapping       XXX offset, size -> blko
         # create memory with head/f mapping and applied pins
         mem = mm.mmap_ro(f.headf.fileno(), offset, size)
         mmap = _Mapping(f, blk_start, mem)
-        for blk, rev in f.pin.items():  # XXX keep f.pin ↑blk and use binary search?
+        for blk, rev in f.pinned.items():  # XXX keep f.pinned ↑blk and use binary search?
             if not (blk_start <= blk && blk < blk_stop):
                 continue    # blk out of this mapping
-            mmap.mmapblk(blk, rev)
+            mmap._mmapblk(blk, rev)
 
         f.mmaps.append(mmap)    # XXX keep f.mmaps ↑blk_start
 
@@ -204,7 +204,7 @@ def remmap_blk(mmap, blk):
     # XXX locking
     assert (mmap.blk_start <= blk < mmap.blk_stop)
     blkrev = mmap.pinned.get(blk, None) # rev | @head
-    mmap.mmapblk(blk, blkrev)
+    mmap._mmapblk(blk, blkrev)
 
 
 # unmap is removes mapping memory from address space.
@@ -580,6 +580,8 @@ def _default_autostart():
 #
 # If wcfs for that zurl was already started, join connects to it.
 # Otherwise it starts wcfs for zurl if autostart is True.
+#
+# For the same zurl join returns the WCFS object.
 def join(zurl, autostart=_default_autostart()): # -> WCFS
     mntpt = _mntpt_4zurl(zurl)
     with _wcmu: