.

wcfs/__init__.py

@@ -48,10 +48,14 @@ from ZODB.utils import u64, p64
 from zodbtools.util import ashex
 
 
-# WCFS represents connection to wcfs server.
+# WCFS represents filesystem-level connection to wcfs server.
 #
 # It has to be created with join.
 # Only 1 connection is maintained for one file server.
+#
+# 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.
 class WCFS(object):
     # .mountpoint   path to wcfs mountpoint
     # ._fwcfs       /.wcfs/zurl opened to keep the server from going away (at least cleanly)
@@ -61,6 +65,22 @@ class WCFS(object):
     # ._proc        wcfs process if it was opened by this WCFS | None
     pass
 
+# Conn represents logical connection viewing data on wcfs server as of
+# particular database state.
+#
+# It uses /head/bigfile/* and notifications received from /head/watch to
+# maintain isolated database view while at the same time sharing most of data
+# cache in OS pagecache of /head/bigfile/*.
+#
+# XXX wc conn <-> zconn
+class Conn(object):
+    # ._wc      WCFS
+    # .at       Tid
+    pass
+
+
+# XXX WatchLink
+# XXX Watch
 
 """
     # open creates wcfs file handle, which can be mmaped to give data of ZBigFile.
@@ -121,6 +141,7 @@ def __init__(wc, mountpoint, fwcfs, proc):
     wc._njoin     = 1
     wc._proc      = proc
 
+# close must be called to release joined connection after it is no longer needed.
 @func(WCFS)
 def close(wc):
     with _wcmu: